^jndZddlmZddlZddlZ ddlZGddej Zy#e$rYywxYw)uGriffe extension: expose runtime-modified docstrings to mkdocstrings. .. note:: **Beta feature** — the public API of this module (class name, hook method signatures) may change in a minor release while it stabilises. ``@deprecated(update_docstring=True)`` writes the deprecation notice into ``fn.__doc__`` at decoration time. Griffe — the engine used by mkdocstrings — reads docstrings from the source AST, so it never sees that runtime change. This extension bridges the gap: after Griffe has visited a module it imports the module at runtime and replaces every AST docstring whose callable carries a ``__deprecated__`` attribute (set by pyDeprecate) with the live ``__doc__``. Usage in ``mkdocs.yml``:: plugins: - mkdocstrings: handlers: python: options: extensions: - deprecate.docstring.griffe_ext:RuntimeDocstrings Requirements: ``griffe`` is a dependency of ``mkdocstrings[python]`` and will always be present in an MkDocs environment that uses mkdocstrings. Importing this module without ``griffe`` installed is safe — ``RuntimeDocstrings`` simply will not be defined. ) annotationsNcDeZdZdZddZeddZd dZed dZy) RuntimeDocstringszCUpdate Griffe docstrings to reflect decorator-modified ``__doc__``.c |j|}|y|jjD]3\}}t|tj s!|j |||5y)a!Run after a module is fully loaded by Griffe. For each function or method in *mod* that carries a ``__deprecated__`` attribute (set by pyDeprecate), replace the Griffe docstring with the runtime value so that mkdocstrings renders the injected notice. N)_import_modulemembersitems isinstancegriffeObject _update_obj)selfmodloaderkwargs runtime_modnameobjs i/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/deprecate/docstring/griffe_ext.py on_modulezRuntimeDocstrings.on_module/s]--c2K" [[..0 = cc6==1$$S+t< =c tj|jS#ttf$rYnwxYwt |dd}|yddl}|j|}t|jjddz }|jdk(r|dz }t|j|}|tjv}|r tjjd| tj|j|r tjj|SS#ttf$r%Y|r tjj|yywxYw#|r tjj|wwxYw)utImport *mod* at runtime, adding its package root to sys.path if needed. griffe loads modules via its own search_paths which are not on sys.path, so a plain ``importlib.import_module(mod.name)`` will fail for modules that live outside the installed packages (e.g. a local ``demo.py``). We derive the package root from ``mod.filepath`` — walking up one level per dotted name component so that both single-file modules (``demo``) and package sub-modules (``pkg.submod``) resolve correctly — and temporarily add it to sys.path so the import can succeed. filepathNr.z __init__.py) importlib import_moduler ImportErrorModuleNotFoundErrorgetattrpathlibPathlensplitstrparentssyspathinsertremove)rrr!pdepth source_diraddeds rrz RuntimeDocstrings._import_module>sE  ..sxx88!45  sJ5H  X&As+,q0Evv& QYYu-.Jchh.E:. 0 ..sxx8HHOOJ/ !45 HHOOJ/ HHOOJ/s0!33#D$$E3EEE$E?cxt||d}|yt|tjr|j ||yt|tj rc|j |||j jD]3\}}t|tjs!|j|||5yy)N) r r r Function_replace_docstringClassrr r r )rrparentr runtime_obj member_namemembers rr zRuntimeDocstrings._update_objos!&$5K"#v/''[9C.''[9+.;;+<+<+>K'K!&&--8((kJK/rct|ddsyt|dd}|sy|jy||j_|jjj ddy)zDOverwrite the Griffe docstring when the runtime ``__doc__`` differs.__deprecated__N__doc__parsed)r docstringvalue__dict__pop) griffe_objr4 runtime_docs rr1z$RuntimeDocstrings._replace_docstring|sc;(8$?!+y$?K##+)4J &  ) ) - -h =rN)r griffe.Modulerzgriffe.GriffeLoaderrobjectreturnNone)rrArCrB)r griffe.Objectr3rBrr%rCrD)r?rEr4rBrCrD) __name__ __module__ __qualname__r9r staticmethodrr r1rrrr,s9Q = . 0 . 0` K  >  >rr) r9 __future__rrr'r ExtensionrrrJrrrMsG@# e> _>F,,_>   s ,44