The deprecated decorator does not preserve class signatures in Sphinx via autodoc

[davidorme]

If I decorate a test function using the sphinx decorator:

from deprecated.sphinx import deprecated

@deprecated(reason="Because", version="1.0.0")
class Test2:
    """A docstring for a class."""

    def __init__(self, a: int = 1) -> None:
        self.a = a
        """An attribute"""

    def method(self) -> None:
        """A method."""

        pass

class Test3:
    """A docstring for a class."""

    def __init__(self, a: int = 1) -> None:
        self.a = a
        """An attribute"""

    def method(self) -> None:
        """A method."""

        pass

And then use autodoc to build the documentation, then it all looks good (methods, attributes etc show nicely), except that the class signature is generalised, compared to the actual signature of the undecorated test class

classTest2(*args, **kwargs)

    A docstring for a class.

    Deprecated since version 1.0.0: Because

Versus

classTest3(a: int = 1)
    A docstring for a class.

Is there a way to preserve those signature details?

[laurent-laporte-pro]

Thank you for your detailed report regarding the signature issue with the @deprecated decorator.

The behavior you're observing is indeed the result of our current implementation. We decorate the class's __new__ method to emit a single deprecation warning when the class is instantiated, which is cleaner than making each method and property individually deprecated.

This approach has the advantage of being simple and efficient performance-wise, but unfortunately changes the class signature as it appears in autodoc-generated documentation.

The alternative would be to use the inspect module to preserve the original signature, but this would add additional computation time to each class instantiation, which we want to avoid.

We'll look into possible solutions to preserve the signature in the documentation while maintaining current performance. Thank you for raising this issue.

[davidorme]

Thanks for the quick response. I don't think this makes any difference to the issue, but my hope is to use a custom version of deprecated.sphinx.SphinxAdapter to generate an experimental decorator for experimental parts of the code base. That would require fewer options than deprecated.sphinx.deprecated but I think that's just cosmetic here.