§
    >²¸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n# e$ r dZY nw xY wer'	 ddlmZ d
Z	n# e$ r dZ	Y nw xY we	r G d„ de¦  «        Zdd„ZdS )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                  óf   ‡ — 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é   Úmemberr   Ú
membernameÚstrÚisattrr   ÚparentÚreturnc                óv   •— t          |t          ¦  «        p#t          ¦   «                              ||||¦  «        S )zEReturn ``True`` for proxies and for all types the base class accepts.)Ú
isinstancer	   ÚsuperÚcan_document_member)Úclsr   r   r   r   Ú	__class__s        €ún/root/private/project/pallet_detection_v2/.venv/lib/python3.11/site-packages/deprecate/docstring/sphinx_ext.pyr   z3_DeprecatedProxyClassDocumenter.can_document_memberQ   s>   ø€ õ " &Õ*:Ñ;Ô;ð ½u¹w¼w×?ZÒ?ZØ˜J¨°ñ@ô @ð ó    FÚ
raiseerrorc                ó  •— t          ¦   «                              |¬¦  «        }t          | dd¦  «        }|rUt          |t          ¦  «        r@t          |dd¦  «        p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``.

                )r   Ú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^   s’   ø€ õ ™œ×.Ò.¸*Ð.ÑEÔE�õ # 4¨°4Ñ8Ô8�Øð -�j¨Õ.>Ñ?Ô?ð -å+2°3¸	À2Ñ+FÔ+FÐ+LÈ"�D”Oõ ˜s FÑ+Ô+ð 3Ø&)¤h¤l˜œð
 (-�DÔ$Ø�r   úlist[list[str]] | Nonec                óŠ   •— 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~   sA   ø€ å!(¨¨|¸RÑ!@Ô!@�	Øð :Ý-¨iÑ8Ô8Ð9Ð9Ý‘w”w—’Ñ(Ô(Ð(r   )
r   r   r   r   r   r   r   r   r   r   )F)r   r   r   r   )r   r*   )Ú__name__Ú
__module__Ú__qualname__r   Úobjtyper   ÚpriorityÚclassmethodr   r"   r,   Ú__classcell__)r   s   @r   r   r   C   s§   ø€ € € € € ðð ð ˆGØ&Ô/°!Ñ3ˆHàð
ð 
ð 
ð 
ð 
ñ Œ[ð
ðð ð ð ð ð ð ð@)ð )ð )ð )ð )ð )ð )ð )ð )ð )r   r   Úappr   r   údict[str, Any]c                óÎ   — t           r9t          r2|                      d¦  «         |                      t          d¬¦  «         n!t           rt
                               d¦  «         dddœS )zºRegister 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)r5   s    r   Úsetupr@   †   s|   € õ ð 	
Õ-ð 	
Ø×ÒÐ0Ñ1Ô1Ð1ð 	×ÒÕ>ÈÐÑNÔNÐNÐNÝ	ð 
Ý�ŠðSñ	
ô 	
ð 	
ð °DÐ9Ð9Ð9r   )r5   r   r   r6   )r   Ú
__future__r   ÚloggingÚtypingr   Ú	getLoggerr.   r>   r   Ú__annotations__Úsphinx.ext.autodocr   Úsphinx.util.docstringsr   r;   ÚImportErrorÚdeprecate.proxyr	   r   r@   © r   r   ú<module>rK      so  ðð$ð $ð $ðL #Ð "Ð "Ð "Ð "Ð "à €€€Ø Ð Ð Ð Ð Ð à
ˆ'Ô
˜HÑ
%Ô
%€àÐ Ð Ð Ð Ñ ðØ2Ð2Ð2Ð2Ð2Ð2Ø8Ð8Ð8Ð8Ð8Ð8àÐÐøØð ð ð ØÐÐÐðøøøð ð J)ð!Ø4Ð4Ð4Ð4Ð4Ð4àÐÐøØð !ð !ð !Ø ÐÐÐð!øøøð ð B)ð@	)ð @	)ð @	)ð @	)ð @	)¨oñ @	)ô @	)ð @	)ðF:ð :ð :ð :ð :ð :s!   ¬; »AÁAÁA ÁAÁA