xtr-stopwatch
Where the time went: named events, grouped by category, nested in sections — one set per unit of work.
Why?
"This request took 400 ms" is a start; "the listeners took 30, the queries 300, and the template the rest" is an answer. Getting there takes every piece of work timed under a name, a kind, and one shared starting point, so the pieces can be laid side by side on a timeline.
- ⏱️ Events by name. Start and stop
"load"; run it three times and it is one event with three periods. - 🏷️ Categories. Each event says what kind of work it is —
"orm","event_listener","template"— so a timeline can colour and filter by kind. - 🪆 Sections. Open one per request: every event in it is measured from the section's own origin, and the section is stored under an id once it closes.
- 🔀 Concurrent units of work stay apart. What is timed belongs to the calling context, so two requests served at once each see only their own events.
- 🕰️ A clock you can freeze. Readings come from an
xtr-clock clock — monotonic by default, a
MockClockin a test.
Install
uv add xtr-stopwatch
Requires Python 3.14.4+.
Quick start
from xtr_stopwatch import Stopwatch
stopwatch = Stopwatch()
stopwatch.open_section()
event = stopwatch.start("load-books", "orm")
... # the work
event.stop()
stopwatch.stop_section("request-42")
for name, event in stopwatch.get_section_events("request-42").items():
print(name, event.category, f"{event.get_duration():.1f} ms")
Events
start(name, category=None) opens a period of the event name in the current section and
returns the event; stop(name) closes the period opened last. Starting a running event again
opens a second, nested period. lap(name) closes one period and opens the next at the same
instant.
Keep the event start returns and stop it when the code that started it is the code that
ends it: the object stays the same even if the context is reset in between,
so its period still closes.
StopwatchEvent |
Answers |
|---|---|
name, category, origin |
what it is called, what kind of work it is ("default" when none was given), the instant its readings count from — milliseconds since the epoch |
get_periods() |
every closed period: start, end, duration, in milliseconds from origin |
get_start_time(), get_end_time() |
when it first began, when its last closed period ended |
get_duration() |
the time spent in every period, open ones counted up to now |
is_started(), ensure_stopped() |
whether a period is open; close every open one |
to_dict() |
all of the above as plain data, for JSON |
Sections
open_section() opens a section inside the current one; stop_section(section_id) closes the
current section and stores it under section_id, after which
get_section_events(section_id) returns its events by name. The events of a section all count
from the instant it opened, which is what puts them on one axis.
Opening a section starts SECTION_EVENT ("__section__") in it and SECTION_CHILD_EVENT
("__section__.child", category "section") in its parent, and closing it stops both — the
section's own duration is one of its events, and the parent records where the child sat in its
own time. open_section(section_id) reopens a stopped child of the current section, adding a
period to it.
Outside any section, events go to the root section, stored as ROOT ("__root__"), whose
events each count from the instant they first started.
has_open_section() tells whether the calling context has a section open, without starting
anything. Code that times what it does on a stopwatch it shares — every listener a dispatcher
runs — asks it first, so a context no unit of work times in, a worker's own loop, never
accumulates events.
Units of work
Everything a stopwatch times belongs to the calling context — the same contextvars mechanism
that keeps a server's concurrent requests apart — so
one stopwatch shared by a whole application gives every request only its own sections. Code
run in a copy of that context, such as a synchronous function a worker thread runs, times into
the same sections.
reset() starts the calling context afresh, with nothing timed. A unit of work calls it as it
begins; other contexts are untouched.
Testing
Freeze time with xtr-clock's MockClock and move it with sleep:
from xtr_clock import MockClock
from xtr_stopwatch import Stopwatch
clock = MockClock("2026-01-01 00:00:00")
stopwatch = Stopwatch(clock)
stopwatch.start("load")
clock.sleep(0.004)
assert stopwatch.stop("load").get_duration() == 4.0
Errors
Everything this library raises derives from StopwatchError.
| Error | Raised when |
|---|---|
EventNotStartedError |
an event is stopped or lapped while it is not running |
UnknownEventError |
get_event names an event the current section never started; also a LookupError |
NoStartedSectionError |
stop_section is called with only the root open |
UnknownSectionError |
open_section(section_id) names no child of the current section; also a LookupError |
Layout
xtr_stopwatch/
├── stopwatch.py Stopwatch, the sections of the calling context
├── section.py Section, the events sharing one origin
├── stopwatch_event.py StopwatchEvent, one named thing and its periods
├── stopwatch_period.py StopwatchPeriod, one start and its stop
└── exception/ StopwatchError, the root of everything this library raises
Development
Developed in the python-xtr monorepo, under
packages/xtr-stopwatch; run the commands below from there.
uv sync
uv run ruff check
uv run ruff format --check
uv run basedpyright
uv run ty check
uv run pytest
License
MIT — see LICENSE.
Metadata
Release files for xtr-stopwatch 7.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xtr_stopwatch-7.1.0.tar.gz | 13.0 kB | With provenance | Details for xtr_stopwatch-7.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_stopwatch-7.1.0-py3-none-any.whl | Python 3 | none | any | Details for xtr_stopwatch-7.1.0-py3-none-any.whl |
Total release size: 29.7 kB
Release files / xtr_stopwatch-7.1.0.tar.gz
| Download URL | xtr_stopwatch-7.1.0.tar.gz |
|---|---|
| Size | 13.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9b865b8b3db96c03180e4250c5145a757086272215763832ca60922301198630
|
|
BLAKE2b-256 checksum How to use checksums |
1344ab12486da09066deda03934ec53d358ef4b078db7fa03c4684e784735b9d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / xtr_stopwatch-7.1.0-py3-none-any.whl
| Download URL | xtr_stopwatch-7.1.0-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
41f957e85bf80b1f59727cf5ec0c652c33dde1bd3fa412c1bf65eb61df24cd4f
|
|
BLAKE2b-256 checksum How to use checksums |
246c9c0fe0a62b7981e0367b0f3b616d31a8934e3a593524838a4444217c3dac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for xtr-stopwatch 7.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xtr_stopwatch-7.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.