Feature: deprecated decorator

[gubaidulinvadim]

Description, motivation and use case
Currently, our Python codebase lacks a standardized way to mark functions, classes, or methods as deprecated. This makes it difficult to communicate to developers when certain features are being phased out, leading to potential misuse of outdated or unsupported code. For example, if we deprecate old_api_function() in favor of new_api_function(), there is no clear way to warn users or developers about this change.

Proposed solution
Introduce a @deprecated decorator that can be applied to functions, classes, or methods. This decorator should:

• Log a deprecation warning when the decorated item is used.
• Optionally include a custom message explaining the deprecation and suggesting alternatives.
• Allow specifying a version number for when the item will be removed.

Describe alternatives you've considered

1. Manual Warnings: Adding warnings.warn() calls inside each deprecated function. This is repetitive and error-prone, as it requires manual updates across the codebase.
2. Docstring Notations: Documenting deprecations in docstrings. While this is informative, it doesn’t actively notify users at runtime.
3. Third-Party Libraries: Using external libraries like deprecation or wradlib. However, this adds external dependencies.

The proposed decorator approach is preferred because it is reusable, consistent, and provides runtime feedback.

Example

@deprecated(
    reason="Use `new_api_function()` instead.",
    version="2.0.0"
)
def old_api_function():
    pass

When old_api_function() is called, it should emit a warning like:

DeprecationWarning: old_api_function is deprecated and will be removed in version 2.0.0. Use `new_api_function()` instead.

Additional context

• Consider adding a since parameter to track when the deprecation was introduced.

Checklist

• I've assigned this issue to a project
• I've @-mentioned relevant people