ge+^dZddlZddlZddlmZddlmZGddeZd dZd dZ d d Zy) 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 `_ has a set of `Paragraph-level markups `_: - ``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) deprecatedcDeZdZdZdddeddffd ZfdZfdZxZS) 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 `_ - 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. NrFcl|s td||_||_tt||||||y)aV 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 `_, the version number has the format "MAJOR.MINOR.PATCH". :type action: Literal["default", "error", "ignore", "always", "module", "once"] :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 global filtering mechanism is used. See: `The Warnings Filter`_ in the Python documentation. :type category: Type[Warning] :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 extra_stacklevel: int :param extra_stacklevel: Number of additional stack levels to consider instrumentation rather than user code. With the default value of 0, the warning refers to where the class was instantiated or the function was called. :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. .. versionchanged:: 1.2.15 Add the *extra_stacklevel* parameter. z3'version' argument is required in Sphinx directives)reasonversionactioncategoryextra_stacklevelN) ValueError directive line_lengthsuperr__init__) selfrr r r r rr __class__s F/var/www/openai/venv/lib/python3.12/site-packages/deprecated/sphinx.pyrzSphinxAdapter.__init__*sDjRS S"& mT+76H_o , c ~|jrdnd}|j|j|jg}|jdkDr|jdz nd}t j |j j}|jD]L}|r7|jt j||ddj<|jdN|jxsd}|jd xsdg}t|d kDr't j dj|d d nd}|d |z}|r+tj d d|tj"dz}nd}|djd|Dz }||_ |jdvr|St$t&|S|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 iz )widthinitial_indentsubsequent_indentrTNrz\n+$flagsz  c3>K|]}dj|yw)z{} N)format).0lines r z)SphinxAdapter.__call__..sGYTV]]40Ys> versionaddedversionchanged)r r"rrtextwrapdedentr strip splitlinesextendfillappend__doc__lenjoinresubDOTALLrr__call__) rwrappedfmt div_linesrr paragraph docstringlinesrs rr5zSphinxAdapter.__call__hs/3ll*@RZZ$..$,,ZOP (,(8(81(<  1$%-335**,I  MM!#',*/  !jl   $-OO)r $$T*2rd;>u:>HOOBGGE!"I$67r !Hy( wIRYYG&PII RWWGYGGG # >>? ?N]D27;;rc~tt| ||}tjdd|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)rrget_deprecated_msgr2r3X)rr6instancemsgrs rr=z SphinxAdapter.get_deprecated_msgs;M4;GXNffBE3VXVZVZ[ r) __name__ __module__ __qualname__r/DeprecationWarningrr5r= __classcell__)rs@rrrs2 #< |-<^rrc$td|||}|S)a1 This decorator can be used to insert a "versionadded" directive in your function/class docstring in order to document 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 `_, 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 rrr r radapters rr&r&s!* G Nrc$td|||}|S)a This decorator can be used to insert a "versionchanged" directive in your function/class docstring in order to document 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 `_, 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 |jdd}|jdt}||d<||d<||d<td||d|S) a This decorator can be used to insert a "deprecated" directive in your function/class docstring in order to document 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 `_, 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 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. - "extra_stacklevel": Number of additional stack levels to consider instrumentation rather than user code. With the default value of 0, the warning refers to where the class was instantiated or the function was called. :return: a decorator used to deprecate a function. .. versionchanged:: 1.2.13 Change the signature of the decorator to reflect the valid use cases. .. versionchanged:: 1.2.15 Add the *extra_stacklevel* parameter. rr adapter_clsr r r)rrM)popr_classic_deprecated)r r rkwargsrrMs rrrsXX ; 5I**]M:KF8F9'F=  V Vv VVr)rrr) r/r2r(deprecated.classicrrrPrr&r'rNrrrSs7( -@MNM`<:1Wr