🎉 pyDeprecate 0.7.0
pyDeprecate 0.7.0 is the docstring tooling release — deprecation notices now flow directly into rendered documentation. update_docstring=True is smarter (section-aware, per-argument) and MkDocs admonitions are supported alongside Sphinx. Two optional extensions wire up MKdocs and Sphinx autodoc so they pick up the injected notices automatically.
🚀 Added
MkDocs / Markdown Admonition Output.
@deprecated now accepts docstring_style="mkdocs" (alias: "markdown"). When update_docstring=True, the deprecation notice is injected as a !!! warning admonition instead of a Sphinx .. deprecated:: directive. Use docstring_style="auto" to detect the style automatically from existing docstring content. (#134)
from deprecate import deprecated
def new_load(path: str) -> dict: ...
@deprecated(target=new_load, deprecated_in="0.7", remove_in="1.0", update_docstring=True, docstring_style="mkdocs")
def load_config(path: str) -> dict:
"""Load the configuration file.
Args:
path: Path to the YAML config.
"""
# Resulting __doc__:
# !!! warning "Deprecated in 0.7"
# Will be removed in v1.0. Use `new_load` instead.
#
# Load the configuration file.
# ...Section-Aware Google / NumPy Docstring Injection.
update_docstring=True now detects Google-style (Args:, Returns:, …) and NumPy-style (Parameters, Returns + underline) section headers and inserts the deprecation notice before the first section rather than appending it at the end. (#134)
@deprecated(target=new_fn, deprecated_in="0.7", remove_in="1.0", update_docstring=True)
def old_fn(x: int) -> int:
"""Compute the result.
Args: ← notice injected above this line
x: Input value.
"""Inline Argument Deprecation in Docstrings.
When args_mapping is set and update_docstring=True, each renamed or removed argument is annotated directly in the Args: / :param section of the docstring rather than appending a general notice at the end. (#136)
@deprecated(
target=new_fn, deprecated_in="0.7", remove_in="1.0", args_mapping={"old_name": "new_name"}, update_docstring=True
)
def old_fn(old_name: str) -> str:
"""Process a value.
Args:
old_name: The value to process.
Deprecated since v0.7 — use `new_name` instead. Will be removed in v1.0.
"""Griffe Extension for mkdocstrings (beta).
Ensures that mkdocstrings renders the live injected docstring rather than the original source text. (#134)
# mkdocs.yml
plugins:
- mkdocstrings:
handlers:
python:
extensions:
- deprecate.docstring.griffe_ext:RuntimeDocstringsSphinx Autodoc Extension for Deprecated Classes (beta).
Ensures that Sphinx autodoc renders deprecated class aliases with the correct members, signature, and injected .. deprecated:: notice. (#134)
# conf.py
extensions = [
"sphinx.ext.autodoc",
"deprecate.docstring.sphinx_ext",
]Live Demo Documentation.
The project now ships live demo documentation published to GitHub Pages — an MkDocs demo, a Sphinx demo, and a portal landing page linking to both. (#134, #137)
📦 Installation
pip install --upgrade pyDeprecate🙏 Thank You
A big thank you to everyone who helped with this release:
- Jirka Borovec (@Borda) — architecture, review, and release management
Automated contributions: @copilot-swe-agent[bot], @pre-commit-ci[bot], @github-advanced-security[bot], @Copilot
Full Changelog: v0.6.0.post0...v0.7.0
