�

$�;f(��n�dZd
dl
Z
d
dlZd
dlZd
dlmZ
d
dlmZ
Gd�de��Zdd	�
Z	dd
�
Z
dd�
ZdS)
a-
Sphinx directive integration
============================

We usually need to document the life-cycle of functions and classes:
when they are created, modified or deprecated.

To do that, `Sphinx <http://www.sphinx-doc.org>`_ has a set
of `Paragraph-level markups <http://www.sphinx-doc.org/en/stable/markup/para.html>`_:

- ``versionadded``: to document the version of the project which added the described feature to the library,
- ``versionchanged``: to document changes of a feature,
- ``deprecated``: to document a deprecated feature.

The purpose of this module is to defined decorators which adds this Sphinx directives
to the docstring of your function and classes.

Of course, the ``@deprecated`` decorator will emit a deprecation warning
when the function/method is called or the class is constructed.
�N)
�ClassicAdapter)
�
deprecatedc�B��eZ
dZd
Zdddedf�f
d�	Z�f
d�Z�f
d�Z�x
ZS)�
SphinxAdaptera
    Sphinx adapter -- *for advanced usage only*

    This adapter override the :class:`~deprecated.classic.ClassicAdapter`
    in order to add the Sphinx directives to the end of the function/class docstring.
    Such a directive is a `Paragraph-level markup <http://www.sphinx-doc.org/en/stable/markup/para.html>`_

    - The directive can be one of "versionadded", "versionchanged" or "deprecated".
    - The version number is added if provided.
    - The reason message is obviously added in the directive block if not empty.
    �N�Fc��
�|st
d
�
�
�
|
|_
||_tt|���||||���
dS)a�
        Construct a wrapper adapter.

        :type  directive: str
        :param directive:
            Sphinx directive: can be one of "versionadded", "versionchanged" or "deprecated".

        :type  reason: str
        :param reason:
            Reason message which documents the deprecation in your library (can be omitted).

        :type  version: str
        :param version:
            Version of your project which deprecates this feature.
            If you follow the `Semantic Versioning <https://semver.org/>`_,
            the version number has the format "MAJOR.MINOR.PATCH".

        :type  action: str
        :param action:
            A warning filter used to activate or not the deprecation warning.
            Can be one of "error", "ignore", "always", "default", "module", or "once".
            If ``None`` or empty, the the global filtering mechanism is used.
            See: `The Warnings Filter`_ in the Python documentation.

        :type  category: type
        :param category:
            The warning category to use for the deprecation warning.
            By default, the category class is :class:`~DeprecationWarning`,
            you can inherit this class to define your own deprecation warning category.

        :type  line_length: int
        :param line_length:
            Max line length of the directive text. If non nul, a long text is wrapped in several lines.
        z3'version' argument is required in Sphinx directives)�reason�version�action�categoryN)�
ValueError�	directive�line_length�superr�__init__)�selfrr
rrr
r�	__class__s       ��D/opt/alt/python311/lib/python3.11/site-packages/deprecated/sphinx.pyrzSphinxAdapter.__init__,s\���V
�	T
��R�S�S�S�"���&���
�m�T�"�"�+�+�6�7�SY�dl�+�m�m�m�m�m�c	��
�|jrd
n
d}|�
|j|j���g
}|jdkr
|jdz
n
d}t	j|j�
�
���}|���D]W}|r>|�	t	j
||dd�������
�

�B|�d�
�

�X|
jp
d}|�d	�
�
�
pdg
}t|�
�
dkr/t	jd�|dd��
�
�
�
n
d}|d
|z}|r&tjdd|tj���dz}nd}|d�d�|D���
�
z
}||
_|jdvr|
St%t&|���|
�
�
S)z�
        Add the Sphinx directive to your class or function.

        :param wrapped: Wrapped class or function.

        :return: the decorated class or function.
        z.. {directive}:: {version}z.. {directive}::)rr�i
z   )�width�initial_indent�subsequent_indentrT)
�keepends�
Nrz\n+$�
�flagsz

�

c
3�@K
�|]}
d�|
�
�
V�

�d
S)z{}
N)
�format)�.0�lines  r�	<genexpr>z)SphinxAdapter.__call__.<locals>.<genexpr>�s.����G�G�T�V�]�]�4�0�0�G�G�G�G�G�Gr>�versionadded�versionchanged)rr"rr�textwrap�dedentr
�strip�
splitlines�extend�fill�append�__doc__�len�join�re�sub�DOTALLrr�__call__)
r�wrapped�fmt�	div_linesrr
�	paragraph�	docstring�linesrs
         �rr5zSphinxAdapter.__call__^s�
