refine: deprecate direct use of @deprecated on classes; delegate to @deprecated_class with warning

[Borda]

Before submitting

• Was this discussed/approved via a Github issue? (no need for typos and docs improvements)
• Did you make sure to update the docs?
• Did you write any new necessary tests?

What does this PR do?

This pull request updates the behavior of the @deprecated decorator when applied directly to classes. Instead of raising a TypeError, it now emits a FutureWarning and delegates to @deprecated_class under the hood. The documentation and tests have been updated to reflect this new behavior, making it clearer for users and ensuring backward compatibility while preparing for a stricter enforcement in future releases.

Behavior change for class-level deprecation:

• src/deprecate/deprecation.py: Modified the @deprecated decorator to emit a FutureWarning and delegate to @deprecated_class when applied to a class, instead of raising a TypeError. This maintains functionality but signals that direct usage is deprecated and will become an error in the future.
• src/deprecate/deprecation.py: Updated the docstring to remove references to the previous TypeError for class-level deprecation.

Documentation updates:

• README.md: Updated the troubleshooting section to describe the new warning behavior and clarify that applying @deprecated to a class is deprecated but still works for now.

Test updates:

• tests/unittests/test_deprecation.py: Updated tests to expect a FutureWarning instead of a TypeError when @deprecated is applied to classes, enums, and dataclasses, and verified that delegation to @deprecated_class still works.

PR review

Anyone in the community is free to review the PR once the tests have passed.
If we didn't discuss your PR in Github issues there's a high chance it will not be merged.

Did you have fun?

Make sure you had fun coding 🙃

[Copilot]

Pull request overview

This PR changes @deprecated behavior when applied to classes: instead of raising TypeError, it now emits a warning and delegates to @deprecated_class, with accompanying updates to docs and unit tests.

Changes:

• Switch class-application handling in deprecated() from TypeError to FutureWarning + delegation to deprecated_class.
• Update unit tests to expect warnings rather than exceptions for class/Enum/dataclass decoration.
• Adjust README troubleshooting guidance for the new behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
src/deprecate/deprecation.py	Implements warning+delegation behavior for class sources in @deprecated and updates the docstring.
tests/unittests/test_deprecation.py	Updates guard tests to expect a warning rather than a TypeError.
README.md	Updates troubleshooting text to reflect the new class-decoration behavior.

Comments suppressed due to low confidence (1)

tests/unittests/test_deprecation.py:317

• These tests currently only assert that decoration emits a FutureWarning, but they don’t validate that the decorated class still functions (e.g., the decorator doesn’t return None) or that delegation to deprecated_class actually happens. Add assertions such as instantiating the decorated class and verifying it’s callable/instantiable (and optionally that it has __deprecated__ metadata) so the intended behavior can’t regress silently.

    def test_warns_for_plain_class(self) -> None:
        """Applying @deprecated to a plain class emits UserWarning and still works."""
        with pytest.warns(FutureWarning, match="deprecated_class"):

            @deprecated(target=None, deprecated_in="1.0", remove_in="2.0")
            class _MyClass:
                pass

    def test_warns_for_enum_class(self) -> None:
        """Applying @deprecated to an Enum class emits UserWarning and still works."""
        with pytest.warns(FutureWarning, match="deprecated_class"):

            @deprecated(target=None, deprecated_in="1.0", remove_in="2.0")
            class _MyEnum(Enum):
                A = "a"

    def test_warns_for_dataclass(self) -> None:
        """Applying @deprecated to a dataclass emits UserWarning and still works."""
        with pytest.warns(FutureWarning, match="deprecated_class"):

            @deprecated(target=None, deprecated_in="1.0", remove_in="2.0")
            @dataclass
            class _MyData:
                x: int

---

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

This PR changes deprecate.deprecation.deprecated() behavior when applied to classes: instead of raising TypeError, it now warns and delegates to deprecated_class() so class-level deprecation continues to work while guiding users toward the correct API.

Changes:

• Updated @deprecated to detect class sources and delegate to deprecated_class() with a warning.
• Adjusted unit tests to expect a warning (instead of TypeError) for class/Enum/dataclass decoration.
• Updated README troubleshooting guidance to reflect the new behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
src/deprecate/deprecation.py	Adds class-source handling that warns and redirects to deprecated_class().
tests/unittests/test_deprecation.py	Updates guard tests for class decoration to assert warnings rather than exceptions.
README.md	Updates troubleshooting section describing the new warning-based behavior.

---

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

This PR changes @deprecated behavior when applied to classes: instead of raising TypeError, it now emits a warning and delegates to deprecated_class() so class deprecations continue to function while discouraging the pattern.

Changes:

• Update deprecated() to detect class sources and return a deprecated_class() proxy with a meta-warning.
• Update unit tests to expect a warning (and a proxy return) rather than TypeError for classes/enums/dataclasses.
• Update README troubleshooting guidance for the new warning-based behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/deprecate/deprecation.py	Switches class-handling from raising TypeError to warning + delegation to deprecated_class().
tests/unittests/test_deprecation.py	Updates expectations for class decoration to warning + proxy, adds stream=None suppression test.
README.md	Adjusts troubleshooting section to describe the new warning behavior.

---

You can also share your feedback on Copilot code review. Take the survey.