# jd/tenacity architecture

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

- Interactive diagram: https://gitdiagram.com/jd/tenacity
- Repository: https://github.com/jd/tenacity

## Overview

##### Project type and purpose
- This is an open-source Python library (“tenacity”) whose sole purpose is to provide a flexible, pluggable retrying system for arbitrary callables (sync and async).
- It is **not** a full-stack app; it’s a library/tool that application code imports, configures via decorators or context managers, and then uses to automatically retry operations under various strategies.

##### File structure
- **Top-level modules and dirs**
- tenacity/           ← core package
- tests/              ← unit tests verifying behavior
- doc/, releasenotes/ ← documentation and changelog
- CI config (GitHub Actions, tox.ini) and packaging (setup.py, pyproject.toml, setup.cfg)
- **Within tenacity/**
- `_utils.py`         ← internal shared utilities
- `retry.py`          ← core retry engine (Retrying class, retry decorator)
- `stop.py`           ← pluggable stop strategies (stop after attempts, stop after delay)
- `wait.py`           ← wait strategies (fixed, exponential backoff, jitter)
- `before.py` & `after.py` ← hooks invoked before sleep / after call
- `nap.py`            ← core sleeping abstraction
- `asyncio/`          ← mirror modules for async/await environments
- `tornadoweb.py`     ← Tornado IOLoop compatibility layer
- `py.typed`          ← type-checking marker for PEP 561

##### Extract insights from the README / docs
- The entry point for users is in `retry.py` (the `retry` decorator and `Retrying` class).
- Documentation (`doc/source/index.rst`) explains configuration of retry, stop, wait, before/after, and integration points (asyncio, Tornado).
- There is emphasis on pluggability: you supply your own callables for stop and wait strategies or use the built-ins.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    Client["Client Application\n(user code)"]:::client

    %% Shared Utilities and Markers
    Utils["Shared Utilities\n_utils.py"]:::util
    PEP["Type‐checking Marker\npy.typed"]:::util

    %% Documentation and Tests
    Docs["Documentation Entry Point\ndoc/source/index.rst"]:::ext
    Tests["Unit Tests Suite\ntests/"]:::ext

    %% Sync Path
    subgraph "Sync Path"
        RetrySync["Retry Core (sync)\nretry.py"]:::core
        Before["Hook - before attempt\nbefore.py"]:::hook
        After["Hook - after attempt\nafter.py"]:::hook
        Stop["Stop Strategies\nstop.py"]:::strategy
        Wait["Wait Strategies\nwait.py"]:::strategy
        Nap["Sleeping Mechanism\nnap.py"]:::edge
    end

    %% Async Path
    subgraph "Async Support Layer"
        RetryAsync["Retry Core (async)\nasyncio/retry.py"]:::core
        StopAsync["Stop Strategies\nstop.py"]:::strategy
        WaitAsync["Wait Strategies\nwait.py"]:::strategy
        BeforeAsync["Hooks (async)\nbefore/after"]:::hook
        NapAsync["Async Sleep\nnap.async_sleep"]:::edge
        Tornado["Tornado IOLoop Integration\ntornadoweb.py"]:::edge
    end

    %% Connections
    Client --> RetrySync
    Client --> RetryAsync

    Utils --> RetrySync
    Utils --> RetryAsync
    PEP --- RetrySync
    PEP --- RetryAsync

    RetrySync --> Before
    RetrySync --> After
    RetrySync --> Stop
    RetrySync --> Wait
    RetrySync --> Nap

    RetryAsync --> StopAsync
    RetryAsync --> WaitAsync
    RetryAsync --> BeforeAsync
    RetryAsync --> NapAsync
    RetryAsync --> Tornado

    Docs --- RetrySync
    Docs --- RetryAsync
    Tests --- RetrySync
    Tests --- RetryAsync

    %% Click Events
    click RetrySync "https://github.com/jd/tenacity/blob/main/tenacity/retry.py"
    click RetryAsync "https://github.com/jd/tenacity/blob/main/tenacity/asyncio/retry.py"
    click Stop "https://github.com/jd/tenacity/blob/main/tenacity/stop.py"
    click StopAsync "https://github.com/jd/tenacity/blob/main/tenacity/stop.py"
    click Wait "https://github.com/jd/tenacity/blob/main/tenacity/wait.py"
    click WaitAsync "https://github.com/jd/tenacity/blob/main/tenacity/wait.py"
    click Before "https://github.com/jd/tenacity/blob/main/tenacity/before.py"
    click After "https://github.com/jd/tenacity/blob/main/tenacity/after.py"
    click Nap "https://github.com/jd/tenacity/blob/main/tenacity/nap.py"
    click Tornado "https://github.com/jd/tenacity/blob/main/tenacity/tornadoweb.py"
    click Utils "https://github.com/jd/tenacity/blob/main/tenacity/_utils.py"
    click PEP "https://github.com/jd/tenacity/blob/main/tenacity/py.typed"
    click Tests "https://github.com/jd/tenacity/tree/main/tests/"
    click Docs "https://github.com/jd/tenacity/blob/main/doc/source/index.rst"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px;
    classDef core fill:#bbf,stroke:#333,stroke-width:1px;
    classDef strategy fill:#fbf,stroke:#333,stroke-width:1px;
    classDef hook fill:#bfb,stroke:#333,stroke-width:1px;
    classDef edge fill:#ffe,stroke:#333,stroke-width:1px;
    classDef util fill:#ddd,stroke:#333,stroke-width:1px;
    classDef ext fill:#eee,stroke:#333,stroke-width:1px;
```
