1717from __future__ import annotations
1818
1919import logging
20+ import warnings
2021from abc import ABC , abstractmethod
2122from collections .abc import Sequence
2223from dataclasses import dataclass
2324from datetime import datetime , timedelta
24- from typing import TYPE_CHECKING , Any , cast
25+ from inspect import signature
26+ from typing import TYPE_CHECKING , Any , Protocol , cast
2527from uuid import UUID
2628
2729import uuid6
28- from sqlalchemy import Boolean , ForeignKey , Index , Integer , Uuid , and_ , func , inspect , select , text
29- from sqlalchemy .exc import SQLAlchemyError
30+ from sqlalchemy import Boolean , ForeignKey , Index , Integer , Uuid , and_ , func , select , text
3031from sqlalchemy .orm import Mapped , mapped_column , relationship
3132
3233from airflow ._shared .observability .metrics import stats
3334from airflow ._shared .timezones import timezone
3435from airflow .configuration import conf
36+ from airflow .exceptions import RemovedInAirflow4Warning
3537from airflow .models .base import Base
3638from airflow .models .callback import (
3739 Callback ,
5759CALLBACK_METRICS_PREFIX = "deadline_alerts"
5860
5961
62+ class DeadlineDagRunProtocol (Protocol ):
63+ """The Dag run interface deadline references are evaluated against."""
64+
65+ dag_id : str
66+ logical_date : datetime | None
67+ queued_at : datetime | None
68+
69+
70+ def _get_evaluation_kwargs (reference : Any , evaluator : Any , kwargs : dict [str , Any ]) -> dict [str , Any ]:
71+ """Return the evaluation arguments accepted by a deadline reference."""
72+ required_kwargs : set [str ] | None = getattr (reference , "required_kwargs" , None )
73+ if required_kwargs is not None :
74+ warnings .warn (
75+ "required_kwargs is deprecated. Declare the keyword-only parameters your "
76+ "_evaluate_with() implementation needs instead." ,
77+ RemovedInAirflow4Warning ,
78+ stacklevel = 3 ,
79+ )
80+ kwargs = {key : value for key , value in kwargs .items () if key in required_kwargs }
81+ if missing_kwargs := required_kwargs - kwargs .keys ():
82+ raise ValueError (
83+ f"{ reference .__class__ .__name__ } is missing required parameters: { ', ' .join (missing_kwargs )} "
84+ )
85+ return kwargs
86+
87+ parameters = signature (evaluator ).parameters
88+ if any (param .kind is param .VAR_KEYWORD for param in parameters .values ()):
89+ return kwargs
90+
91+ return {key : value for key , value in kwargs .items () if key in parameters }
92+
93+
6094class classproperty :
6195 """
6296 Decorator that converts a method with a single cls argument into a property.
@@ -323,34 +357,18 @@ def get_reference_class(cls, reference_name: str) -> type[BaseDeadlineReference]
323357 class BaseDeadlineReference (LoggingMixin , ABC ):
324358 """Base class for all Deadline implementations."""
325359
326- # Set of required kwargs - subclasses should override this.
327- required_kwargs : set [str ] = set ()
328-
329360 @classproperty
330361 def reference_name (cls : Any ) -> str :
331362 return cls .__name__
332363
333364 def evaluate_with (self , * , session : Session , interval : timedelta , ** kwargs : Any ) -> datetime | None :
334- """Validate the provided kwargs and evaluate this deadline with the given conditions."""
335- filtered_kwargs = {k : v for k , v in kwargs .items () if k in self .required_kwargs }
336-
337- if missing_kwargs := self .required_kwargs - filtered_kwargs .keys ():
338- raise ValueError (
339- f"{ self .__class__ .__name__ } is missing required parameters: { ', ' .join (missing_kwargs )} "
340- )
341-
342- if extra_kwargs := kwargs .keys () - filtered_kwargs .keys ():
343- self .log .debug (
344- "%s ignoring unexpected parameters: %s" ,
345- self .reference_name ,
346- ", " .join (extra_kwargs ),
347- )
348-
349- base_time = self ._evaluate_with (session = session , ** filtered_kwargs )
365+ """Evaluate this deadline with the supplied context."""
366+ evaluation_kwargs = _get_evaluation_kwargs (self , self ._evaluate_with , kwargs )
367+ base_time = self ._evaluate_with (session = session , ** evaluation_kwargs )
350368 return base_time + interval if base_time is not None else None
351369
352370 @abstractmethod
353- def _evaluate_with (self , * , session : Session , ** kwargs : Any ) -> datetime | None :
371+ def _evaluate_with (self , * , session : Session , dagrun : DeadlineDagRunProtocol ) -> datetime | None :
354372 """Must be implemented by subclasses to perform the actual evaluation."""
355373 raise NotImplementedError
356374
@@ -384,7 +402,7 @@ class FixedDatetimeDeadline(BaseDeadlineReference):
384402
385403 _datetime : datetime
386404
387- def _evaluate_with (self , * , session : Session , ** kwargs : Any ) -> datetime | None :
405+ def _evaluate_with (self , * , session : Session , ** kwargs ) -> datetime | None :
388406 return self ._datetime
389407
390408 def serialize_reference (self ) -> dict :
@@ -400,23 +418,14 @@ def deserialize_reference(cls, reference_data: dict):
400418 class DagRunLogicalDateDeadline (BaseDeadlineReference ):
401419 """A deadline that returns a DagRun's logical date."""
402420
403- required_kwargs = {"dag_id" , "run_id" }
404-
405- def _evaluate_with (self , * , session : Session , ** kwargs : Any ) -> datetime | None :
406- from airflow .models import DagRun
407-
408- return _fetch_from_db (DagRun .logical_date , session = session , ** kwargs )
421+ def _evaluate_with (self , * , session : Session , dagrun : DeadlineDagRunProtocol ) -> datetime | None :
422+ return dagrun .logical_date
409423
410424 class DagRunQueuedAtDeadline (BaseDeadlineReference ):
411425 """A deadline that returns when a DagRun was queued."""
412426
413- required_kwargs = {"dag_id" , "run_id" }
414-
415- @provide_session
416- def _evaluate_with (self , * , session : Session , ** kwargs : Any ) -> datetime | None :
417- from airflow .models import DagRun
418-
419- return _fetch_from_db (DagRun .queued_at , session = session , ** kwargs )
427+ def _evaluate_with (self , * , session : Session , dagrun : DeadlineDagRunProtocol ) -> datetime | None :
428+ return dagrun .queued_at
420429
421430 @dataclass
422431 class AverageRuntimeDeadline (BaseDeadlineReference ):
@@ -425,7 +434,6 @@ class AverageRuntimeDeadline(BaseDeadlineReference):
425434 DEFAULT_LIMIT = 10
426435 max_runs : int
427436 min_runs : int | None = None
428- required_kwargs = {"dag_id" }
429437
430438 def __post_init__ (self ):
431439 if self .min_runs is None :
@@ -434,10 +442,10 @@ def __post_init__(self):
434442 raise ValueError ("min_runs must be at least 1" )
435443
436444 @provide_session
437- def _evaluate_with (self , * , session : Session , ** kwargs : Any ) -> datetime | None :
445+ def _evaluate_with (self , * , session : Session , dagrun : DeadlineDagRunProtocol ) -> datetime | None :
438446 from airflow .models import DagRun
439447
440- dag_id = kwargs [ " dag_id" ]
448+ dag_id = dagrun . dag_id
441449
442450 # Get database dialect to use appropriate time difference calculation
443451 dialect = get_dialect_name (session )
@@ -510,54 +518,3 @@ def deserialize_reference(cls, reference_data: dict):
510518
511519
512520DeadlineReferenceType = ReferenceModels .BaseDeadlineReference
513-
514-
515- @provide_session
516- def _fetch_from_db (model_reference : Mapped , * , session = None , ** conditions ) -> datetime | None :
517- """
518- Fetch a datetime value from the database using the provided model reference and filtering conditions.
519-
520- For example, to fetch a TaskInstance's start_date:
521- _fetch_from_db(
522- TaskInstance.start_date, dag_id='example_dag', task_id='example_task', run_id='example_run'
523- )
524-
525- This generates SQL equivalent to:
526- SELECT start_date
527- FROM task_instance
528- WHERE dag_id = 'example_dag'
529- AND task_id = 'example_task'
530- AND run_id = 'example_run'
531-
532- :param model_reference: SQLAlchemy Column to select (e.g., DagRun.logical_date, TaskInstance.start_date)
533- :param conditions: Filtering conditions applied as equality comparisons in the WHERE clause.
534- Multiple conditions are combined with AND.
535- :param session: SQLAlchemy session (auto-provided by decorator)
536- """
537- query = select (model_reference )
538-
539- for key , value in conditions .items ():
540- inspected = inspect (model_reference )
541- if inspected is not None :
542- query = query .where (getattr (inspected .class_ , key ) == value )
543-
544- compiled_query = query .compile (compile_kwargs = {"literal_binds" : True })
545- pretty_query = "\n " .join (str (compiled_query ).splitlines ())
546- logger .debug (
547- "Executing query:\n %r\n As SQL:\n %s" ,
548- query ,
549- pretty_query ,
550- )
551-
552- try :
553- result = session .scalar (query )
554- except SQLAlchemyError :
555- logger .exception ("Database query failed." )
556- raise
557-
558- if result is None :
559- message = f"No matching record found in the database for query:\n { pretty_query } "
560- logger .error (message )
561- raise ValueError (message )
562-
563- return result
0 commit comments