uYf(fdZddlZddlZddlZddlmZddlmZGddeZd dZ d 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) deprecatedcBeZdZdZdddedffd 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. NFcj|s td||_||_tt|||||y)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 `_, 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)reasonversionactioncategoryN) ValueError directive line_lengthsuperr__init__)selfrr r r r r __class__s Q/var/www/highfloat_scraper/venv/lib/python3.12/site-packages/deprecated/sphinx.pyrzSphinxAdapter.__init__,s>VRS S"& mT+67SYdl+mc |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 dd|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_indentrT)keependsNrz\n+$flagsz  c3>K|]}dj|yw)z{} N)format).0lines r z)SphinxAdapter.__call__..sGTV]]40Gs> versionaddedversionchanged)r r"rrtextwrapdedentr strip splitlinesextendfillappend__doc__lenjoinresubDOTALLrr__call__) rwrappedfmt div_linesrr paragraph docstringlinesrs rr5zSphinxAdapter.__call__^s/3ll*@RZZ$..$,,ZOP (,(8(81(<  1$'-335**, %I  MM!#',*/  !jl   $ %OO)r $$d$3;t;>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@rrrs0 #0nd-<^rrc$td|||}|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 `_, 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 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 `_, 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) 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 `_, 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 r r)rrM)popr_classic_deprecated)r r rkwargsrrMs rrrsXF ; 5I**]M:KF8F9'F=  V Vv VVr)rrr) r/r2r(wraptdeprecated.classicrrrPrr&r'rNrrrTs:(  -@ANAH<:(Wr