zope-exceptions

library6.0pypypi✓ verified 84d ago

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.

testing

pip install zope-exceptions

github ↗package ↗

INSTALL

IMPORT

SIG · ZOPE-EXCEPTIONS

zope-exceptions

testingpythonv6.0

Install

2.1s avg

Import

58ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v6.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.059s · 19.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.057s · 21MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

Debug

Known issues

breakingVersion 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.

affects: 6.0+

breakingVersion 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.

affects: 6.0+

breakingVersion 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.

affects: 5.0+

gotchaThe `__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.

affects: All versions

gotchaIn 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.

affects: Zope 2, 3, 4, 5+

Errors

Common errors & fixes

ImportError: cannot import name '...' from 'pkg_resources'

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__)

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

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')`.

Upgrade

Version history

6.0latest on PyPI · released Sep 12, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

44 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/zopefoundation/zope.exceptions ↗

packagehttps://pypi.org/project/zope-exceptions/ ↗