app.utils.date_parser module¶

Date parser — handles every real-world date format found in bank CSVs and invoices.

Supported formats:: ISO: 2026-05-29 UK/EU: 29/05/2026 | 29-05-2026 | 29.05.2026 US: 05/29/2026 | 05-29-2026 Short year: 29/05/26 | 05/29/26 Month name: 29-May-2026 | 29 May 2026 | May 29, 2026 Month abbrev: 29-May-26 | May-26 Excel serial: 46044 (days since 1900-01-01) Timestamp: 2026-05-29 14:30:00 | 2026-05-29T14:30:00Z Ambiguous: 04/05/2026 → logged as warning

class app.utils.date_parser.ParsedDate(value: datetime.date, is_ambiguous: bool, is_excel_serial: bool, original: str, warning: str | None)[source]¶

Bases: object

is_ambiguous: bool¶

is_excel_serial: bool¶

original: str¶

value: date¶

warning: str | None¶

app.utils.date_parser.infer_date_format_hint(sample_dates: list[str]) → bool[source]¶: Infer dayfirst setting from a sample of date strings. If any date has a leading component > 12, it must be the day (dayfirst=True). Returns True if dayfirst is likely, False for monthfirst (US).

app.utils.date_parser.parse_date(raw: str, dayfirst: bool = True, yearfirst: bool = False) → ParsedDate | None[source]¶

Parse a raw date string into a normalized ParsedDate.

Parameters:

raw – The raw string from the CSV cell.
dayfirst – Hint for ambiguous dates like 04/05/2026 (default: True for DD/MM).
yearfirst – Hint when year comes first (e.g., Japanese format).

Returns:

ParsedDate, or None if the value is a null/missing marker.

Raises:

ValueError – If the string is non-null but unparseable.