# pallets/itsdangerous architecture

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

- Interactive diagram: https://gitdiagram.com/pallets/itsdangerous
- Repository: https://github.com/pallets/itsdangerous

## Overview

ItsDangerous is a Python library for safely passing data through untrusted environments: it serializes values into tokens, signs them, and verifies and loads them later. Users can choose ordinary signing, timestamp-based expiration, or URL-safe serialization with optional compression. The sampled sources show the main implementation layers and their dependencies; the README documents the user workflow. The graph omits uncertain internal calls where the excerpts do not show them.

Main entry points: [`src/itsdangerous/serializer.py`](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/serializer.py) (Serializer), [`src/itsdangerous/url_safe.py`](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/url_safe.py) (URL-Safe Serializer), [`src/itsdangerous/encoding.py`](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/encoding.py) (Encoding), [`src/itsdangerous/timed.py`](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/timed.py) (Timestamp Signer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_token_formats["Token Formats"]
  node_url_serializer["URL-Safe Serializer<br/>[url_safe.py]"]
  node_timed_serializer["Timed Serializer<br/>[timed.py]"]
  node_serializer["Serializer<br/>[serializer.py]"]
end

subgraph group_signing["Signing"]
  node_timestamp_signer["Timestamp Signer<br/>[timed.py]"]
  node_signer["Signer<br/>[signer.py]"]
end

subgraph group_shared_support["Shared Support"]
  node_encoding["Encoding<br/>[encoding.py]"]
  node_compact_json["Compact JSON<br/>[_json.py]"]
  node_exceptions["Data Exceptions<br/>[exc.py]"]
end

node_user(("Library User"))

node_user -->|"creates and loads tokens"| node_url_serializer
node_url_serializer -->|"extends serialization"| node_serializer
node_url_serializer -->|"extends timed serialization"| node_timed_serializer
node_url_serializer -->|"uses default JSON"| node_compact_json
node_url_serializer -->|"encodes payloads"| node_encoding
node_timed_serializer -->|"extends serialization"| node_serializer
node_timed_serializer -->|"selects default signer"| node_timestamp_signer
node_timestamp_signer -->|"extends signing"| node_signer
node_timestamp_signer -->|"loads payloads"| node_serializer
node_timestamp_signer -->|"encodes timestamps"| node_encoding
node_serializer -->|"creates signers"| node_signer
node_serializer -->|"normalizes bytes"| node_encoding
node_signer -->|"encodes signatures"| node_encoding
node_serializer -->|"raises data errors"| node_exceptions
node_signer -->|"raises signature errors"| node_exceptions
node_encoding -->|"raises decode errors"| node_exceptions

click node_url_serializer "https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/url_safe.py"
click node_timed_serializer "https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/timed.py"
click node_serializer "https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/serializer.py"
click node_timestamp_signer "https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/timed.py"
click node_signer "https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/signer.py"
click node_encoding "https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/encoding.py"
click node_compact_json "https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/_json.py"
click node_exceptions "https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/exc.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_url_serializer,node_timed_serializer,node_serializer,node_user toneBlue
class node_timestamp_signer,node_signer toneAmber
class node_encoding,node_compact_json,node_exceptions toneMint
```

## Components

### Token Formats

- [URL-Safe Serializer](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/url_safe.py): `src/itsdangerous/url_safe.py`
- [Timed Serializer](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/timed.py): `src/itsdangerous/timed.py`
- [Serializer](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/serializer.py): `src/itsdangerous/serializer.py`

### Signing

- [Timestamp Signer](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/timed.py): `src/itsdangerous/timed.py`
- [Signer](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/signer.py): `src/itsdangerous/signer.py`

### Shared Support

- [Encoding](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/encoding.py): `src/itsdangerous/encoding.py`
- [Compact JSON](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/_json.py): `src/itsdangerous/_json.py`
- [Data Exceptions](https://github.com/pallets/itsdangerous/blob/main/src/itsdangerous/exc.py): `src/itsdangerous/exc.py`

### Other components

- **Library User**

## Connections

- Library User → URL-Safe Serializer: creates and loads tokens (evidence: `README.md`)
- URL-Safe Serializer → Serializer: extends serialization (evidence: `src/itsdangerous/url_safe.py`)
- URL-Safe Serializer → Timed Serializer: extends timed serialization (evidence: `src/itsdangerous/url_safe.py`)
- URL-Safe Serializer → Compact JSON: uses default JSON (evidence: `src/itsdangerous/url_safe.py`)
- URL-Safe Serializer → Encoding: encodes payloads (evidence: `src/itsdangerous/url_safe.py`)
- Timed Serializer → Serializer: extends serialization (evidence: `src/itsdangerous/timed.py`)
- Timed Serializer → Timestamp Signer: selects default signer (evidence: `src/itsdangerous/timed.py`)
- Timestamp Signer → Signer: extends signing (evidence: `src/itsdangerous/timed.py`)
- Timestamp Signer → Serializer: loads payloads (evidence: `src/itsdangerous/timed.py`)
- Timestamp Signer → Encoding: encodes timestamps (evidence: `src/itsdangerous/timed.py`)
- Serializer → Signer: creates signers (evidence: `src/itsdangerous/serializer.py`)
- Serializer → Encoding: normalizes bytes (evidence: `src/itsdangerous/serializer.py`)
- Signer → Encoding: encodes signatures (evidence: `src/itsdangerous/signer.py`)
- Serializer → Data Exceptions: raises data errors (evidence: `src/itsdangerous/serializer.py`)
- Signer → Data Exceptions: raises signature errors (evidence: `src/itsdangerous/signer.py`)
- Encoding → Data Exceptions: raises decode errors (evidence: `src/itsdangerous/encoding.py`)