[Core] Add deprecation module with decorator and custom warnings

[kacpermuda]

Rationale

This is a step number 2 of the process described in #36876, please refer to it for the rationale and in depth description. Possibly, it can also replace part of the mechanism described in #31830.

TLDR

See the tests i wrote, for the demo of how it works (look at the end of the file).

I want to add a decorator (for now only for classes, functions, methods etc.) that we can use for deprecations in the entire codebase (core and providers). By defining a custom function, we can have the most common information (now included in deprecation message) as separate arguments, so it's easier to parse it and use in CI, docs etc.

To do in next PRs

• Possibly some changes in the documentation will be required, to describe how the developers should deprecate things and what are the options.
• We can probably remove the warnings from current location (airflow.exceptions.py) and only keep them in airflow.deprecation.py, but this requires some time to migrate etc. so I am not sure how do properly do it.

Questions

This is my first PR that touches the core airflow, so let me know if anything needs to be changed 😄 I also have some questions to the functionality itself:

1. Are there any more arguments that we can define in the deprecation decorator? Some ideas?
2. Is it a good place (deprecation module in core) to have helper functions like: get_callable_full_path or validate_release_string. We can just make them private.
3. Should we define separate provider_deprecated decorator that will have a default category set to AirflowProviderDeprecationWarning ?
4. Should we allow passing a different Adapter, so that You can alter the deprecation message or we want to enforce standardization in the whole codebase and remove that option for the end user?

---

^ Add meaningful description above
Read the Pull Request Guidelines for more information.
In case of fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in a newsfragment file, named {pr_number}.significant.rst or {issue_number}.significant.rst, in newsfragments.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 5 days if no further activity occurs. Thank you for your contributions.

[kacpermuda]

Will reopen when i have time to do this.

[Taragolis]

If you have a time also worthwhile to check PEP-702 – Marking deprecations using the type system (and discussion) and maybe it is possible to adopt it to use it, in python before 3.13 it back-ported in typing_extensions

Some upstream PEP-702 related issues/feature requests

• Add support for PEP 702 (@deprecated) python/mypy#16111
• https://youtrack.jetbrains.com/issue/PY-61651/Deprecation-highlighting-with-PEP-702-deprecated-decorator
• Add provisional support for PEP 702 (marking classes and functions as deprecated) microsoft/pyright#4456

[kacpermuda]

Adding another example of deprecations from Ray: https://github.com/ray-project/ray/blob/master/python/ray/_private/utils.py#L1090