par_ai_core.time_display API documentation
Description: Time Display and Conversion Utilities …

# Module `par_ai_core.time_display`

Time Display and Conversion Utilities

This module provides a set of functions for formatting timestamps, converting datetimes between UTC and local timezones, and retrieving local timezone information. It is designed to simplify common datetime operations in the par_ai_core project.

## Functions

format_datetime: Convert a datetime object to a formatted string. format_timestamp: Convert a Unix timestamp to a formatted string. convert_to_local: Convert a UTC datetime to the local timezone. get_local_timezone: Retrieve the local timezone.

These utilities are particularly useful for displaying timestamps in a human-readable format and handling timezone conversions, which are common requirements in many parts of the par_ai_core project.

## Functions

`def convert_to_local(utc_dt: datetime | str | None) ‑> datetime.datetime | None`
  Expand source code

      def convert_to_local(utc_dt: datetime | str | None) -> datetime | None:
          """Convert a UTC datetime to the local timezone.

          Args:
              utc_dt: The UTC datetime, either as a datetime object or an ISO format string.

          Returns:
              datetime | None: A datetime in the local timezone, or None if input is None or an empty string.
          """
          if utc_dt is None:
              return None
          if isinstance(utc_dt, str):
              if utc_dt == "":
                  return None
              utc_dt = datetime.fromisoformat(utc_dt)

          local_dt_now = datetime.now(timezone.utc)
          local_tz = local_dt_now.astimezone().tzinfo
          local_dt = utc_dt.astimezone(local_tz)
          return local_dt

  Convert a UTC datetime to the local timezone.

  ## Args

  `utc_dt`
    The UTC datetime, either as a datetime object or an ISO format string.

  ## Returns

  `datetime | None`
    A datetime in the local timezone, or None if input is None or an empty string.
`def format_datetime(dt: datetime | None, fmt: str = '%Y-%m-%d %H:%M:%S') ‑> str`
  Expand source code

      def format_datetime(dt: datetime | None, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
          """Convert a datetime object into a string in human-readable format.

          Args:
              dt: The datetime object.
              fmt: The format string. Defaults to "%Y-%m-%d %H:%M:%S".

          Returns:
              str: The string datetime in the format specified. Or "Never" if dt is None.
          """
          if dt is None:
              return "Never"
          return dt.strftime(fmt)

  Convert a datetime object into a string in human-readable format.

  ## Args

  `dt`
    The datetime object.
  `fmt`
    The format string. Defaults to "%Y-%m-%d %H:%M:%S".

  ## Returns

  `str`
    The string datetime in the format specified. Or "Never" if dt is None.
`def format_timestamp(timestamp: float, fmt: str = '%Y-%m-%d %H:%M:%S') ‑> str`
  Expand source code

      def format_timestamp(timestamp: float, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
          """Convert a Unix timestamp into a string in human-readable format.

          Args:
              timestamp: The Unix timestamp.
              fmt: The format string. Defaults to "%Y-%m-%d %H:%M:%S".

          Returns:
              str: The string timestamp in the format specified.
          """
          utc_dt = datetime.fromtimestamp(timestamp, timezone.utc)
          local_dt = utc_dt.astimezone()
          return local_dt.strftime(fmt)

  Convert a Unix timestamp into a string in human-readable format.

  ## Args

  `timestamp`
    The Unix timestamp.
  `fmt`
    The format string. Defaults to "%Y-%m-%d %H:%M:%S".

  ## Returns

  `str`
    The string timestamp in the format specified.
`def get_local_timezone() ‑> datetime.tzinfo | None`
  Expand source code

      def get_local_timezone() -> tzinfo | None:
          """Get the local timezone.

          Returns:
              tzinfo | None: The local timezone.
          """
          return datetime.now(timezone.utc).astimezone().tzinfo

  Get the local timezone.

  ## Returns

  `tzinfo | None`
    The local timezone.