# hh-mwb/timerun architecture

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

- Interactive diagram: https://gitdiagram.com/hh-mwb/timerun
- Repository: https://github.com/hh-mwb/timerun

## Overview

TimeRun is a single-file Python timing library. A developer uses `Timer` as a context manager or decorator; it measures wall-clock and CPU time and produces a `Measurement` containing `TimeSpan` values and optional metadata. Decorator mode retains recent measurements, while optional callbacks run at measurement start and end. The README and sampled source establish these behaviors; implementation details beyond the excerpt are not mapped.

Main entry points: [`timerun.py`](https://github.com/hh-mwb/timerun/blob/main/timerun.py) (Timer)

## Diagram (Mermaid)

```mermaid
flowchart TD

node_developer(("Developer code"))
node_timer["Timer<br/>[timerun.py]"]
node_measured["Measured code"]
node_measurement["Measurement<br/>[timerun.py]"]
node_timespan["TimeSpan<br/>[timerun.py]"]
node_callbacks["User callbacks"]
node_history["Measurement deque<br/>[timerun.py]"]
node_clocks["System clocks"]

node_developer -->|"uses"| node_timer
node_timer -->|"wraps or scopes"| node_measured
node_timer -->|"reads"| node_clocks
node_timer -->|"creates and updates"| node_measurement
node_timer -->|"records durations"| node_timespan
node_timer -.->|"invokes"| node_callbacks
node_timer -->|"appends measurements"| node_history
node_timer -->|"yields measurement"| node_developer

click node_timer "https://github.com/hh-mwb/timerun/blob/main/timerun.py"
click node_measurement "https://github.com/hh-mwb/timerun/blob/main/timerun.py"
click node_timespan "https://github.com/hh-mwb/timerun/blob/main/timerun.py"
click node_history "https://github.com/hh-mwb/timerun/blob/main/timerun.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_developer,node_measured,node_clocks toneIndigo
class node_timer,node_measurement,node_timespan,node_history toneTeal
class node_callbacks toneBlue
```

## Components

### Other components

- **Developer code**
- [Timer](https://github.com/hh-mwb/timerun/blob/main/timerun.py): `timerun.py`
- **Measured code**
- [Measurement](https://github.com/hh-mwb/timerun/blob/main/timerun.py): `timerun.py`
- [TimeSpan](https://github.com/hh-mwb/timerun/blob/main/timerun.py): `timerun.py`
- **User callbacks**
- [Measurement deque](https://github.com/hh-mwb/timerun/blob/main/timerun.py): `timerun.py`
- **System clocks**

## Connections

- Developer code → Timer: uses
- Timer → Measured code: wraps or scopes
- Timer → System clocks: reads
- Timer → Measurement: creates and updates
- Timer → TimeSpan: records durations
- Timer → User callbacks: invokes
- Timer → Measurement deque: appends measurements
- Timer → Developer code: yields measurement