feat(common): add deprecated decorator (#300)

[borderlessboy]

Issue Reference

Closes #300

---

What Was Changed

• pyaml/common/deprecation.py: new deprecated(message=None) decorator. Works on functions, methods and classes. Each call or instantiation emits a DeprecationWarning naming the object and the optional message. Uses functools.wraps, so name and docstring are kept.
• tests/common/test_deprecation.py: 6 tests (function, custom message, method, class, warning points at caller, metadata kept).

---

Why Was It Changed

The issue asks for a standard way to mark functions and classes as deprecated, with a warning to developers. Nothing in the codebase did this before.

---

Screenshots

N/A (library code, no UI change).

---

Checklist

• I ran the change locally: tests for what I changed pass, and ruff check and format are clean
• I covered every item the issue lists (decorator for functions, methods, classes; optional custom message; logs/warns on use)
• I attached proof: test output below
• This is my only open PR on a good first issue
• Docs issue? N/A

---

Additional Context

Verification (Windows, Python 3.12.14):

• pytest tests/common/test_deprecation.py: 6 passed.
• Full suite pytest tests -m "not integration": 459 passed, 1 failed. The failure is tests/tuning_tools/test_tuning_orm.py::test_tuning_orm (PermissionError on a Windows temp file). It also fails on the unmodified base commit, so it predates this change.
• ruff check and ruff format --check on the two new files: clean.

[GamelinAl]

Hi, we should probably use something based on typing_extensions.deprecated instead of starting from scratch (see https://peps.python.org/pep-0702/). For example, I think this proposal will not handle a class method which already use decorators like @classmethod or @Property.

It is to be seen but maybe just using the default python tool like @deprecated would be enough for our need.

[borderlessboy]

Thank you @GamelinAl for the review — agreed on all points. Reworked in b032d1c:

• pyaml/common/deprecation.py is now a thin re-export of typing_extensions.deprecated (PEP 702), keeping the module path; the hand-rolled decorator is gone.
• typing_extensions>=4.5 added to project dependencies in pyproject.toml (direct import needs a direct dep; keeps Python < 3.13 support).
• Composition tests added for @deprecated stacked with @classmethod, @staticmethod and @property in both stacking orders, matching typing_extensions' actual behavior (including the orders it rejects at definition time); existing function/class/custom-message/caller-location coverage kept. Verified the new tests fail against the old implementation and pass with the rework; ruff check and tests/common (120 passed) green.

[GamelinAl]

The conclusion is that we don't need anything else than typing_extensions.deprecated. I am closing this PR and the issue #300.