
    ^j                        U d Z ddlmZ ddlZddlmZ  ej                  e      ZdZ	de
d<   	 ddlmZ dd	lmZ d
Zer	 ddlmZ d
Z	e	r G d de      ZddZy# e$ r dZY &w xY w# e$ r dZ	Y (w xY w)u  Sphinx 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 <target>"`` 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)AnyFbool_PROXY_AVAILABLE)ClassDocumenter)prepare_docstringT)_DeprecatedProxyc                  ~     e Zd ZdZdZej                  dz   Ze	 	 	 	 	 	 	 	 	 	 d fd       Zdd	 fdZ	d
 fdZ
 xZS )_DeprecatedProxyClassDocumentera  ClassDocumenter 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.

            class   c                L    t        |t              xs t        |   ||||      S )zEReturn ``True`` for proxies and for all types the base class accepts.)
isinstancer	   supercan_document_member)clsmember
membernameisattrparent	__class__s        i/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/deprecate/docstring/sphinx_ext.pyr   z3_DeprecatedProxyClassDocumenter.can_document_memberQ   s0     "&*:; uw?ZJ@     c                    t         |   |      }t        | dd      }|rTt        |t              rDt        |dd      xs d| _        t        |d      r|j                  j                  | _	        d| _
        |S )u  Import 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``.

                )
raiseerrorobjectN__doc__ _cfgF)r   import_objectgetattrr   r	   
_proxy_dochasattrr   objr   doc_as_attr)selfr   resultr$   r   s       r   r    z-_DeprecatedProxyClassDocumenter.import_object^   ss     .*.E #448j.>?+23	2+F+L"DO sF+&)hhll
 (-D$r   c                V    t        | dd      }|rt        |      gS t        |          S )z?Return the proxy docstring so the deprecated block is rendered.r"   r   )r!   r   r   get_doc)r&   	proxy_docr   s     r   r)   z'_DeprecatedProxyClassDocumenter.get_doc~   s/    !(|R!@	-i899w((r   )
r   r   r   strr   r   r   r   returnr   )F)r   r   r,   r   )r,   zlist[list[str]] | None)__name__
__module____qualname__r   objtyper   priorityclassmethodr   r    r)   __classcell__)r   s   @r   r   r   C   sq     G&//!3H

  
 	

 
 
 
@) )r   r   c                    t         r/t        r)| j                  d       | j                  t        d       nt         rt
        j                  d       dddS )zRegister the ``_DeprecatedProxy`` documenter with Sphinx.

    Args:
        app: The Sphinx application instance.

    Returns:
        Extension metadata dict consumed by Sphinx.

    zsphinx.ext.autodocT)overrideu   deprecate.docstring.sphinx_ext: _DeprecatedProxy unavailable — extension loaded but _DeprecatedProxyClassDocumenter not registered.z0.1)versionparallel_read_safe)_SPHINX_AVAILABLEr   setup_extensionadd_autodocumenterr   _loggerwarning)apps    r   setupr>      sQ     -01 	>N	S	
 D99r   )r=   r   r,   zdict[str, Any])r   
__future__r   loggingtypingr   	getLoggerr-   r;   r   __annotations__sphinx.ext.autodocr   sphinx.util.docstringsr   r8   ImportErrordeprecate.proxyr	   r   r>    r   r   <module>rI      s   $L #  
'

H
% $ 28
 !4 @	)o @	)F:c    ! !s"   A A& A#"A#&A0/A0