# agronholm/exceptiongroup architecture

> Architecture diagram of the GitHub repository agronholm/exceptiongroup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agronholm/exceptiongroup
- Repository: https://github.com/agronholm/exceptiongroup

## Overview

##### Project Type and Purpose
- This is a backport library for Python’s BaseExceptionGroup/ExceptionGroup (PEP 654).
- It provides:
- Core exception group classes
- A catch() context‐manager API
- A suppress() API
- Monkey‐patching of traceback.TracebackException and sys.excepthook
- Special versions of traceback.* functions

##### File Structure
- src/exceptiongroup/: the package root
- _exceptions.py → defines BaseExceptionGroup & ExceptionGroup
- _catch.py → implements catch()
- _suppress.py → implements suppress()
- _formatting.py → monkey patches TracebackException & provides format_* overrides
- __init__.py → imports and installs monkey patches on import
- py.typed → indicates PEP 561 typing support
- tests/: covers unit tests for each module
- CI/config files (.github/, pyproject.toml, pre‐commit, etc.)

##### Extract Key Architectural Elements from README
- “On import, if Python <3.11, install patches; otherwise no‐ops.”
- Two extension points: sys.excepthook override & patched TracebackException.
- Exposed public API: catch(), suppress(), ExceptionGroup classes, and patched traceback functions.

##### Main Components & Their Relationships
A. Public API Layer
– exceptiongroup.catch() (context manager)
– exceptiongroup.suppress() (context manager)
– exceptiongroup.BaseExceptionGroup & ExceptionGroup classes
– fallback or no‐op behavior on Python 3.11+

B. Core Logic Layer
– _exceptions: exception group data structures
– _catch: logic for iterating and dispatching handlers
– _suppress: context manager that re‐raises filtered groups

C. Formatting / Monkey‐Patch Layer
– _formatting:
- Patches traceback.TracebackException.__init__ & .format()
- Implements format_exception, format_exception_only, print_exception, print_exc
– sys.excepthook hook installation
– Environment‐based toggle (EXCEPTIONGROUP_NO_PATCH)

D. Test Suite
– tests for each corner: catching, suppressing, formatting, hook behavior, Python 3.11 compatibility.

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- Data Structures (_exceptions) vs. Control Flow (_catch/_suppress) vs. I/O/Presentation (_formatting).
- Lazy initialization: patches applied at import only once, gated by environment and Python version.
- Backport/Adapter pattern: adapts new language features for older runtimes.
- Context‐manager-based APIs for resource‐like semantics (catch, suppress).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        Init["__init__.py"]:::public_api
        CatchAPI["catch()"]:::public_api
        SuppressAPI["suppress()"]:::public_api
        ExGroupAPI["BaseExceptionGroup & ExceptionGroup"]:::public_api
        PyTyped["py.typed"]:::public_api
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        direction TB
        Exceptions["_exceptions.py"]:::core
        CatchLogic["_catch.py"]:::core
        SuppressLogic["_suppress.py"]:::core
    end

    %% Formatting / Monkey-Patch Layer
    subgraph "Formatting & Patching Layer"
        direction TB
        Formatting["_formatting.py"]:::patch
        TracebackEX["traceback.TracebackException"]:::external
        SysHook["sys.excepthook"]:::external
    end

    %% Test Suite
    subgraph "Test Suite"
        direction TB
        TE["tests/test_exceptions.py"]:::test
        TC["tests/test_catch.py"]:::test
        TC311["tests/test_catch_py311.py"]:::test
        TS["tests/test_suppress.py"]:::test
        TF["tests/test_formatting.py"]:::test
        TA["tests/test_apport_monkeypatching.py"]:::test
        TA2["tests/apport_excepthook.py"]:::test
        CT["tests/check_types.py"]:::test
        CF["tests/conftest.py"]:::test
    end

    %% Connections - Import & Initialization
    Import["import exceptiongroup"]:::external -->|initializes| Init
    Init -->|conditionally apply patches| Formatting
    Init -->|exports| CatchAPI
    Init -->|exports| SuppressAPI
    Init -->|exports| ExGroupAPI

    %% Public API to Core Logic
    CatchAPI -->|"context-manager entry"| CatchLogic
    SuppressAPI -->|"context-manager entry"| SuppressLogic
    ExGroupAPI -->|"data structures"| Exceptions

    %% Formatting patches
    Formatting -->|monkey-patch| TracebackEX
    Formatting -->|override hook| SysHook

    %% Tests depend on modules
    TE --> Exceptions
    TC --> CatchLogic
    TC311 --> CatchLogic
    TS --> SuppressLogic
    TF --> Formatting
    TA --> Formatting
    TA2 --> SysHook
    CT --> ExGroupAPI
    CF --> Init

    %% Click Events
    click Init "https://github.com/agronholm/exceptiongroup/blob/main/src/exceptiongroup/__init__.py"
    click Exceptions "https://github.com/agronholm/exceptiongroup/blob/main/src/exceptiongroup/_exceptions.py"
    click CatchLogic "https://github.com/agronholm/exceptiongroup/blob/main/src/exceptiongroup/_catch.py"
    click SuppressLogic "https://github.com/agronholm/exceptiongroup/blob/main/src/exceptiongroup/_suppress.py"
    click Formatting "https://github.com/agronholm/exceptiongroup/blob/main/src/exceptiongroup/_formatting.py"
    click PyTyped "https://github.com/agronholm/exceptiongroup/blob/main/src/exceptiongroup/py.typed"
    click TE "https://github.com/agronholm/exceptiongroup/blob/main/tests/test_exceptions.py"
    click TC "https://github.com/agronholm/exceptiongroup/blob/main/tests/test_catch.py"
    click TC311 "https://github.com/agronholm/exceptiongroup/blob/main/tests/test_catch_py311.py"
    click TS "https://github.com/agronholm/exceptiongroup/blob/main/tests/test_suppress.py"
    click TF "https://github.com/agronholm/exceptiongroup/blob/main/tests/test_formatting.py"
    click TA "https://github.com/agronholm/exceptiongroup/blob/main/tests/test_apport_monkeypatching.py"
    click TA2 "https://github.com/agronholm/exceptiongroup/blob/main/tests/apport_excepthook.py"
    click CT "https://github.com/agronholm/exceptiongroup/blob/main/tests/check_types.py"
    click CF "https://github.com/agronholm/exceptiongroup/blob/main/tests/conftest.py"

    %% Styles
    classDef public_api fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6af,stroke:#333,stroke-width:1px
    classDef patch fill:#fa6,stroke:#333,stroke-width:1px
    classDef test fill:#eee,stroke:#666,stroke-dasharray: 5 5,stroke-width:1px
    classDef external fill:#fff,stroke:#999,stroke-width:1px
```
