pipeline.src.helpers.dates
==========================

.. py:module:: pipeline.src.helpers.dates


Classes
-------

.. autoapisummary::

   pipeline.src.helpers.dates.Period


Functions
---------

.. autoapisummary::

   pipeline.src.helpers.dates.make_periods
   pipeline.src.helpers.dates.get_datetime_intervals
   pipeline.src.helpers.dates.is_in_validity_period


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

.. py:class:: Period

   .. py:attribute:: start
      :type:  datetime.datetime


   .. py:attribute:: end
      :type:  datetime.datetime


.. py:function:: make_periods(start_datetime_utc: datetime.datetime, end_datetime_utc: datetime.datetime, period_duration: datetime.timedelta, overlap: Union[None, datetime.timedelta] = None) -> List[Period]

   Returns a list of `Period` of duration `period_duration` covering the time range
   from `start_datetime_utc` to `end_datetime_utc`.

   If `overlap` is specified, the `Period` returned will overlap by the amount
   specified, otherwise the end of one period will coincide with the start of the
   next one.

   If `period_duration` is shorter than the time between `start_datetime_utc` and
   `end_datetime_utc`, returns a list with a single `Period` starting on
   `start_datetime_utc` and ending on `end_datetime_utc`.

   This is useful to break a long time range into smaller periods for processing time
   series data that would take up too much memory to handle in one piece.

   :param start_datetime_utc: start of the period to cover
   :type start_datetime_utc: datetime
   :param end_datetime_utc: end of the period to cover
   :type end_datetime_utc: datetime
   :param period_duration: duration of the individual
                           periods returned
   :type period_duration: timedelta
   :param overlap: overlap between successive
                   periods, if specified. Defaults to `None`.
   :type overlap: Union[None, timedelta]


.. py:function:: get_datetime_intervals(s: pandas.Series, unit: str = None, how: str = 'backward') -> pandas.Series

   Takes a pandas Series with datetime dtype. Return a pandas Series with the same
   index and with time intervals between the successives values of the input Series as
   values.

   :param s: pandas Series with datetime dtype
   :type s: Series
   :param unit:
                - if `None`, returns values as pandas `Timedelta`
                - if provided, must be one of 's', 'min' or 'h', in which case values
                  are returned as a float.

                Defaults to `None`.
   :type unit: Union[str, None]
   :param how: if, 'forward', computes the interval between each position and the
               next one. If 'backward', computes the interval between each position and
               the previous one.
               Defaults to 'backward'
   :type how: str

   :returns: Series of time intervals between the values of the input Series
   :rtype: pd.Series


.. py:function:: is_in_validity_period(validity_start_date: datetime.datetime, validity_end_date: datetime.datetime, repeat_each_year: bool, sample_date: datetime.datetime) -> bool

   Check if a sample_date falls within a validity period.

   :param validity_start_date: Start of validity period (None means no start constraint)
   :param validity_end_date: End of validity period (None means no end constraint)
   :param repeat_each_year: If True, the validity period repeats annually
   :param sample_date: Date to check against the validity period

   :returns: True if sample_date is within the validity period, False otherwise