timing

openplaces timing module

Track execution time across script milestones and export as structured data.

Classes

Timer

Track time consumption across labeled milestones.

Module Contents

class openplaces.timing.Timer

Track time consumption across labeled milestones.

Two modes of use: 1. Milestones: mark points in time, duration = time since last mark 2. Steps: explicit begin/end or context manager for nested sections

Example

>>> timer = Timer('process_county')
>>> timer.mark('load')
>>> data = load_data()
>>> timer.mark('transform')
>>> result = transform(data)
>>> timer.mark('export')
>>> export(result)
>>> timer.finish()
>>> timer.save('timings.json')

mark(label: str, **metadata) → tuple[float, float]

Record a milestone. Duration = time since last mark (or creation).

begin(label: str, **metadata)

Begin a timed step (for explicit begin/end usage).

end() → tuple[float, float] | None

End the current timed step. Returns (wall_duration, cpu_duration).

property total_duration: float

Total elapsed time since timer creation.

property tracked_duration: float

Sum of all recorded step durations.

property records: list[dict[str, Any]]

All timing records as dictionaries.

to_dict() → dict[str, Any]

Export full timing data as dictionary.

save(path: pathlib.Path | str | None = None)

Save timing data to JSON file. Auto-finishes if needed.

save_csv(path: pathlib.Path | str | None = None)

Save timing data to CSV (one row per step). Auto-finishes if needed.

summary() → None

Human-readable summary.