DagRun.get_task_instances / fetch_task_instances accept a single TaskInstanceState at runtime, but the type hint only allows an Iterable #67653

Under which category would you file this issue?

Airflow Core

Apache Airflow version

3.2.0

What happened and how to reproduce it?

The state parameter on DagRun.get_task_instances[code] and DagRun.fetch_task_instances[code] is annotated:

state: Iterable[TaskInstanceState | None] | None = None

but the implementation explicitly handles a single state value via an isinstance(state, str)[code] short-circuit:

  if isinstance(state, str):
      tis = tis.where(TI.state == state)
  else:
      ...
      tis = tis.where(TI.state.in_(state))

Because TaskInstanceState(str, Enum) inherits from str, calling dagrun.get_task_instances(state=TaskInstanceState.FAILED) works at runtime and takes the == branch, but mypy/pyright flag it, and the docs/signature don't communicate that it's allowed.

The single-state code path is clearly deliberate, so the annotation should reflect it.

What you think should happen instead?

I propose to widen the annotation to TaskInstanceState | Iterable[TaskInstanceState | None] | None on both methods.

Operating System

No response

Deployment

Official Apache Airflow Helm Chart

Apache Airflow Provider(s)

No response

Versions of Apache Airflow Providers

No response

Official Helm Chart version

1.21.0 (latest released)

Kubernetes Version

No response

Helm Chart configuration

No response

Docker Image customizations

No response

Anything else?

No response

Are you willing to submit PR?

• Yes I am willing to submit a PR!

Code of Conduct

• I agree to follow this project's Code of Conduct