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

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

.. autoapi-nested-parse::

   Utility functions for date formatting and validation.



Attributes
----------

.. autoapisummary::

   epicsarchiver.common.date_util.NANO_PER_SECOND
   epicsarchiver.common.date_util.MICRO_PER_SECOND
   epicsarchiver.common.date_util.NANO_PER_MICROSECOND
   epicsarchiver.common.date_util.EPOCH
   epicsarchiver.common.date_util._DATE_FORMATS


Exceptions
----------

.. autoapisummary::

   epicsarchiver.common.date_util.DateFormatError


Classes
-------

.. autoapisummary::

   epicsarchiver.common.date_util.QueryTimestamp
   epicsarchiver.common.date_util.ResponseTimestamp


Functions
---------

.. autoapisummary::

   epicsarchiver.common.date_util.ensure_utc
   epicsarchiver.common.date_util.year_start_epoch_seconds
   epicsarchiver.common.date_util._parse_datetime_str


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

.. py:data:: NANO_PER_SECOND
   :value: 1000000000


.. py:data:: MICRO_PER_SECOND
   :value: 1000000


.. py:data:: NANO_PER_MICROSECOND
   :value: 1000


.. py:data:: EPOCH

.. py:data:: _DATE_FORMATS
   :value: ['%Y%m%d', '%Y%m%d %H:%M', '%Y%m%d %H:%M:%S', '%Y-%m-%d', '%Y-%m-%dT%H:%M', '%Y-%m-%d %H:%M',...


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

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


   Exception raised for invalid date formats.


.. py:function:: ensure_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: datetime.datetime


.. py:function:: year_start_epoch_seconds(year: int) -> int

   Seconds from Unix epoch at the start of a given year.

   :param year: year
   :type year: int

   :returns: seconds from epoch of start of year.
   :rtype: int


.. py:function:: _parse_datetime_str(date_str: str) -> datetime.datetime

   Parse a date string using known formats.

   :param date_str: A date/datetime string.

   :returns: UTC-aware datetime.
   :rtype: datetime.datetime

   :raises DateFormatError: If the string cannot be parsed.


.. py:class:: QueryTimestamp(dt: datetime.datetime)

   A microsecond-precision UTC timestamp for archiver queries.

   Wraps a UTC-aware datetime. Used for the input flow: user
   string/datetime to archiver HTTP query parameter.


   .. py:attribute:: __slots__
      :value: ('_dt',)



   .. py:attribute:: _dt


   .. py:method:: from_input(date_or_str: datetime.datetime | str) -> QueryTimestamp
      :classmethod:


      Parse user input (string or datetime).

      Strings are parsed using a set of known formats.
      Strings without timezone information are treated as UTC.
      Datetimes are normalised to UTC.

      :param date_or_str: A datetime object or a date/datetime string.

      :returns: QueryTimestamp



   .. py:method:: from_datetime(dt: datetime.datetime) -> QueryTimestamp
      :classmethod:


      From a datetime (naive assumed UTC, aware converted).

      :param dt: A datetime object.

      :returns: QueryTimestamp



   .. py:property:: datetime
      :type: datetime.datetime


      UTC-aware datetime.

      :returns: UTC datetime
      :rtype: datetime.datetime


   .. py:method:: to_query_string() -> str

      ISO 8601 with 'Z' suffix for archiver HTTP params.

      :returns: e.g. '2018-07-04T13:00:00.000000Z'
      :rtype: str



.. py:class:: ResponseTimestamp(timestamp_ns: int)

   A nanosecond-precision UTC timestamp from archiver responses.

   Internal representation is nanoseconds since Unix epoch (int).
   Used for the response flow: archiver data to datetime or
   display string. Precision is only lost when outputting to
   datetime (microsecond resolution).


   .. py:attribute:: __slots__
      :value: ('_ns',)



   .. py:attribute:: _ns


   .. py:method:: from_yearsecondnanos(year: int, seconds: int, nanos: int) -> ResponseTimestamp
      :classmethod:


      From archiver PB format.

      Full nanosecond precision is preserved.

      :param year: year
      :type year: int
      :param seconds: seconds into year
      :type seconds: int
      :param nanos: nanoseconds
      :type nanos: int

      :returns: ResponseTimestamp



   .. py:property:: ns
      :type: int


      Nanoseconds since Unix epoch. Full precision.

      :returns: nanoseconds since epoch
      :rtype: int


   .. py:property:: datetime
      :type: datetime.datetime


      UTC-aware datetime (microsecond precision).

      Sub-microsecond nanoseconds are truncated.

      :returns: UTC datetime
      :rtype: datetime.datetime


   .. py:method:: to_local_string() -> str

      Local timezone string for display.

      :returns: local timezone datetime string
      :rtype: str