���/3�l�R�*�*�@R���Z�Z�$�.�$�,�Z�O�O�P�	�(,�(8�1�(<�(<�� �1�$�$�'������-�-�3�3�5�5���*�*�,�,�	%�	%�I��

%�� � ��M�!�#�',�*/�	���
!�j�l�l�
����� � ��$�$�$�$��O�)�r�	��$�$�d�$�3�3�;��t��;>�u�:�:�
�>�>�H�O�B�G�G�E�!�"�"�I�$6�$6�7�7�7�r�	��!�H�y�(�	��	���w��I�R�Y�G�G�G�&�P�I�I��I�	�R�W�W�G�G�Y�G�G�G�G�G�G�	�#����>�?�?�?��N��]�D�)�)�2�2�7�;�;�;rc��
�t
t|���|
|��}tjd
d|tj���}|S)a�

        Get the deprecation warning message (without Sphinx cross-referencing syntax) for the user.

        :param wrapped: Wrapped class or function.

        :param instance: The object to which the wrapped function was bound when it was called.

        :return: The warning message.

        .. versionadded:: 1.2.12
           Strip Sphinx cross-referencing syntax from warning message.

        z*(?: : [a-zA-Z]+ )? : [a-zA-Z]+ : (`[^`]*`)z\1r)rr�get_deprecated_msgr2r3�
X)rr6�instance�msgrs    �rr=z SphinxAdapter.get_deprecated_msg�sH����M�4�(�(�;�;�G�X�N�N���f�B�E�3�VX�VZ�[�[�[���
r)	�__name__�
__module__�__qualname__r/�DeprecationWarningrr5r=�
__classcell__)
rs
@rrrs��������
�
����#��0n
�0n
�0n
�0n
�0n
�0n
�d
-<�-<�-<�-<�-<�^
��������rrrrc�,�t
d
||
|���}|S)a2
    This decorator can be used to insert a "versionadded" directive
    in your function/class docstring in order to documents the
    version of the project which adds this new functionality in your library.

    :param str reason:
        Reason message which documents the addition in your library (can be omitted).

    :param str version:
        Version of your project which adds this feature.
        If you follow the `Semantic Versioning <https://semver.org/>`_,
        the version number has the format "MAJOR.MINOR.PATCH", and,
        in the case of a new functionality, the "PATCH" component should be "0".

    :type  line_length: int
    :param line_length:
        Max line length of the directive text. If non nul, a long text is wrapped in several lines.

    :return: the decorated function.
    r&�r
rr�
r�r
rr�adapters    rr&r&�s+��*�����	���G��Nrc�,�t
d
||
|���}|S)a�
    This decorator can be used to insert a "versionchanged" directive
    in your function/class docstring in order to documents the
    version of the project which modifies this functionality in your library.

    :param str reason:
        Reason message which documents the modification in your library (can be omitted).

    :param str version:
        Version of your project which modifies this feature.
        If you follow the `Semantic Versioning <https://semver.org/>`_,
        the version number has the format "MAJOR.MINOR.PATCH".

    :type  line_length: int
    :param line_length:
        Max line length of the directive text. If non nul, a long text is wrapped in several lines.

    :return: the decorated function.
    r'rGrHrIs    rr'r'�s+��(�����	���G��Nrc��|�d
d��}|�dt��}||d<|
|d<||d<td||d�|�
�
S)	ax
    This decorator can be used to insert a "deprecated" directive
    in your function/class docstring in order to documents the
    version of the project which deprecates this functionality in your library.

    :param str reason:
        Reason message which documents the deprecation in your library (can be omitted).

    :param str version:
        Version of your project which deprecates this feature.
        If you follow the `Semantic Versioning <https://semver.org/>`_,
        the version number has the format "MAJOR.MINOR.PATCH".

    :type  line_length: int
    :param line_length:
        Max line length of the directive text. If non nul, a long text is wrapped in several lines.

    Keyword arguments can be:

    -   "action":
        A warning filter used to activate or not the deprecation warning.
        Can be one of "error", "ignore", "always", "default", "module", or "once".
        If ``None``, empty or missing, the the global filtering mechanism is used.

    -   "category":
        The warning category to use for the deprecation warning.
        By default, the category class is :class:`~DeprecationWarning`,
        you can inherit this class to define your own deprecation warning category.

    :return: a decorator used to deprecate a function.

    .. versionchanged:: 1.2.13
       Change the signature of the decorator to reflect the valid use cases.
    rr�adapter_clsr
rr)rrM�)�popr�_classic_deprecated)r
rr�kwargsrrMs      rrr�sd��F
�
�
�;��5�5�I��*�*�]�M�:�:�K��F�8���F�9��'�F�=���V���V�V�v�V�V�Vr)rrr)r/r2r(�wrapt�deprecated.classicrrrPrr&r'rNrr�<module>rT
s��


�
�
�(

�	�	�	���������-�-�-�-�-�-�@�@�@�@�@�@�A
�A
�A
�A
�A
�N�A
�A
�A
�H
�
�
�
�<
�
�
�
�:(
W
�(
W
�(
W
�(
W
�(
W
�(
W
r