^jUdZddlmZddlZddlmZej eZdZ de d< ddl m Z dd l mZd Zer dd lmZd Z e r Gd d e ZddZy#e$rdZY&wxYw#e$rdZ Y(wxYw)uSphinx autodoc extension: expose runtime-modified docstrings for _DeprecatedProxy. .. note:: **Beta feature** — the public API of this module (documenter class, priority value) may change in a minor release while it stabilises. ``@deprecated_class(update_docstring=True)`` writes the deprecation notice into the proxy's ``__doc__`` at decoration time. Sphinx's autodoc sees the proxy as a non-class instance and renders it as ``"alias of "`` without showing the docstring. This extension bridges the gap by registering a custom :class:`ClassDocumenter` that: 1. Recognises :class:`~deprecate.proxy._DeprecatedProxy` objects via :meth:`can_document_member`. 2. Swaps the proxy for the underlying (wrapped) class so that Sphinx can introspect members and build the correct signature. 3. Returns the proxy's ``__doc__`` (which already contains the injected ``.. deprecated::`` block) from :meth:`get_doc`, so the notice appears in the rendered output. Usage in ``conf.py``:: extensions = [ 'sphinx.ext.autodoc', ... 'deprecate.docstring.sphinx_ext', ] Requirements: ``sphinx`` with ``sphinx.ext.autodoc`` is required. Importing this module without Sphinx installed is safe — the custom documenter is simply not registered. ) annotationsN)AnyFbool_PROXY_AVAILABLE)ClassDocumenter)prepare_docstringT)_DeprecatedProxyc~eZdZdZdZej dzZe dfd Zdd fd Z d fd Z xZ S) _DeprecatedProxyClassDocumenteraClassDocumenter subclass that handles pyDeprecate ``_DeprecatedProxy`` objects. Registered with a priority one step above the standard :class:`~sphinx.ext.autodoc.ClassDocumenter` so that it is selected whenever ``autoclass::`` is used on a :class:`~deprecate.proxy._DeprecatedProxy` instance, while all ordinary classes continue to be handled by the built-in documenter. classcLt|txst| ||||S)zEReturn ``True`` for proxies and for all types the base class accepts.) isinstancer supercan_document_member)clsmember membernameisattrparent __class__s i/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/deprecate/docstring/sphinx_ext.pyrz3_DeprecatedProxyClassDocumenter.can_document_memberQs0"&*:;uw?ZJ@ct||}t|dd}|rTt|trDt|ddxsd|_t |dr|jj|_ d|_ |S)uImport the object and, when it is a proxy, swap it for the wrapped class. The proxy's ``__doc__`` (which contains the injected deprecation notice) is saved in ``self._proxy_doc`` before the swap so that :meth:`get_doc` can return it verbatim. ``doc_as_attr`` is reset to ``False`` after the swap because the base :class:`~sphinx.ext.autodoc.ClassDocumenter` computes it using ``self.object.__name__``. On a :class:`~deprecate.proxy._DeprecatedProxy` that attribute is forwarded to the *target* class (via ``__getattr__``), which makes Sphinx believe the object is an alias for that target and adds an ``alias of …`` paragraph. After the swap ``self.object`` is the real class whose ``__name__`` matches the documented path, so ``doc_as_attr`` should be ``False``. ) raiseerrorobjectN__doc___cfgF) r import_objectgetattrrr _proxy_dochasattrrobjr doc_as_attr)selfrresultr$rs rr z-_DeprecatedProxyClassDocumenter.import_object^ss.*.E#448j.>?+23 2+F+L"DOsF+&)hhll (-D$ rcVt|dd}|r t|gSt| S)z?Return the proxy docstring so the deprecated block is rendered.r"r)r!rrget_doc)r& proxy_docrs rr)z'_DeprecatedProxyClassDocumenter.get_doc~s/!(|R!@ -i899w((r) rrrstrrrrrreturnr)F)rrr,r)r,zlist[list[str]] | None) __name__ __module__ __qualname__robjtyperpriority classmethodrr r) __classcell__)rs@rr r Csq G&//!3H            @ ) )rr ctr/tr)|jd|jtdntrt j ddddS)zRegister the ``_DeprecatedProxy`` documenter with Sphinx. Args: app: The Sphinx application instance. Returns: Extension metadata dict consumed by Sphinx. zsphinx.ext.autodocT)overrideudeprecate.docstring.sphinx_ext: _DeprecatedProxy unavailable — extension loaded but _DeprecatedProxyClassDocumenter not registered.z0.1)versionparallel_read_safe)_SPHINX_AVAILABLErsetup_extensionadd_autodocumenterr _loggerwarning)apps rsetupr>sQ- 01 >N  S D 99r)r=rr,zdict[str, Any])r __future__rloggingtypingr getLoggerr-r;r__annotations__sphinx.ext.autodocrsphinx.util.docstringsrr8 ImportErrordeprecate.proxyr r r>rrrIs$L# '  H %$28 !4@ )o@ )F:c ! !s"AA&A#"A#&A0/A0