# python-thread/thread architecture

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

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

## Overview

Thread is a Python threading extension for type-safe thread execution, result retrieval, hooks, and dataset-oriented concurrent processing. Users can instantiate Thread directly or invoke a threaded-decorated function; for datasets, processor creates and starts ConcurrentProcessing, which partitions work into chunks and runs workers. The core thread wrapper handles status, results, and errors, with shared configuration and typing support. The graph reflects the sampled implementation and indexed references; detailed CLI behavior and other unsampled internals are not inferred.

Main entry points: [`src/thread/thread.py`](https://github.com/python-thread/thread/blob/main/src/thread/thread.py) (Thread and concurrent processing), [`src/thread/decorators/_threaded.py`](https://github.com/python-thread/thread/blob/main/src/thread/decorators/_threaded.py) (Thread decorator), [`src/thread/decorators/_processor.py`](https://github.com/python-thread/thread/blob/main/src/thread/decorators/_processor.py) (Processor decorator), [`src/thread/cli.py`](https://github.com/python-thread/thread/blob/main/src/thread/cli.py) (CLI adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_threaded["Thread decorator<br/>[_threaded.py]"]
  node_processor["Processor decorator<br/>[_processor.py]"]
  node_cli["CLI adapter<br/>[cli.py]"]
end

subgraph group_execution["Concurrent execution"]
  node_core["Thread and concurrent processing<br/>[thread.py]"]
end

subgraph group_support["Shared support"]
  node_chunking["Chunk splitter<br/>[algorithm.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_errors["Thread exceptions<br/>[exceptions.py]"]
  node_types["Typing protocols<br/>[_types.py]"]
end

node_user(("Python caller"))
node_dataset["Input dataset"]
node_python_threads["Python threading"]
node_cli_service["Optional thread-cli"]

node_user -->|"decorates function"| node_threaded
node_threaded -->|"creates and starts"| node_core
node_user -->|"decorates function"| node_processor
node_user -->|"supplies"| node_dataset
node_processor -->|"creates and starts"| node_core
node_core -->|"extends and starts"| node_python_threads
node_core -->|"splits dataset"| node_chunking
node_core -->|"reads settings"| node_settings
node_core -->|"raises and handles"| node_errors
node_threaded -->|"uses type definitions"| node_types
node_processor -->|"uses type definitions"| node_types
node_user -.->|"invokes command"| node_cli
node_cli -->|"loads optionally"| node_cli_service

click node_threaded "https://github.com/python-thread/thread/blob/main/src/thread/decorators/_threaded.py"
click node_processor "https://github.com/python-thread/thread/blob/main/src/thread/decorators/_processor.py"
click node_core "https://github.com/python-thread/thread/blob/main/src/thread/thread.py"
click node_chunking "https://github.com/python-thread/thread/blob/main/src/thread/utils/algorithm.py"
click node_settings "https://github.com/python-thread/thread/blob/main/src/thread/utils/config.py"
click node_errors "https://github.com/python-thread/thread/blob/main/src/thread/exceptions.py"
click node_types "https://github.com/python-thread/thread/blob/main/src/thread/_types.py"
click node_cli "https://github.com/python-thread/thread/blob/main/src/thread/cli.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_threaded,node_processor,node_cli toneBlue
class node_core toneAmber
class node_chunking,node_settings,node_errors,node_types toneMint
class node_user,node_dataset,node_python_threads,node_cli_service toneIndigo
```

## Components

### Public API

- [Thread decorator](https://github.com/python-thread/thread/blob/main/src/thread/decorators/_threaded.py): `src/thread/decorators/_threaded.py`
- [Processor decorator](https://github.com/python-thread/thread/blob/main/src/thread/decorators/_processor.py): `src/thread/decorators/_processor.py`
- [CLI adapter](https://github.com/python-thread/thread/blob/main/src/thread/cli.py): `src/thread/cli.py`

### Concurrent execution

- [Thread and concurrent processing](https://github.com/python-thread/thread/blob/main/src/thread/thread.py): `src/thread/thread.py`

### Shared support

- [Chunk splitter](https://github.com/python-thread/thread/blob/main/src/thread/utils/algorithm.py): `src/thread/utils/algorithm.py`
- [Runtime settings](https://github.com/python-thread/thread/blob/main/src/thread/utils/config.py): `src/thread/utils/config.py`
- [Thread exceptions](https://github.com/python-thread/thread/blob/main/src/thread/exceptions.py): `src/thread/exceptions.py`
- [Typing protocols](https://github.com/python-thread/thread/blob/main/src/thread/_types.py): `src/thread/_types.py`

### Other components

- **Python caller**
- **Input dataset**
- **Python threading**
- **Optional thread-cli**

## Connections

- Python caller → Thread decorator: decorates function (evidence: `src/thread/decorators/_threaded.py`)
- Thread decorator → Thread and concurrent processing: creates and starts (evidence: `src/thread/decorators/_threaded.py`)
- Python caller → Processor decorator: decorates function (evidence: `src/thread/decorators/_processor.py`)
- Python caller → Input dataset: supplies (evidence: `README.md`)
- Processor decorator → Thread and concurrent processing: creates and starts (evidence: `src/thread/decorators/_processor.py`)
- Thread and concurrent processing → Python threading: extends and starts (evidence: `src/thread/thread.py`)
- Thread and concurrent processing → Chunk splitter: splits dataset (evidence: `src/thread/thread.py`)
- Thread and concurrent processing → Runtime settings: reads settings (evidence: `src/thread/thread.py`)
- Thread and concurrent processing → Thread exceptions: raises and handles (evidence: `src/thread/thread.py`)
- Thread decorator → Typing protocols: uses type definitions (evidence: `src/thread/decorators/_threaded.py`)
- Processor decorator → Typing protocols: uses type definitions (evidence: `src/thread/decorators/_processor.py`)
- Python caller → CLI adapter: invokes command
- CLI adapter → Optional thread-cli: loads optionally (evidence: `src/thread/cli.py`)