Date Utilities#

Date parsing utilities for portfolio operations.

This module provides date parsing functions used across portfolio-related modules to avoid circular dependencies.

parse_date_with_formats(date_str: str, formats: list[str]) → datetime#

Parse a date string trying multiple formats.

Parameters:

  • date_str (str) – Date string to parse.

  • formats (list[str]) – List of date format strings to try.

Returns:

Parsed datetime object.

Return type:

datetime.datetime

Raises:

ValueError – If date cannot be parsed with any format.

Examples

>>> parse_date_with_formats("2020-01-01", DATE_FORMATS)
datetime.datetime(2020, 1, 1, 0, 0)

>>> parse_date_with_formats("01/01/2020", DATE_FORMATS)
datetime.datetime(2020, 1, 1, 0, 0)
parse_config_date(value: str | date | datetime | None) → date | Literal['auto']#

Parse a date value from any configuration source into a datetime.date or "auto".

This is the single shared utility for configuration-level date parsing. It handles the full range of inputs that may come from Excel cells, YAML files, JSON files, or programmatic parameters.

Parameters:

value (str | datetime.date | datetime.datetime | None) –

The raw date value. Accepted inputs:

  • None — interpreted as "auto".

  • The string "auto" (case-insensitive) — returned as "auto".

  • A datetime.datetime — converted to datetime.date via .date().

  • A datetime.date — returned unchanged.

  • An ISO-formatted string (YYYY-MM-DD) — parsed via date.fromisoformat().

  • Other date-string formats (YYYY/MM/DD, DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD HH:MM:SS) — parsed via parse_date_with_formats() as a fallback.

Returns:

A resolved date or the sentinel string "auto".

Return type:

datetime.date | Literal[“auto”]

Raises:

DateParsingError – If value is a string that cannot be parsed with any known format, or if value is an unsupported type.

Examples

>>> parse_config_date(None)
'auto'

>>> parse_config_date("auto")
'auto'

>>> parse_config_date("2024-01-15")
datetime.date(2024, 1, 15)

>>> parse_config_date(datetime.date(2024, 1, 15))
datetime.date(2024, 1, 15)