Skip to content

griffe-warnings-deprecated¤

documentation gitpod gitter

Griffe extension for @warnings.deprecated (PEP 702).

Installation¤

This project is available to sponsors only, through my Insiders program. See Insiders explanation and installation instructions.

Usage¤

The option values in the following examples are the default ones, you can omit them if you like the defaults.

Command-line¤

griffe dump mypackage -e griffe_warnings_deprecated

See command-line usage in Griffe's documentation.

Python¤

import griffe

griffe.load(
    "mypackage",
    extensions=griffe.load_extensions(
        [{"griffe_warnings_deprecated": {
            "kind": "danger",
            "title": "Deprecated",
            "label": "deprecated"
        }}]
    )
)

See programmatic usage in Griffe's documentation.

MkDocs¤

mkdocs.yml
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          extensions:
          - griffe_warnings_deprecated:
              kind: danger
              title: Deprecated

See MkDocs usage in Griffe's documentation.

Options:

  • kind: The admonition kind (default: danger).
  • title: The admonition title (default: Deprecated). Can be set to null to use the message as title.
  • label: The label added to deprecated objects (default: deprecated). Can be set to null.

Examples¤

Normal admonition¤

Given the following code:

# normal.py
import warnings


@warnings.deprecated(
    "This function is deprecated, use [`other_function`][normal.other_function] instead.",
    category=DeprecationWarning,
)
def function() -> int:
    """Do something.

    Do something in a suboptimal manner.

    Returns:
        An integer.
    """
    return 0


def other_function() -> int:
    """Do something.

    Do something in an optimal manner.

    Returns:
        An integer.
    """
    return 1

And this mkdocstrings configuration:

::: normal.function
    options:
      heading_level: 4
      extensions: [griffe_warnings_deprecated]

::: normal.other_function
    options:
      heading_level: 4

Here is the rendered HTML:

function deprecated ¤

function() -> int
Deprecated

This function is deprecated, use other_function instead.

Do something.

Do something in a suboptimal manner.

Returns:

  • int –

    An integer.

other_function ¤

other_function() -> int

Do something.

Do something in an optimal manner.

Returns:

  • int –

    An integer.

Admonition with message as title¤

Given the following code:

# notitle.py
import warnings


@warnings.deprecated(
    "This function is deprecated, use [`other_function`][normal.other_function] instead.",
    category=DeprecationWarning,
)
def function() -> int:
    """Do something.

    Do something in a suboptimal manner.

    Returns:
        An integer.
    """
    return 0

And this mkdocstrings configuration:

::: notitle.function
    options:
      heading_level: 4
      extensions:
      - griffe_warnings_deprecated:
          title: null
          kind: warning

Here is the rendered HTML:

function deprecated ¤

function() -> int
This function is deprecated, use other_function instead.

Do something.

Do something in a suboptimal manner.

Returns:

  • int –

    An integer.