Dateformat

Common errors

• ValueError: Invalid format string: '%Y-%m-%d'

  cause Attempting to use standard `datetime.strftime`/`strptime` format codes with `dateformat.format` or `dateformat.parse`.
  fix Replace standard `%` format codes with `dateformat`'s custom codes. For example, change `%Y-%m-%d` to `YYYY-MM-DD`.

• AttributeError: 'datetime.datetime' object has no attribute 'strftime' (when using dateformat.datetime)

  cause Trying to directly call `strftime` on a `dateformat.datetime` object or a standard `datetime` object, expecting `dateformat`'s custom formatting logic to apply.
  fix Always use `dateformat.format(your_datetime_object, 'YYYY-MM-DD')` to apply `dateformat`'s formatting logic. The `strftime` method still exists on the underlying `datetime` object but uses standard `%` codes.

• TypeError: parser() takes 2 positional arguments but 3 were given (or similar for format)

  cause Incorrect import: Trying to call `datetime.parser` or `datetime.format` when you meant `dateformat.parse` or `dateformat.format`.
  fix Ensure you are importing correctly as `from dateformat import format, parse` or calling via the main module: `dateformat.format(...)` and `dateformat.parse(...)`.

Warnings

• breaking Dateformat uses its own custom set of formatting codes (e.g., 'YYYY', 'MM', 'DD', 'HH') which are distinct from Python's standard `datetime.strftime`/`strptime` codes (e.g., '%Y', '%m', '%d', '%H'). Mixing these will lead to `ValueError` or incorrect output.
  Fix: Always refer to the `dateformat` documentation for the correct format codes. Convert `%Y` to `YYYY`, `%m` to `MM`, `%d` to `DD`, `%H` to `HH`, `%M` to `II` (for minutes), `%S` to `SS` etc.
• gotcha The `dateformat.datetime` object is a wrapper around the standard `datetime.datetime` object. While convenient, direct calls to methods like `strftime()` or `strptime()` on `dateformat.datetime` instances will behave like standard `datetime` objects and will not use `dateformat`'s custom format codes.
  Fix: For formatting and parsing with `dateformat`'s codes, always use `dateformat.format(dt_object, format_string)` and `dateformat.parse(date_string, format_string)` respectively. Do not try to call `strftime` or `strptime` directly on `dateformat.datetime` objects with custom codes.
• gotcha The project has a slow release cadence, with the last stable release (v0.9.7) in July 2022. While functional, users should not expect rapid feature development, bug fixes, or immediate support for new Python versions.
  Fix: Be aware of the project's maintenance status. For actively developed alternatives with similar features, consider libraries like `pendulum` or `arrow`, which may offer more frequent updates and broader community support.

Install

• pip install dateformat Install stable version

Imports

• format

  from dateformat import format

• parse

  from dateformat import parse

• datetime
  wrong:

  import datetime

  correct:

  from dateformat import datetime

  dateformat provides its own wrapper around the standard datetime module.

Quickstart

This example demonstrates how to use `dateformat.format` to convert a `datetime` object (either standard or `dateformat`'s wrapper) into a string, and `dateformat.parse` to convert a string into a `datetime` object, both utilizing `dateformat`'s unique format codes.

import dateformat
import datetime as std_datetime

# Get a datetime object (can be standard datetime or dateformat.datetime)
now_dt = std_datetime.datetime.now()

# Format a datetime object using dateformat's codes
formatted_date = dateformat.format(now_dt, "YYYY-MM-DD HH:MM:SS")
print(f"Formatted: {formatted_date}")

# Parse a date string using dateformat's codes
date_string = "2023-10-27 14:35:01"
parsed_dt = dateformat.parse(date_string, "YYYY-MM-DD HH:MM:SS")
print(f"Parsed: {parsed_dt}")

# Using dateformat's own datetime wrapper
df_now = dateformat.datetime.now()
formatted_df_now = dateformat.format(df_now, "Do MMMM YYYY")
print(f"Formatted (df.dt): {formatted_df_now}")