# python/typeshed architecture

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

- Interactive diagram: https://gitdiagram.com/python/typeshed
- Repository: https://github.com/python/typeshed

## Overview

Typeshed is a repository of Python type annotations, not a type checker: it supplies stubs that type checkers use for analysis, inference, and autocompletion. The main workflow is a developer using a checker, which consumes bundled standard-library and builtin stubs, plus separately installed third-party stubs where needed. The README also identifies `_typeshed` as a standard-library utility package. Source excerpts chiefly cover contributor utilities, so relationships and capabilities beyond those documented in the README are not inferred from unsampled implementation.

Main entry points: [`stdlib`](https://github.com/python/typeshed/tree/main/stdlib) (Standard library), [`stubs`](https://github.com/python/typeshed/tree/main/stubs) (Third-party packages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_stub_data["Stub data"]
  node_stdlib_stubs["Standard library"]
  node_builtin_stubs["Builtins"]
  node_typeshed_utilities["_typeshed utilities"]
  node_third_party_stubs["Third-party packages"]
end

subgraph group_catalog["Repository utilities"]
  node_metadata["Stub metadata<br/>[metadata.py]"]
  node_paths["Repository paths<br/>[paths.py]"]
end

subgraph group_consumption["Stub consumption"]
  node_checker["Type checker"]
  node_type_results(("Analysis and completion"))
end

node_developer(("Developer"))

node_developer -->|"uses"| node_checker
node_checker -->|"uses bundled stubs"| node_stdlib_stubs
node_checker -->|"uses bundled stubs"| node_builtin_stubs
node_checker -->|"uses installed stubs"| node_third_party_stubs
node_checker -->|"supports"| node_type_results

click node_stdlib_stubs "https://github.com/python/typeshed/tree/main/stdlib"
click node_builtin_stubs "https://github.com/python/typeshed/tree/main/stdlib"
click node_typeshed_utilities "https://github.com/python/typeshed/tree/main/stdlib/_typeshed"
click node_third_party_stubs "https://github.com/python/typeshed/tree/main/stubs"
click node_metadata "https://github.com/python/typeshed/blob/main/lib/ts_utils/metadata.py"
click node_paths "https://github.com/python/typeshed/blob/main/lib/ts_utils/paths.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_stdlib_stubs,node_builtin_stubs,node_typeshed_utilities,node_third_party_stubs toneBlue
class node_metadata,node_paths toneAmber
class node_checker,node_type_results toneMint
class node_developer toneIndigo
```

## Components

### Stub data

- [Standard library](https://github.com/python/typeshed/tree/main/stdlib): `stdlib`
- [Builtins](https://github.com/python/typeshed/tree/main/stdlib): `stdlib`
- [_typeshed utilities](https://github.com/python/typeshed/tree/main/stdlib/_typeshed): `stdlib/_typeshed`
- [Third-party packages](https://github.com/python/typeshed/tree/main/stubs): `stubs`

### Repository utilities

- [Stub metadata](https://github.com/python/typeshed/blob/main/lib/ts_utils/metadata.py): `lib/ts_utils/metadata.py`
- [Repository paths](https://github.com/python/typeshed/blob/main/lib/ts_utils/paths.py): `lib/ts_utils/paths.py`

### Stub consumption

- **Type checker**
- **Analysis and completion**

### Other components

- **Developer**

## Connections

- Developer → Type checker: uses (evidence: `README.md`)
- Type checker → Standard library: uses bundled stubs (evidence: `README.md`)
- Type checker → Builtins: uses bundled stubs (evidence: `README.md`)
- Type checker → Third-party packages: uses installed stubs (evidence: `README.md`)
- Type checker → Analysis and completion: supports (evidence: `README.md`)
