Add a way to manage .pyi <-> .py consistency

[potiuk]

Body

We have quite a few cases where .pyi and .py files we have get desynchronized (for example:

• Make the interface of common.sql DBApiHook type-defined #36224
• Remove redundant docker decorator type annotations #36406
• Make kubernetes decorator type annotation consistent with operator #36405

We should find a way to keep them synchronized as changes are applied to either .py or .pyi

Committer

• I acknowledge that I am a maintainer/committer of the Apache Airflow project.

[potiuk]

cc: @Taragolis

[Taragolis]

For provider's decorators it might be a good point to make it as part of some release management commands rather than pre-commit, because such of decorators is a part of providers and stub is part of core.

I've added this lines into the DockerOperator:

airflow/airflow/providers/docker/operators/docker.py

Lines 179 to 181 in d039437

	# !!! Changes in DockerOperator's arguments should be also reflected in !!!
	# - docs/apache-airflow-providers-docker/decorators/docker.rst
	# - airflow/decorators/__init__.pyi (by a separate PR)

I hope this reduce number of inconsistency but still easy to miss this comment

[potiuk]

We could for example use stubgen from mypy and compare the generated .pyi files AST (while we automatically remove the things we want to remove from .pyI). That would force whoever addss stuff to .py files to do something when new methods are added or signatures are modified.