// Use when deprecating a public Python API or `verdi` CLI command in aiida-core.
Use when adding a new `verdi` subcommand in `src/aiida/cmdline/`.
Use when adding a new third-party dependency to aiida-core's `pyproject.toml`.
Use when exploring the aiida-core codebase structure, looking for key files, or understanding how packages relate to each other.
Use when making commits, creating branches, or preparing pull requests for aiida-core.
Use when diagnosing failed, stuck, or misbehaving AiiDA processes or the daemon.
Use when running pre-commit, linting, type checking, or fixing CI failures in aiida-core.
| name | deprecating-api |
| description | Use when deprecating a public Python API or `verdi` CLI command in aiida-core. |
Public API is anything importable from a second-level package (from aiida.orm import ..., from aiida.engine import ...).
Public API must go through a deprecation cycle before removal.
Data created with older AiiDA versions is guaranteed to work with newer versions (database migrations are applied automatically), so backwards compatibility matters.
Use the warn_deprecation helper, which handles stacklevel=2 and respects the user's deprecation-visibility config:
from aiida.common.warnings import warn_deprecation
def old_function(x):
warn_deprecation('`old_function` is deprecated, use `new_function` instead.', version=3)
return new_function(x)
Add a .. deprecated:: note to the docstring with replacement guidance:
def old_function(x):
"""Do the thing.
.. deprecated:: 2.7
Use :func:`new_function` instead. Will be removed in 3.0.
"""
Use @decorators.deprecated_command() from aiida.cmdline.utils.decorators:
from aiida.cmdline.utils import decorators
@verdi_group.command('old-command')
@decorators.deprecated_command('Use `verdi new-command` instead.')
def old_command():
...
AIIDA_WARN_v3=1.src/aiida/common/warnings.pysrc/aiida/cmdline/utils/decorators.py