epicsarchiver.common.date_util
==============================

.. py:module:: epicsarchiver.common.date_util

.. autoapi-nested-parse::

   Utility functions for date formatting and validation.



Exceptions
----------

.. autoapisummary::

   epicsarchiver.common.date_util.DateFormatError


Functions
---------

.. autoapisummary::

   epicsarchiver.common.date_util.datetime_from_str
   epicsarchiver.common.date_util.format_date
   epicsarchiver.common.date_util.set_timezone_utc


Module Contents
---------------

.. py:exception:: DateFormatError(date_str: str)

   Bases: :py:obj:`epicsarchiver.common.validation.ValidationError`


   Exception raised for invalid date formats.


.. py:function:: datetime_from_str(date_or_str: datetime.datetime | str) -> datetime.datetime

   Formats a date or string to a datetime object.

   If the input is a string, it attempts to parse it into a datetime object.
   If the input is already a datetime object, it returns it without timezone info.

   All timezone information is stripped from the datetime object.

   :param date_or_str: can be a datetime object or string

   :returns: datetime object without timezone info.
   :rtype: datetime.datetime

   :raises DateFormatError: If the string cannot be parsed into a datetime object.


.. py:function:: format_date(at: datetime.datetime) -> str

   Format a datetime object to a string in ISO 8601 format with UTC timezone.

   :param at: The datetime object to format.
   :type at: datetime.datetime

   :returns: Formatted date string in ISO 8601 format with 'Z' suffix.
   :rtype: str


.. py:function:: set_timezone_utc(input_time: datetime.datetime) -> datetime.datetime

   Add UTC timezone if timezone missing, otherwise convert to UTC.

   :param input_time: A timestamp object.
   :type input_time: datetime.datetime

   :returns: A timestamp object with timezone set to UTC.
   :rtype: input_time (datetime.datetime)