# pyauth/pyotp architecture

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

- Interactive diagram: https://gitdiagram.com/pyauth/pyotp
- Repository: https://github.com/pyauth/pyotp

## Overview

PyOTP is a Python library for generating and verifying HOTP and TOTP codes, plus creating and parsing authenticator provisioning URIs. An application uses its public API to create an OTP handler, then generates or verifies codes; provisioning can produce an otpauth URI for an authenticator app. The core OTP class supplies HMAC code generation, while utilities provide URI construction and timing-resistant comparison. The README documents secret-generation helpers and Steam TOTP support. This is a stateless library: applications manage secret storage and replay prevention. Arrows follow shown imports, calls, or README descriptions.

Main entry points: [`src/pyotp/__init__.py`](https://github.com/pyauth/pyotp/blob/main/src/pyotp/__init__.py) (Public API and URI Parsing), [`src/pyotp/totp.py`](https://github.com/pyauth/pyotp/blob/main/src/pyotp/totp.py) (TOTP), [`src/pyotp/hotp.py`](https://github.com/pyauth/pyotp/blob/main/src/pyotp/hotp.py) (HOTP), [`src/pyotp/contrib/steam.py`](https://github.com/pyauth/pyotp/blob/main/src/pyotp/contrib/steam.py) (Steam TOTP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["Public API and URI Parsing<br/>[__init__.py]"]
  node_random["Secret Generation<br/>[__init__.py]"]
end

subgraph group_algorithms["OTP Algorithms"]
  node_hotp["HOTP<br/>[hotp.py]"]
  node_totp["TOTP<br/>[totp.py]"]
  node_steam["Steam TOTP<br/>[steam.py]"]
end

subgraph group_shared["Shared Core"]
  node_otp["HMAC OTP Core<br/>[otp.py]"]
  node_utils["URI and Comparison<br/>[utils.py]"]
  node_compat["Random Compatibility<br/>[compat.py]"]
end

node_app(("Application"))
node_authenticator(("Authenticator App"))

node_app -->|"uses"| node_api
node_api -->|"constructs"| node_hotp
node_api -->|"constructs"| node_totp
node_api -->|"constructs"| node_steam
node_api -->|"provides"| node_random
node_random -->|"uses"| node_compat
node_hotp -->|"inherits"| node_otp
node_totp -->|"inherits"| node_otp
node_steam -->|"inherits"| node_totp
node_hotp -->|"uses"| node_utils
node_totp -->|"uses"| node_utils
node_authenticator -->|"imports URI"| node_api

click node_api "https://github.com/pyauth/pyotp/blob/main/src/pyotp/__init__.py"
click node_random "https://github.com/pyauth/pyotp/blob/main/src/pyotp/__init__.py"
click node_hotp "https://github.com/pyauth/pyotp/blob/main/src/pyotp/hotp.py"
click node_totp "https://github.com/pyauth/pyotp/blob/main/src/pyotp/totp.py"
click node_steam "https://github.com/pyauth/pyotp/blob/main/src/pyotp/contrib/steam.py"
click node_otp "https://github.com/pyauth/pyotp/blob/main/src/pyotp/otp.py"
click node_utils "https://github.com/pyauth/pyotp/blob/main/src/pyotp/utils.py"
click node_compat "https://github.com/pyauth/pyotp/blob/main/src/pyotp/compat.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_api,node_random toneBlue
class node_hotp,node_totp,node_steam toneAmber
class node_otp,node_utils,node_compat toneMint
class node_app,node_authenticator toneIndigo
```

## Components

### Public API

- [Public API and URI Parsing](https://github.com/pyauth/pyotp/blob/main/src/pyotp/__init__.py): `src/pyotp/__init__.py`
- [Secret Generation](https://github.com/pyauth/pyotp/blob/main/src/pyotp/__init__.py): `src/pyotp/__init__.py`

### OTP Algorithms

- [HOTP](https://github.com/pyauth/pyotp/blob/main/src/pyotp/hotp.py): `src/pyotp/hotp.py`
- [TOTP](https://github.com/pyauth/pyotp/blob/main/src/pyotp/totp.py): `src/pyotp/totp.py`
- [Steam TOTP](https://github.com/pyauth/pyotp/blob/main/src/pyotp/contrib/steam.py): `src/pyotp/contrib/steam.py`

### Shared Core

- [HMAC OTP Core](https://github.com/pyauth/pyotp/blob/main/src/pyotp/otp.py): `src/pyotp/otp.py`
- [URI and Comparison](https://github.com/pyauth/pyotp/blob/main/src/pyotp/utils.py): `src/pyotp/utils.py`
- [Random Compatibility](https://github.com/pyauth/pyotp/blob/main/src/pyotp/compat.py): `src/pyotp/compat.py`

### Other components

- **Application**
- **Authenticator App**

## Connections

- Application → Public API and URI Parsing: uses (evidence: `README.rst`)
- Public API and URI Parsing → HOTP: constructs (evidence: `src/pyotp/__init__.py`)
- Public API and URI Parsing → TOTP: constructs (evidence: `src/pyotp/__init__.py`)
- Public API and URI Parsing → Steam TOTP: constructs (evidence: `src/pyotp/__init__.py`)
- Public API and URI Parsing → Secret Generation: provides (evidence: `src/pyotp/__init__.py`)
- Secret Generation → Random Compatibility: uses (evidence: `src/pyotp/__init__.py`)
- HOTP → HMAC OTP Core: inherits (evidence: `src/pyotp/hotp.py`)
- TOTP → HMAC OTP Core: inherits (evidence: `src/pyotp/totp.py`)
- Steam TOTP → TOTP: inherits (evidence: `src/pyotp/contrib/steam.py`)
- HOTP → URI and Comparison: uses (evidence: `src/pyotp/hotp.py`)
- TOTP → URI and Comparison: uses (evidence: `src/pyotp/totp.py`)
- Authenticator App → Public API and URI Parsing: imports URI (evidence: `README.rst`)
