:py:mod:`airflow.timetables.base`
=================================

.. py:module:: airflow.timetables.base


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

Classes
~~~~~~~

.. autoapisummary::

   airflow.timetables.base.DataInterval
   airflow.timetables.base.TimeRestriction
   airflow.timetables.base.DagRunInfo
   airflow.timetables.base.Timetable


.. py:class:: DataInterval

   Bases: :py:obj:`NamedTuple`

   A data interval for a DagRun to operate over.

   Both ``start`` and ``end`` **MUST** be "aware", i.e. contain timezone
   information.

   .. py:attribute:: start
      :annotation: :pendulum.DateTime

      
   .. py:attribute:: end
      :annotation: :pendulum.DateTime

      
   .. py:method:: exact(cls, at)
      :classmethod:

      Represent an "interval" containing only an exact time.


.. py:class:: TimeRestriction

   Bases: :py:obj:`NamedTuple`

   Restriction on when a DAG can be scheduled for a run.

   Specifically, the run must not be earlier than ``earliest``, nor later than
   ``latest``. If ``catchup`` is *False*, the run must also not be earlier than
   the current time, i.e. "missed" schedules are not backfilled.

   These values are generally set on the DAG or task's ``start_date``,
   ``end_date``, and ``catchup`` arguments.

   Both ``earliest`` and ``latest``, if not *None*, are inclusive; a DAG run
   can happen exactly at either point of time. They are guaranteed to be aware
   (i.e. contain timezone information) for ``TimeRestriction`` instances
   created by Airflow.

   .. py:attribute:: earliest
      :annotation: :Optional[pendulum.DateTime]

      
   .. py:attribute:: latest
      :annotation: :Optional[pendulum.DateTime]

      
   .. py:attribute:: catchup
      :annotation: :bool

      
.. py:class:: DagRunInfo

   Bases: :py:obj:`NamedTuple`

   Information to schedule a DagRun.

   Instances of this will be returned by timetables when they are asked to
   schedule a DagRun creation.

   .. py:attribute:: run_after
      :annotation: :pendulum.DateTime

      The earliest time this DagRun is created and its tasks scheduled.

      This **MUST** be "aware", i.e. contain timezone information.


   .. py:attribute:: data_interval
      :annotation: :DataInterval

      The data interval this DagRun to operate over.


   .. py:method:: exact(cls, at)
      :classmethod:

      Represent a run on an exact time.


   .. py:method:: interval(cls, start, end)
      :classmethod:

      Represent a run on a continuous schedule.

      In such a schedule, each data interval starts right after the previous
      one ends, and each run is scheduled right after the interval ends. This
      applies to all schedules prior to AIP-39 except ``@once`` and ``None``.


   .. py:method:: logical_date(self)
      :property:

      Infer the logical date to represent a DagRun.

      This replaces ``execution_date`` in Airflow 2.1 and prior. The idea is
      essentially the same, just a different name.


.. py:class:: Timetable

   Bases: :py:obj:`airflow.typing_compat.Protocol`

   Protocol that all Timetable classes are expected to implement.

   .. py:attribute:: description
      :annotation: :str = 

      Human-readable description of the timetable.

      For example, this can produce something like ``'At 21:30, only on Friday'``
      from the cron expression ``'30 21 * * 5'``. This is used in the webserver UI.


   .. py:attribute:: periodic
      :annotation: :bool = True

      Whether this timetable runs periodically.

      This defaults to and should generally be *True*, but some special setups
      like ``schedule_interval=None`` and ``"@once"`` set it to *False*.


   .. py:attribute:: can_run
      :annotation: :bool = True

      Whether this timetable can actually schedule runs.

      This defaults to and should generally be *True*, but ``NullTimetable`` sets
      this to *False*.


   .. py:method:: deserialize(cls, data)
      :classmethod:

      Deserialize a timetable from data.

      This is called when a serialized DAG is deserialized. ``data`` will be
      whatever was returned by ``serialize`` during DAG serialization. The
      default implementation constructs the timetable without any arguments.


   .. py:method:: serialize(self)

      Serialize the timetable for JSON encoding.

      This is called during DAG serialization to store timetable information
      in the database. This should return a JSON-serializable dict that will
      be fed into ``deserialize`` when the DAG is deserialized. The default
      implementation returns an empty dict.


   .. py:method:: validate(self)

      Validate the timetable is correctly specified.

      Override this method to provide run-time validation raised when a DAG
      is put into a dagbag. The default implementation does nothing.

      :raises: AirflowTimetableInvalid on validation failure.


   .. py:method:: summary(self)
      :property:

      A short summary for the timetable.

      This is used to display the timetable in the web UI. A cron expression
      timetable, for example, can use this to display the expression. The
      default implementation returns the timetable's type name.


   .. py:method:: infer_manual_data_interval(self, *, run_after)
      :abstractmethod:

      When a DAG run is manually triggered, infer a data interval for it.

      This is used for e.g. manually-triggered runs, where ``run_after`` would
      be when the user triggers the run. The default implementation raises
      ``NotImplementedError``.


   .. py:method:: next_dagrun_info(self, *, last_automated_data_interval, restriction)
      :abstractmethod:

      Provide information to schedule the next DagRun.

      The default implementation raises ``NotImplementedError``.

      :param last_automated_data_interval: The data interval of the associated
          DAG's last scheduled or backfilled run (manual runs not considered).
      :param restriction: Restriction to apply when scheduling the DAG run.
          See documentation of :class:`TimeRestriction` for details.

      :return: Information on when the next DagRun can be scheduled. None
          means a DagRun will not happen. This does not mean no more runs
          will be scheduled even again for this DAG; the timetable can return
          a DagRunInfo object when asked at another time.