akkudoktoreos.utils.datetimeutil.to_datetime

akkudoktoreos.utils.datetimeutil.to_datetime(date_input: Any | None = None, as_string: Literal[False] | None = None, in_timezone: str | Timezone | None = None, to_naiv: bool | None = None, to_maxtime: bool | None = None) → DateTime
akkudoktoreos.utils.datetimeutil.to_datetime(date_input: Any | None = None, as_string: str | Literal[True] = True, in_timezone: str | Timezone | None = None, to_naiv: bool | None = None, to_maxtime: bool | None = None) → str

Convert a date input into a Pendulum DateTime object or a formatted string, with optional timezone handling.

This function handles various date input formats, adjusts for timezones, and provides flexibility for formatting and time adjustments. For date strings without explicit timezone information, the local timezone is assumed. Be aware that Pendulum DateTime objects created without a timezone default to UTC.

Parameters:

  • date_input (Optional[Any]) – The date input to convert. Supported types include: - str: A date string in various formats (e.g., “2024-10-13”, “13 Oct 2024”). - pendulum.DateTime: A Pendulum DateTime object. - pendulum.Date: A Pendulum Date object, which will be converted to a datetime at the start or end of the day. - datetime.datetime: A standard Python datetime object. - datetime.date: A date object, which will be converted to a datetime at the start or end of the day. - int or float: A Unix timestamp, interpreted as seconds since the epoch (UTC). - None: Defaults to the current date and time, adjusted to the start or end of the day based on to_maxtime.

  • as_string (Optional[Union[str, bool]]) – Determines the output format: - True: Returns the datetime in ISO 8601 string format. - “UTC” or “utc”: Returns the datetime normalized to UTC as an ISO 8601 string. - str: A custom date format string for the output (e.g., “YYYY-MM-DD HH:mm:ss”). - False or None (default): Returns a pendulum.DateTime object.

  • in_timezone (Optional[Union[str, Timezone]]) – Specifies the target timezone for the result. - Can be a timezone string (e.g., “UTC”, “Europe/Berlin”) or a pendulum.Timezone object. - Defaults to the local timezone if not provided.

  • to_naiv (Optional[bool]) – If True, removes timezone information from the resulting datetime object. - Defaults to False.

  • to_maxtime (Optional[bool]) – Determines the time portion of the resulting datetime for date inputs: - True: Sets the time to the end of the day (23:59:59). - False or None: Sets the time to the start of the day (00:00:00). - Ignored if date_input includes an explicit time or if the input is a timestamp.

Returns:

  • A timezone-aware Pendulum DateTime object by default.

  • A string representation if as_string is specified.

Return type:

pendulum.DateTime or str

Raises:

ValueError – If date_input is not a valid or supported type, or if the date string cannot be parsed.

Examples

>>> to_datetime("2024-10-13", as_string=True, in_timezone="UTC")
'2024-10-13T00:00:00+00:00'

>>> to_datetime("2024-10-13T15:30:00", in_timezone="Europe/Berlin")
DateTime(2024, 10, 13, 17, 30, 0, tzinfo=Timezone('Europe/Berlin'))

>>> to_datetime(date(2024, 10, 13), to_maxtime=True)
DateTime(2024, 10, 13, 23, 59, 59, tzinfo=Timezone('Local'))

>>> to_datetime(1698784800, as_string="YYYY-MM-DD HH:mm:ss", in_timezone="UTC")
'2024-10-31 12:00:00'