§
    ð¿ˆc'  ã                   ón   — d Z ddlZddlZddlZddlmZ ddlmZ  G d„ de¦  «        Zdd	„Z	dd
„Z
dd„ZdS )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   ‡ — e Zd ZdZdddedfˆ fd„	Zˆ fd„Zˆ fd„Zˆ xZS )Ú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éF   c                 óž   •— |st          d¦  «        ‚|| _        || _        t          t          | ¦  «                             ||||¬¦  «         dS )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__)Úselfr   r
   r   r   r   r   Ú	__class__s          €ú3/usr/lib/python3/dist-packages/deprecated/sphinx.pyr   zSphinxAdapter.__init__,   s\   ø€ ðV ð 	TåÐRÑSÔSÐSØ"ˆŒØ&ˆÔÝ�m˜TÑ"Ô"×+Ò+°6À7ÐSYÐdlÐ+ÑmÔmÐmÐmÐmó    c           	      óü  •— | j         rdnd}|                     | j        | j         ¬¦  «        g}| j        dk    r
| j        dz
  nd}t	          j        | j        ¦  «                             ¦   «         }|                     ¦   «         D ]W}|r>| 	                    t	          j
        ||dd¬¦  «                             ¦   «         ¦  «         ŒB|                     d¦  «         ŒXt	          j        |j        pd¦  «        }|r&t          j        d	d|t          j        ¬
¦  «        dz   }nd}|d                     d„ |D ¦   «         ¦  «        z  }||_        | j        dv r|S t#          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}::)r   r   é   i   z   )ÚwidthÚinitial_indentÚsubsequent_indentr   z\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)r   r    r   r   ÚtextwrapÚdedentr
   ÚstripÚ
splitlinesÚextendÚfillÚappendÚ__doc__ÚreÚsubÚDOTALLÚjoinr   r   Ú__call__)	r   ÚwrappedÚfmtÚ	div_linesr   r
   Ú	paragraphÚ	docstringr   s	           €r   r2   zSphinxAdapter.__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 G¤OÐ$9°rÑ:Ô:ˆ	Øð 	åœ˜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Ñ;Ô;Ð;r   c                 óž   •— t          t          | ¦  «                             ||¦  «        }t          j        dd|t          j        ¬¦  «        }|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   )r   r   Úget_deprecated_msgr.   r/   ÚX)r   r3   ÚinstanceÚmsgr   s       €r   r9   z SphinxAdapter.get_deprecated_msg‰   sH   ø€ õ •M 4Ñ(Ô(×;Ò;¸GÀXÑNÔNˆõ ŒfÐBÀEÈ3ÕVXÔVZÐ[Ñ[Ô[ˆØˆ
r   )	Ú__name__Ú
__module__Ú__qualname__r-   ÚDeprecationWarningr   r2   r9   Ú__classcell__)r   s   @r   r   r      s’   ø€ € € € € ð
ð 
ð ØØØ#Øð0nð 0nð 0nð 0nð 0nð 0nðd)<ð )<ð )<ð )<ð )<ðVð ð ð ð ð ð ð ð r   r   r   r   c                 ó,   — 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
   r   r   ©r   ©r
   r   r   Úadapters       r   r$   r$   Ÿ   s+   € õ* ØØØØð	ñ ô €Gð €Nr   c                 ó,   — 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%   rC   rD   rE   s       r   r%   r%   ½   s+   € õ( ØØØØð	ñ ô €Gð €Nr   c                 ó    — |                      dd¦  «        }|                      dt          ¦  «        }| |d<   ||d<   ||d<   t          d||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.
    r   r   Úadapter_clsr
   r   r   )r   rI   © )Úpopr   Ú_classic_deprecated)r
   r   r   Úkwargsr   rI   s         r   r   r   Ú   sd   € ðF —
’
˜;¨Ñ5Ô5€IØ—*’*˜]­MÑ:Ô:€KØ€Fˆ8ÑØ€Fˆ9ÑØ'€Fˆ=ÑÝÐV¨ÀÐVÐVÈvÐVÐVÐVr   )r   r   r   )r-   r.   r&   ÚwraptÚdeprecated.classicr   r   rL   r   r$   r%   rJ   r   r   ú<module>rP      sÏ   ððð ð( 
€	€	€	Ø €€€à €€€à -Ð -Ð -Ð -Ð -Ð -Ø @Ð @Ð @Ð @Ð @Ð @ð}ð }ð }ð }ð }�Nñ }ô }ð }ð@ð ð ð ð<ð ð ð ð:(Wð (Wð (Wð (Wð (Wð (Wr   