timerun 0.6.1__tar.gz → 0.7.0__tar.gz

timerun-0.7.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: timerun
+Version: 0.7.0
+Summary: Structured wall-clock & CPU timing for Python (stdlib only). Zero dependencies, nanosecond precision, and ready for your logs, metrics, and OpenTelemetry.
+Author-email: HH-MWB <h.hong@mail.com>
+License: MIT
+Project-URL: Homepage, https://hh-mwb.github.io/timerun/
+Project-URL: Documentation, https://hh-mwb.github.io/timerun/
+Project-URL: Repository, https://github.com/HH-MWB/timerun
+Project-URL: Issues, https://github.com/HH-MWB/timerun/issues
+Project-URL: Changelog, https://github.com/HH-MWB/timerun/releases
+Project-URL: PyPI, https://pypi.org/project/timerun
+Keywords: time,timing,measurement,measurements,elapsed,stopwatch,timer,performance,latency,profiler,benchmarking,telemetry,opentelemetry,wall-clock,cpu-time,asyncio,fastapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://github.com/HH-MWB/timerun">
+    <img src="https://github.com/user-attachments/assets/00f08873-3ee5-4ee4-a41f-f9eda37fc30d" alt="TimeRun">
+  </a>
+</p>
+
+<p align="center">
+  <strong>Structured, zero-dependency Python timing for humans and telemetry.</strong><br>
+  Instantly isolate wall-clock latency from CPU burn across sync, async, and generators.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/timerun/"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/timerun.svg"></a>
+  <a href="https://codecov.io/gh/HH-MWB/timerun"><img alt="Coverage" src="https://codecov.io/gh/HH-MWB/timerun/branch/main/graph/badge.svg"></a>
+  <a href="https://github.com/HH-MWB/timerun/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/timerun.svg"></a>
+  <a href="https://pepy.tech/project/timerun"><img alt="Total Downloads" src="https://static.pepy.tech/badge/timerun"></a>
+</p>
+
+---
+
+## Quickstart
+
+### 1. Measure Code Blocks (Wall vs. CPU)
+
+Wrap any block in `with Timer() as m:` (or `async with Timer() as m:`). On exit, `m.wall_time` and `m.cpu_time` are immediately available:
+
+```python
+import time
+from timerun import Timer
+
+with Timer() as m:
+    time.sleep(0.05)  # Simulates network I/O or database wait
+    total = sum(i * i for i in range(100_000))  # Simulates CPU computation
+
+print("Elapsed (Wall):", m.wall_time.timedelta)  # e.g., 0:00:00.055120
+print("Compute (CPU):  ", m.cpu_time.timedelta)  # e.g., 0:00:00.005110
+```
+
+> **Why both?** If wall time is 2 seconds but CPU time is 5 milliseconds, your code spent 99.7% of its time waiting on I/O. If both are 2 seconds, you have a CPU bottleneck.
+
+### 2. Time Functions and Generators
+
+Use `@Timer()` on sync or async functions. The wrapped function retains a bounded deque of measurements:
+
+```python
+from timerun import Timer
+
+
+@Timer(maxlen=100)
+def process_batch(items):
+    return [x * 2 for x in items]
+
+
+process_batch([1, 2, 3])
+
+last = process_batch.measurements[-1]
+print("Wall time:", last.wall_time.timedelta)
+print("CPU time: ", last.cpu_time.timedelta)
+```
+
+### 3. Stream to Logs & Observability
+
+Use `on_end` to ship timings directly to your logs, OpenTelemetry, Prometheus, or Datadog without adding vendor dependencies to your core logic:
+
+```python
+import logging
+from timerun import Timer
+
+logger = logging.getLogger("app")
+
+with Timer(
+    metadata={"service": "checkout", "user_id": "u-123"},
+    on_end=lambda m: logger.info(
+        "checkout_completed",
+        extra={
+            "wall_ms": m.wall_time.duration / 1e6,
+            "cpu_ms": m.cpu_time.duration / 1e6,
+            **m.metadata,
+        },
+    ),
+):
+    pass  # your operation
+```
+
+## Installation
+
+```bash
+pip install timerun
+```
+
+*Requires Python 3.10+.*
+
+## Why TimeRun?
+
+When code runs slowly, **is it waiting on network/disk I/O, or burning CPU?**
+
+- `time.perf_counter()` only gives a raw float of elapsed wall time. Measuring CPU time requires manual `time.thread_time()` calls and boilerplate.
+- Profilers (`cProfile`, `py-spy`) and APM agents (`Datadog`, `New Relic`) introduce binary dependencies, sampling overhead, or vendor lock-in.
+- Naive timing patterns risk race conditions and crosstalk in concurrent `asyncio` tasks or multi-threaded workers.
+
+TimeRun provides clean, structured timing with sub-microsecond overhead:
+
+| Feature | Manual `time.perf_counter()` | Profilers (`cProfile`, `py-spy`) | APM Agents (`Datadog`, `New Relic`) | **TimeRun** |
+| :--- | :---: | :---: | :---: | :---: |
+| **Dependencies** | None | Extra tooling | Large binary agents | **Zero (stdlib only)** |
+| **Wall vs. CPU Breakdown** | ❌ Manual boilerplate | ⚠️ Profiling overhead | ❌ Usually wall only | **✅ Built-in & precise** |
+| **Structured Output** | ❌ Raw floats | ❌ Binary trace files | ⚠️ Proprietary format | **✅ Structured `Measurement`** |
+| **Asyncio & Thread Safe** | ❌ Race condition risk | ⚠️ Global runtime cost | ✅ Handled by agent | **✅ Task & Thread isolated** |
+| **Telemetry Hooks** | ❌ Build it yourself | ❌ Offline analysis only | ⚠️ Vendor locked | **✅ Agnostic (`on_end`)** |
+| **Footprint** | 0 LOC | Heavy | Large background daemon | **Single file (~500 LOC)** |
+
+## Key Capabilities
+
+- **Zero Supply-Chain Risk:** Pure Python standard library only (`time`, `dataclasses`, `contextvars`); vendorable as a single file (`timerun.py`).
+- **Context Isolation:** Native `ContextVar` stacks ensure concurrent `asyncio` tasks and threads never mix up measurements.
+- **Sub-Microsecond Overhead:** Slotted dataclasses and integer nanoseconds keep internal overhead under ~0.4 µs.
+- **Full Async & Generator Support:** Accurately times coroutines, synchronous generators, and asynchronous streaming generators across full iteration.
+- **100% Test Coverage:** Verified with comprehensive Behavior-Driven Development (BDD) test suites.
+
+## Documentation
+
+- **[Documentation Site](https://hh-mwb.github.io/timerun/)** — Tutorials, concepts, and guides.
+- **[API Guide](https://hh-mwb.github.io/timerun/guide/)** — In-depth reference for `Timer`, `Measurement`, and `TimeSpan`.
+- **[Cookbooks](https://hh-mwb.github.io/timerun/cookbook/)** — Real-world recipes for FastAPI, OpenTelemetry, Structlog, and LLM streaming.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](https://github.com/HH-MWB/timerun/blob/main/CONTRIBUTING.md) for setup, testing, and pull request guidelines.
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/HH-MWB/timerun/blob/main/LICENSE) file for details.

timerun-0.7.0/README.md

@@ -0,0 +1,132 @@
+<p align="center">
+  <a href="https://github.com/HH-MWB/timerun">
+    <img src="https://github.com/user-attachments/assets/00f08873-3ee5-4ee4-a41f-f9eda37fc30d" alt="TimeRun">
+  </a>
+</p>
+
+<p align="center">
+  <strong>Structured, zero-dependency Python timing for humans and telemetry.</strong><br>
+  Instantly isolate wall-clock latency from CPU burn across sync, async, and generators.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/timerun/"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/timerun.svg"></a>
+  <a href="https://codecov.io/gh/HH-MWB/timerun"><img alt="Coverage" src="https://codecov.io/gh/HH-MWB/timerun/branch/main/graph/badge.svg"></a>
+  <a href="https://github.com/HH-MWB/timerun/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/timerun.svg"></a>
+  <a href="https://pepy.tech/project/timerun"><img alt="Total Downloads" src="https://static.pepy.tech/badge/timerun"></a>
+</p>
+
+---
+
+## Quickstart
+
+### 1. Measure Code Blocks (Wall vs. CPU)
+
+Wrap any block in `with Timer() as m:` (or `async with Timer() as m:`). On exit, `m.wall_time` and `m.cpu_time` are immediately available:
+
+```python
+import time
+from timerun import Timer
+
+with Timer() as m:
+    time.sleep(0.05)  # Simulates network I/O or database wait
+    total = sum(i * i for i in range(100_000))  # Simulates CPU computation
+
+print("Elapsed (Wall):", m.wall_time.timedelta)  # e.g., 0:00:00.055120
+print("Compute (CPU):  ", m.cpu_time.timedelta)  # e.g., 0:00:00.005110
+```
+
+> **Why both?** If wall time is 2 seconds but CPU time is 5 milliseconds, your code spent 99.7% of its time waiting on I/O. If both are 2 seconds, you have a CPU bottleneck.
+
+### 2. Time Functions and Generators
+
+Use `@Timer()` on sync or async functions. The wrapped function retains a bounded deque of measurements:
+
+```python
+from timerun import Timer
+
+
+@Timer(maxlen=100)
+def process_batch(items):
+    return [x * 2 for x in items]
+
+
+process_batch([1, 2, 3])
+
+last = process_batch.measurements[-1]
+print("Wall time:", last.wall_time.timedelta)
+print("CPU time: ", last.cpu_time.timedelta)
+```
+
+### 3. Stream to Logs & Observability
+
+Use `on_end` to ship timings directly to your logs, OpenTelemetry, Prometheus, or Datadog without adding vendor dependencies to your core logic:
+
+```python
+import logging
+from timerun import Timer
+
+logger = logging.getLogger("app")
+
+with Timer(
+    metadata={"service": "checkout", "user_id": "u-123"},
+    on_end=lambda m: logger.info(
+        "checkout_completed",
+        extra={
+            "wall_ms": m.wall_time.duration / 1e6,
+            "cpu_ms": m.cpu_time.duration / 1e6,
+            **m.metadata,
+        },
+    ),
+):
+    pass  # your operation
+```
+
+## Installation
+
+```bash
+pip install timerun
+```
+
+*Requires Python 3.10+.*
+
+## Why TimeRun?
+
+When code runs slowly, **is it waiting on network/disk I/O, or burning CPU?**
+
+- `time.perf_counter()` only gives a raw float of elapsed wall time. Measuring CPU time requires manual `time.thread_time()` calls and boilerplate.
+- Profilers (`cProfile`, `py-spy`) and APM agents (`Datadog`, `New Relic`) introduce binary dependencies, sampling overhead, or vendor lock-in.
+- Naive timing patterns risk race conditions and crosstalk in concurrent `asyncio` tasks or multi-threaded workers.
+
+TimeRun provides clean, structured timing with sub-microsecond overhead:
+
+| Feature | Manual `time.perf_counter()` | Profilers (`cProfile`, `py-spy`) | APM Agents (`Datadog`, `New Relic`) | **TimeRun** |
+| :--- | :---: | :---: | :---: | :---: |
+| **Dependencies** | None | Extra tooling | Large binary agents | **Zero (stdlib only)** |
+| **Wall vs. CPU Breakdown** | ❌ Manual boilerplate | ⚠️ Profiling overhead | ❌ Usually wall only | **✅ Built-in & precise** |
+| **Structured Output** | ❌ Raw floats | ❌ Binary trace files | ⚠️ Proprietary format | **✅ Structured `Measurement`** |
+| **Asyncio & Thread Safe** | ❌ Race condition risk | ⚠️ Global runtime cost | ✅ Handled by agent | **✅ Task & Thread isolated** |
+| **Telemetry Hooks** | ❌ Build it yourself | ❌ Offline analysis only | ⚠️ Vendor locked | **✅ Agnostic (`on_end`)** |
+| **Footprint** | 0 LOC | Heavy | Large background daemon | **Single file (~500 LOC)** |
+
+## Key Capabilities
+
+- **Zero Supply-Chain Risk:** Pure Python standard library only (`time`, `dataclasses`, `contextvars`); vendorable as a single file (`timerun.py`).
+- **Context Isolation:** Native `ContextVar` stacks ensure concurrent `asyncio` tasks and threads never mix up measurements.
+- **Sub-Microsecond Overhead:** Slotted dataclasses and integer nanoseconds keep internal overhead under ~0.4 µs.
+- **Full Async & Generator Support:** Accurately times coroutines, synchronous generators, and asynchronous streaming generators across full iteration.
+- **100% Test Coverage:** Verified with comprehensive Behavior-Driven Development (BDD) test suites.
+
+## Documentation
+
+- **[Documentation Site](https://hh-mwb.github.io/timerun/)** — Tutorials, concepts, and guides.
+- **[API Guide](https://hh-mwb.github.io/timerun/guide/)** — In-depth reference for `Timer`, `Measurement`, and `TimeSpan`.
+- **[Cookbooks](https://hh-mwb.github.io/timerun/cookbook/)** — Real-world recipes for FastAPI, OpenTelemetry, Structlog, and LLM streaming.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](https://github.com/HH-MWB/timerun/blob/main/CONTRIBUTING.md) for setup, testing, and pull request guidelines.
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/HH-MWB/timerun/blob/main/LICENSE) file for details.

timerun-0.7.0/pyproject.toml

@@ -0,0 +1,258 @@
+# ============================================================================
+# Build System & Package Metadata (PEP 517 / PEP 621 / PEP 735)
+# ============================================================================
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "timerun"
+description = "Structured wall-clock & CPU timing for Python (stdlib only). Zero dependencies, nanosecond precision, and ready for your logs, metrics, and OpenTelemetry."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "HH-MWB", email = "h.hong@mail.com" }]
+keywords = [
+    "time",
+    "timing",
+    "measurement",
+    "measurements",
+    "elapsed",
+    "stopwatch",
+    "timer",
+    "performance",
+    "latency",
+    "profiler",
+    "benchmarking",
+    "telemetry",
+    "opentelemetry",
+    "wall-clock",
+    "cpu-time",
+    "asyncio",
+    "fastapi",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://hh-mwb.github.io/timerun/"
+Documentation = "https://hh-mwb.github.io/timerun/"
+Repository = "https://github.com/HH-MWB/timerun"
+Issues = "https://github.com/HH-MWB/timerun/issues"
+Changelog = "https://github.com/HH-MWB/timerun/releases"
+PyPI = "https://pypi.org/project/timerun"
+
+[dependency-groups]
+dev = [
+    { include-group = "test" },
+    { include-group = "audit" },
+    "pre-commit",
+]
+test = [
+    "behave",
+    "coverage",
+]
+audit = [
+    "pip-audit",
+]
+docs = [
+    "zensical",
+]
+build = [
+    "build",
+    "twine",
+]
+
+# ============================================================================
+# Build Backend
+# ============================================================================
+
+[tool.setuptools]
+py-modules = ["timerun"]
+license-files = ["LICENSE"]
+
+[tool.setuptools.dynamic]
+version = { attr = "timerun.__version__" }
+
+# ============================================================================
+# Linting & Formatting
+# ============================================================================
+
+[tool.ruff]
+target-version = "py310"
+line-length = 79
+fix = true
+force-exclude = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "CPY001",  # Missing copyright notice at top of file
+    "D203",    # Incompatible with D211 (no-blank-line-before-class)
+    "D213",    # Incompatible with D212 (multi-line-summary-first-line)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"features/steps/*.py" = ["S101"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+known-first-party = ["timerun"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 5
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.flake8-type-checking]
+strict = true
+
+[tool.pylint.main]
+py-version = "3.10"
+fail-under = 10.0
+load-plugins = ["pylint.extensions.mccabe"]
+
+[tool.pylint.messages_control]
+disable = [
+    "not-callable",  # false positive for behave's when/then decorators
+]
+
+[tool.pylint.format]
+max-line-length = 79
+
+[tool.pylint.imports]
+known-first-party = ["timerun"]
+
+[tool.pylint.design]
+max-args = 4
+max-attributes = 5
+max-complexity = 5
+max-returns = 3
+max-branches = 4
+max-statements = 20
+
+# ============================================================================
+# Type Checking
+# ============================================================================
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+extra_checks = true
+local_partial_types = true
+
+# Stricter checks beyond default strict mode
+disallow_any_decorated = true
+disallow_any_explicit = true
+disallow_any_unimported = true
+strict_equality_for_none = true
+warn_unreachable = true
+
+# Extended error codes
+enable_error_code = [
+    "deprecated",
+    "exhaustive-match",
+    "explicit-override",
+    "ignore-without-code",
+    "possibly-undefined",
+    "redundant-expr",
+    "redundant-self",
+    "truthy-bool",
+    "truthy-function",
+    "truthy-iterable",
+    "unimported-reveal",
+    "unused-awaitable",
+]
+
+# Output formatting
+show_column_numbers = true
+show_error_codes = true
+show_error_context = true
+pretty = true
+
+[[tool.mypy.overrides]]
+module = [
+    "behave",
+    "behave.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "features.*"
+ignore_errors = true
+
+[tool.pyright]
+pythonVersion = "3.10"
+venvPath = "."
+venv = ".venv"
+
+include = ["timerun.py"]
+exclude = ["features"]
+
+typeCheckingMode = "strict"
+deprecateTypingAliases = true
+
+# Diagnostic rules elevated to error beyond strict mode
+reportCallInDefaultInitializer = "error"
+reportImplicitOverride = "error"
+reportImplicitStringConcatenation = "error"
+reportImportCycles = "error"
+reportMissingSuperCall = "error"
+reportPropertyTypeMismatch = "error"
+reportUninitializedInstanceVariable = "error"
+reportUnnecessaryCast = "error"
+reportUnnecessaryComparison = "error"
+reportUnnecessaryContains = "error"
+reportUnnecessaryIsInstance = "error"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportUnusedCallResult = "error"
+
+# ============================================================================
+# Security Analysis
+# ============================================================================
+
+[tool.bandit]
+exclude_dirs = ["features/steps"]
+
+[tool.bandit.try_except_pass]
+check_typed_exception = true
+
+# ============================================================================
+# Spelling & Quality
+# ============================================================================
+
+[tool.codespell]
+check-filenames = true
+check-hidden = true
+
+# ============================================================================
+# Testing & Coverage
+# ============================================================================
+
+[tool.behave]
+show_snippets = false
+show_skipped = false
+
+[tool.coverage.run]
+source = ["timerun"]
+relative_files = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true