{"id":8801,"library":"zope-exceptions","title":"Zope Exceptions","description":"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.","status":"active","version":"6.0","language":"en","source_language":"en","source_url":"https://github.com/zopefoundation/zope.exceptions","tags":["zope","exceptions","error handling","traceback","debugging"],"install":[{"cmd":"pip install zope-exceptions","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"format_exception","correct":"from zope.exceptions import format_exception"},{"note":"Used for advanced HTML-based traceback formatting.","symbol":"HTMLExceptionFormatter","correct":"from zope.exceptions.exceptionformatter import HTMLExceptionFormatter"},{"note":"Used for advanced plain-text traceback formatting.","symbol":"TextExceptionFormatter","correct":"from zope.exceptions.exceptionformatter import TextExceptionFormatter"}],"quickstart":{"code":"import sys\nfrom zope.exceptions import format_exception\n\ndef problematic_function(item_id):\n    __traceback_info__ = f\"Processing item with ID: {item_id}\" # Adds context to traceback\n    raise ValueError(f\"Failed to process item {item_id}\")\n\ntry:\n    problematic_function('XYZ-123')\nexcept Exception:\n    exc_type, exc_value, exc_traceback = sys.exc_info()\n    formatted_traceback = format_exception(exc_type, exc_value, exc_traceback)\n    print(\"\\n\".join(formatted_traceback))\n    del exc_traceback # Avoid reference cycles\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer, or pin `zope-exceptions<6.0` if you cannot upgrade Python.","message":"Version 6.0 and higher explicitly drop support for Python 3.8 and older. Ensure your project runs on Python 3.9 or newer.","severity":"breaking","affected_versions":"6.0+"},{"fix":"Ensure your `setuptools` is up-to-date and your environment correctly handles PEP 420 native namespace packages. Consider using modern virtual environment tools.","message":"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.","severity":"breaking","affected_versions":"6.0+"},{"fix":"Upgrade your Python environment to 3.7 or newer, or pin `zope-exceptions<5.0` if you are on an unsupported Python version.","message":"Version 5.0 dropped support for Python 2.7, 3.5, and 3.6.","severity":"breaking","affected_versions":"5.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Zope 2, 3, 4, 5+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ImportError: cannot import name '...' from 'pkg_resources'"},{"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.","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.","error":"TypeError: 'str' object is not callable (when using __traceback_supplement__)"},{"fix":"Refactor your code to raise proper exception classes, such as `raise ValueError('My Error')`.","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.","error":"DeprecationWarning: string exceptions are deprecated"}]}