Zope Deprecation Infrastructure

6.0 · active · verified Fri Apr 10

zope.deprecation provides utilities for marking modules, classes, functions, methods, and properties as deprecated in Python projects. It helps manage backward compatibility by issuing warnings when deprecated code is used. The current version is 6.0, and it generally sees a few releases per year, often tied to Python version support updates or internal Zope Foundation infrastructure changes.

Warnings

breaking Version 6.0 replaced `pkg_resources` namespace package handling with PEP 420 native namespace packages. Projects relying on the older `pkg_resources` mechanism for `zope` namespace package declarations might need adjustment.
Fix: Ensure your project's `pyproject.toml` or `setup.cfg` correctly declares namespace packages according to PEP 420. If you encounter `ModuleNotFoundError`, a clean reinstall of all `zope` related packages in a new virtual environment is often recommended.
breaking Python 3.7 and 3.8 are no longer supported as of version 5.1. Version 5.0 also dropped support for Python 2.7, 3.4, 3.5, and 3.6.
Fix: Upgrade to Python 3.9 or newer. The current version (6.0) requires Python >=3.9.
gotcha Mixing installation methods (e.g., `python setup.py develop` with `pip install`) for namespace packages like `zope.deprecation` can lead to `ModuleNotFoundError` due to how different systems handle namespace package discovery.
Fix: Always use a single, consistent tool for installing Python packages, preferably `pip` with virtual environments. If issues arise, perform a clean uninstall of all related packages and reinstall using only `pip`.
gotcha By default, `DeprecationWarning`s are often ignored. For `zope.deprecation` to be effective, you might need to configure Python's warnings system to display them.
Fix: Use `warnings.simplefilter('always', DeprecationWarning)` in your code, or run Python with the `-Wa` or `-Wd` flag (e.g., `python -Wd your_script.py`) to ensure deprecation warnings are displayed.

Install

pip install zope.deprecation Install with pip

Imports

deprecated
```
from zope.deprecation import deprecated
```
deprecate
```
from zope.deprecation import deprecate
```
moved
```
from zope.deprecation import moved
```
Suppressor
```
from zope.deprecation import Suppressor
```

Quickstart

This quickstart demonstrates how to use the `@deprecate` decorator for functions and mentions `moved` for module relocations. It also shows how to enable warnings and temporarily suppress them using `Suppressor`.

from zope.deprecation import deprecate, moved
import warnings

# Deprecating a function
@deprecate('Use new_function instead of old_function.')
def old_function():
    return "This is an old function."

# Deprecating a module that has moved
# In old_module.py (assuming it was moved to new_package.new_module)
# This would be placed in the *original* location of the module:
# from zope.deprecation import moved
# moved("new_package.new_module", "2.0")

# Example usage with warnings enabled
warnings.simplefilter('always')

print(old_function()) # This will emit a DeprecationWarning

# You can also suppress warnings for specific blocks
with Suppressor():
    print(old_function()) # No warning will be emitted here

view raw JSON →