Zope Exceptions

6.0 · active · verified Thu Apr 16

This package provides general-purpose exception classes and implementations for the Zope ecosystem, designed to extend Python's standard `traceback` module with additional context information. It facilitates annotating tracebacks with `__traceback_info__` for unstructured data or `__traceback_supplement__` for delayed, structured data. It is currently at version 6.0 and receives updates primarily driven by Python version support and significant ecosystem changes, maintaining an active but irregular release cadence.

Common errors

```
ImportError: cannot import name '...' from 'pkg_resources'
```
cause The library (especially 6.0+) uses PEP 420 native namespaces, moving away from `pkg_resources` for namespace package discovery. Your environment might be outdated or configured to expect `pkg_resources` behavior.

fix Ensure your Python environment uses `setuptools` compatible with PEP 420 native namespace packages. Upgrade `setuptools` to its latest version (`pip install --upgrade setuptools`) and consider using a fresh virtual environment.
```
TypeError: 'str' object is not callable (when using __traceback_supplement__)
```
cause The `__traceback_supplement__` variable expects a sequence (typically a tuple) where the first element is a callable (function or method) and subsequent elements are its arguments. Users often mistakenly provide the result of the callable instead.

fix Assign `__traceback_supplement__` a tuple `(my_callable, arg1, arg2, ...)` where `my_callable` is the function to be called, not `my_callable(arg1, arg2, ...)`. The function will be called only when the traceback is formatted.
```
DeprecationWarning: string exceptions are deprecated
```
cause This warning occurs in older Python 2.x Zope environments when exceptions are raised as string literals (e.g., `raise 'My Error'`), a practice deprecated in Python 2.6 and removed in Python 3.

fix Refactor your code to raise proper exception classes, such as `raise ValueError('My Error')`.

Warnings

breaking Version 6.0 and higher explicitly drop support for Python 3.8 and older. Ensure your project runs on Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or newer, or pin `zope-exceptions<6.0` if you cannot upgrade Python.
breaking Version 6.0 replaces `pkg_resources` namespace with PEP 420 native namespace for package discovery. This can impact environments relying on older `setuptools` or specific packaging setups.
Fix: Ensure your `setuptools` is up-to-date and your environment correctly handles PEP 420 native namespace packages. Consider using modern virtual environment tools.
breaking Version 5.0 dropped support for Python 2.7, 3.5, and 3.6.
Fix: Upgrade your Python environment to 3.7 or newer, or pin `zope-exceptions<5.0` if you are on an unsupported Python version.
gotcha The `__traceback_info__` variable is evaluated immediately, even if the traceback is never formatted. If generating this information is computationally expensive, it can introduce unnecessary runtime overhead.
Fix: For expensive context generation, use `__traceback_supplement__` instead. This variable takes a callable and its arguments, which are only evaluated if a traceback needs to be formatted, delaying the computation.
gotcha In older Zope 2.x environments, error handling often involved `standard_error_message` (a ZODB object). Zope 3/4 and modern WSGI setups transitioned to 'exception views' registered via ZCML. `zope.exceptions` provides low-level tools, but the high-level application error display depends on the broader Zope architecture.
Fix: When working with Zope, understand the specific exception handling mechanism for your Zope version (e.g., configuring exception views in ZCML for Zope 4+). `zope.errorview` is a related package that provides basic HTTP and Browser views for common exceptions in newer Zope versions.

Install

pip install zope-exceptions Install latest version

Imports

format_exception

from zope.exceptions import format_exception

HTMLExceptionFormatter
```
from zope.exceptions.exceptionformatter import HTMLExceptionFormatter
```
Used for advanced HTML-based traceback formatting.
TextExceptionFormatter
```
from zope.exceptions.exceptionformatter import TextExceptionFormatter
```
Used for advanced plain-text traceback formatting.

Quickstart

This quickstart demonstrates how to use `__traceback_info__` to inject context into an exception's traceback. The `format_exception` function then processes this enriched information for output, making debugging easier.

import sys
from zope.exceptions import format_exception

def problematic_function(item_id):
    __traceback_info__ = f"Processing item with ID: {item_id}" # Adds context to traceback
    raise ValueError(f"Failed to process item {item_id}")

try:
    problematic_function('XYZ-123')
except Exception:
    exc_type, exc_value, exc_traceback = sys.exc_info()
    formatted_traceback = format_exception(exc_type, exc_value, exc_traceback)
    print("\n".join(formatted_traceback))
    del exc_traceback # Avoid reference cycles

view raw JSON →