| :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: pendulum.DateTime) -> DagRunInfo |
| :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: pendulum.DateTime) -> DagRunInfo |
| :classmethod: |
| |
| Represent a run on an exact time. |
| |
| |
| .. py:method:: interval(cls, start: pendulum.DateTime, end: pendulum.DateTime) -> DagRunInfo |
| :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) -> pendulum.DateTime |
| :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:: 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: Dict[str, Any]) -> Timetable |
| :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) -> Dict[str, Any] |
| |
| 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) -> None |
| |
| 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) -> str |
| :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: pendulum.DateTime) -> DataInterval |
| :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: Optional[DataInterval], restriction: TimeRestriction) -> Optional[DagRunInfo] |
| :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. |
| |
| |
| |