timetracer 1.1.0__py3-none-any.whl

timetracer/utils/time.py

@@ -0,0 +1,106 @@
+"""
+Time utilities for duration tracking.
+
+Provides a Timer context manager for accurate timing.
+"""
+
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class TimingResult:
+    """Result of a timing operation."""
+    start_ns: int
+    end_ns: int
+
+    @property
+    def duration_ns(self) -> int:
+        """Duration in nanoseconds."""
+        return self.end_ns - self.start_ns
+
+    @property
+    def duration_ms(self) -> float:
+        """Duration in milliseconds."""
+        return self.duration_ns / 1_000_000
+
+    @property
+    def duration_s(self) -> float:
+        """Duration in seconds."""
+        return self.duration_ns / 1_000_000_000
+
+
+class Timer:
+    """
+    A timer for measuring operation duration.
+
+    Can be used as a context manager or manually.
+
+    Usage:
+        # Context manager
+        with Timer() as t:
+            do_something()
+        print(f"Took {t.duration_ms}ms")
+
+        # Manual
+        timer = Timer()
+        timer.start()
+        do_something()
+        timer.stop()
+        print(f"Took {timer.duration_ms}ms")
+    """
+
+    def __init__(self) -> None:
+        self._start_ns: int | None = None
+        self._end_ns: int | None = None
+
+    def start(self) -> None:
+        """Start the timer."""
+        self._start_ns = time.perf_counter_ns()
+        self._end_ns = None
+
+    def stop(self) -> TimingResult:
+        """Stop the timer and return result."""
+        if self._start_ns is None:
+            raise RuntimeError("Timer was not started")
+
+        self._end_ns = time.perf_counter_ns()
+        return TimingResult(self._start_ns, self._end_ns)
+
+    @property
+    def duration_ns(self) -> int:
+        """Duration in nanoseconds (uses current time if not stopped)."""
+        if self._start_ns is None:
+            return 0
+        end = self._end_ns if self._end_ns is not None else time.perf_counter_ns()
+        return end - self._start_ns
+
+    @property
+    def duration_ms(self) -> float:
+        """Duration in milliseconds."""
+        return self.duration_ns / 1_000_000
+
+    @property
+    def elapsed_ms(self) -> float:
+        """Alias for duration_ms (more intuitive during ongoing timing)."""
+        return self.duration_ms
+
+    def __enter__(self) -> "Timer":
+        self.start()
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.stop()
+
+
+def get_offset_ms(start_time: float) -> float:
+    """
+    Get milliseconds elapsed since a start time.
+
+    Args:
+        start_time: Start time from time.perf_counter().
+
+    Returns:
+        Milliseconds elapsed.
+    """
+    return (time.perf_counter() - start_time) * 1000

timetracer-1.1.0.dist-info/METADATA

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: timetracer
+Version: 1.1.0
+Summary: Time-travel debugging for FastAPI and Flask - record API cassettes, replay with mocked dependencies
+Author: Timetracer Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/usv240/timetracer
+Project-URL: Documentation, https://github.com/usv240/timetracer#readme
+Project-URL: Repository, https://github.com/usv240/timetracer
+Keywords: fastapi,flask,debugging,testing,api,replay,mocking,cassette
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
+Requires-Dist: starlette>=0.27.0; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=2.0.0; extra == "flask"
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.24.0; extra == "httpx"
+Provides-Extra: requests
+Requires-Dist: requests>=2.28.0; extra == "requests"
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0.0; extra == "sqlalchemy"
+Provides-Extra: redis
+Requires-Dist: redis>=4.0.0; extra == "redis"
+Provides-Extra: s3
+Requires-Dist: boto3>=1.26.0; extra == "s3"
+Provides-Extra: all
+Requires-Dist: timetracer[fastapi,flask,httpx,redis,requests,s3,sqlalchemy]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: timetracer[all]; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: uvicorn>=0.20.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: fakeredis>=2.0.0; extra == "dev"
+Dynamic: license-file
+
+# Timetracer
+
+**Time-travel debugging for FastAPI and Flask** — Record API requests, replay with mocked dependencies.
+
+[![CI](https://github.com/usv240/timetracer/actions/workflows/ci.yml/badge.svg)](https://github.com/usv240/timetracer/actions)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI](https://img.shields.io/pypi/v/timetracer.svg)](https://pypi.org/project/timetracer/)
+
+---
+
+## What is Timetracer?
+
+Timetracer captures real API requests into portable **cassettes** and replays them with mocked dependencies (HTTP calls, database queries, Redis commands).
+
+> Record once. Replay anywhere. Debug faster.
+
+**Common use cases:**
+
+- Reproduce production bugs locally without access to external services
+- Build regression tests from real traffic patterns
+- Run demos offline with pre-recorded data
+- Detect performance regressions between releases
+- Compare behavior between different code versions
+
+---
+
+## How It Works
+
+Timetracer acts as middleware that intercepts your app's external calls:
+
+```
+                      RECORD MODE
+┌──────────┐      ┌──────────────┐      ┌──────────────┐
+│  Client  │ ───► │   Your App   │ ───► │   External   │
+│  (curl)  │      │ + Timetracer │      │   APIs/DB    │
+└──────────┘      └──────────────┘      └──────────────┘
+                         │
+                         ▼
+                   ┌───────────┐
+                   │  Cassette │  (saves everything)
+                   │   .json   │
+                   └───────────┘
+
+
+                      REPLAY MODE
+┌──────────┐      ┌──────────────┐       ╳ External APIs
+│  Client  │ ───► │   Your App   │       ╳ (not called)
+│  (curl)  │      │ + Timetracer │
+└──────────┘      └──────────────┘
+                         ▲
+                         │
+                   ┌───────────┐
+                   │  Cassette │  (replays from here)
+                   │   .json   │
+                   └───────────┘
+```
+
+---
+
+## Installation
+
+```bash
+pip install timetracer[all]
+```
+
+Or install only what you need:
+
+```bash
+pip install timetracer[fastapi,httpx]    # FastAPI + HTTP
+pip install timetracer[flask,requests]   # Flask + HTTP
+```
+
+---
+
+## Quick Start
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from timetracer.integrations.fastapi import auto_setup
+
+app = auto_setup(FastAPI())
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: int):
+    async with httpx.AsyncClient() as client:
+        return (await client.get(f"https://api.example.com/users/{user_id}")).json()
+```
+
+### Flask
+
+```python
+from flask import Flask
+from timetracer.integrations.flask import auto_setup
+
+app = auto_setup(Flask(__name__))
+```
+
+### Record and Replay
+
+```bash
+# Record mode - captures all external calls
+TIMETRACER_MODE=record uvicorn app:app
+curl http://localhost:8000/users/123
+
+# Replay mode - mocks external calls from cassette
+TIMETRACER_MODE=replay \
+  TIMETRACER_CASSETTE=./cassettes/2026-01-16/GET__users_{user_id}__abc.json \
+  uvicorn app:app
+```
+
+---
+
+## Manual Setup
+
+For more control over configuration:
+
+```python
+import httpx
+from fastapi import FastAPI
+from timetracer import TraceConfig
+from timetracer.integrations.fastapi import TimeTraceMiddleware
+from timetracer.plugins import enable_httpx
+
+app = FastAPI()
+
+config = TraceConfig(
+    mode="record",
+    cassette_dir="./my-cassettes",
+    errors_only=True,
+)
+app.add_middleware(TimeTraceMiddleware, config=config)
+
+enable_httpx()
+```
+
+---
+
+## Configuration
+
+All settings are controlled via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TIMETRACER_MODE` | `off`, `record`, `replay` | `off` |
+| `TIMETRACER_DIR` | Cassette storage directory | `./cassettes` |
+| `TIMETRACER_CASSETTE` | Path to cassette file (replay mode) | — |
+| `TIMETRACER_SAMPLE_RATE` | Fraction of requests to record (0-1) | `1.0` |
+| `TIMETRACER_ERRORS_ONLY` | Only record error responses | `false` |
+| `TIMETRACER_MOCK_PLUGINS` | Plugins to mock during replay | all |
+| `TIMETRACER_LIVE_PLUGINS` | Plugins to keep live during replay | none |
+
+---
+
+## Features
+
+| Category | Supported |
+|----------|-----------|
+| **Frameworks** | FastAPI, Flask |
+| **HTTP Clients** | httpx, requests |
+| **Databases** | SQLAlchemy |
+| **Cache** | Redis |
+| **Storage** | Local filesystem, AWS S3 |
+| **Tools** | CLI, diff engine, HTML timeline, **Dashboard** |
+
+---
+
+## CLI
+
+```bash
+timetracer list --dir ./cassettes              # List all cassettes
+timetracer show ./cassettes/GET__users.json    # Show cassette details
+timetracer diff --a old.json --b new.json      # Compare two cassettes
+timetracer timeline ./cassettes/GET__users.json --open  # Generate timeline
+timetracer dashboard --dir ./cassettes --open  # Generate interactive dashboard
+timetracer serve --dir ./cassettes --open      # Start live dashboard with replay
+```
+
+---
+
+## Dashboard
+
+Browse and debug all recorded cassettes with the interactive dashboard:
+
+```bash
+# Static HTML dashboard (open in browser)
+timetracer dashboard --dir ./cassettes --open
+
+# Live dashboard with real-time replay
+timetracer serve --dir ./cassettes --open
+```
+
+**Features:**
+- 📊 **Sortable table** - Sort by time, method, status, duration
+- 🔍 **Filters** - Filter by method, status, duration, time range
+- ⚠️ **Error highlighting** - Errors shown in red with warning icons
+- 📋 **Stack traces** - View exception details and Python tracebacks
+- ▶️ **Replay** - One-click replay to see recorded request/response
+- 📁 **Raw JSON** - Expandable view of full cassette data
+
+---
+
+## Security
+
+Timetracer automatically protects sensitive data:
+
+- Removes `Authorization`, `Cookie`, and `Set-Cookie` headers
+- Masks sensitive fields like `password`, `token`, `api_key` in request/response bodies
+- Enforces a 64KB body size limit to prevent large data captures
+
+---
+
+## Documentation
+
+- [Why Timetracer?](docs/why-timetracer.md)
+- [Quick Start Guide](docs/quickstart.md)
+- [Configuration Reference](docs/configuration.md)
+- [Dashboard Guide](docs/dashboard.md)
+- [Plugin Guide](docs/plugins.md)
+- [SQLAlchemy Integration](docs/sqlalchemy.md)
+- [Flask Integration](docs/flask.md)
+- [S3 Storage](docs/s3-storage.md)
+- [Cassette Search](docs/search.md)
+- [Security Best Practices](docs/security.md)
+
+---
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

timetracer-1.1.0.dist-info/RECORD

@@ -0,0 +1,51 @@
+timetracer/__init__.py,sha256=klGmsW7pY1kh5tVPxtLusff1_fEAG2v3eoPvUpaa6fo,676
+timetracer/config.py,sha256=iX07nLAFp9NYgGGq1ZHp745VaL4urj0EVe24j95KBzE,11175
+timetracer/constants.py,sha256=_I2tGijXG-JNkK-Ba_fSODu6JJ2SCJorNoslUgsbrdg,4703
+timetracer/context.py,sha256=MN9EpUtyX9ZvaLhW71FSQdvOfTovhm_n_52q0ovu7RI,2368
+timetracer/exceptions.py,sha256=bTo_A_-0DHOmCmX8XilFciNoQ0s3YtC7GajPfN6Hr04,3163
+timetracer/session.py,sha256=e-TMLRGZGSZpO_k5ZxJPafUwMBsuMkyv-myiMwEZPTc,12072
+timetracer/types.py,sha256=e3eGcgYSboXw7TIm6ftDoZiRzcjiFLfmvS81Kaj0RqA,5719
+timetracer/cassette/__init__.py,sha256=JZ4XEK51WdD2iFV0yLpyDHgN0Xgb6--1qiXDslWJv58,274
+timetracer/cassette/io.py,sha256=bhRGITVK2-v50oB0OGgdnVL8RX-xPqd1o7B_29-YlSI,12933
+timetracer/cassette/naming.py,sha256=_wdaZR751s-stxDiQ1SkbrbMZ37Cj2MeOceOyFU_BBE,1680
+timetracer/catalog/__init__.py,sha256=_IvevBJVUR15YaxyZQ3fTQRANOPAYPrURsGrzduXK38,8168
+timetracer/cli/__init__.py,sha256=iIdNJFDOU-U77V2DN5x42g4VPoE0Swyp2H6MLd5UDyA,91
+timetracer/cli/main.py,sha256=IpsKRuaQFLyLDQTwuPCRxmHHh3yRUG3bP5S1dMstW1M,20314
+timetracer/cli/commands/__init__.py,sha256=FIIaAXFQd7YyXrzm9CVGePr0uLipPWIRC9rWu9JZMEc,31
+timetracer/dashboard/__init__.py,sha256=sNQT3m-EMNLxiWr9jBOnyEKTlpFD0aLveOT2L-f4yeo,335
+timetracer/dashboard/generator.py,sha256=280XMneIB91AYDLKiiGDYHIr7h-QyjkOwQjhRxEOcfU,6961
+timetracer/dashboard/server.py,sha256=14LlR8uLV9XY7L_OlMgWmN2L903YvSDzslG62RmV12Q,9340
+timetracer/dashboard/template.py,sha256=bNs0THiZezc6o2H8vO685PchrPBcFHhUewkeib1XcyE,31682
+timetracer/diff/__init__.py,sha256=YvcuQcL8JhYUAFiZ_EFY6y8w3AW1hVySfsElGTLWoNQ,226
+timetracer/diff/engine.py,sha256=9RZK-9-NyxnO-pqmG74G_VXvJJP3zfaHSToZ-jF4D0Q,8898
+timetracer/diff/report.py,sha256=eVDhlOe7LdmPtXTdrGmFevAZlDIY026-jkJSLdTnJdw,3109
+timetracer/integrations/__init__.py,sha256=U2gtm5ayknLJUY1llJMb11RbzRn56M29wPki9aiIFKs,745
+timetracer/integrations/fastapi.py,sha256=-u3X1xMJv1LZRrNu8OBRVnk5hV0U3zdcf2tQ8Sx7z9c,17095
+timetracer/integrations/flask.py,sha256=z9yAOx25bJkFYfBQT1OBlAd5FAqtQwR_ScGrexJHuh0,15938
+timetracer/plugins/__init__.py,sha256=J7wzZT_eYfOEjKXdL33Bfo5MIPNOHUTBURkDQ1W1400,1253
+timetracer/plugins/base.py,sha256=ZBZ9KohVIVKz9zwIv-sS2_xIS-0x25Diabw_Rxm_a48,1688
+timetracer/plugins/httpx_plugin.py,sha256=nCK0ZYiKLYaH7nEd7Ul7Sl7CJa9PfWMPeaQRrEeNNAU,11975
+timetracer/plugins/redis_plugin.py,sha256=Lzt6tqNi6foRsWyKGkOr7KsuCeEFOFMmlpiUZNX4Os8,8174
+timetracer/plugins/requests_plugin.py,sha256=_wyfxhYTq4HWL-7ZfW8puMbqqPh4RrxVmNgazWo1WaE,9526
+timetracer/plugins/sqlalchemy_plugin.py,sha256=-FEIZlrIRfYP0I7AfzJ5lP0TYUOJacFfegV4gPO5E_Q,7771
+timetracer/policies/__init__.py,sha256=sGd2tEuLeW-h2CQ814ek8FfTb4MVkDtHVnSuRajiFtI,378
+timetracer/policies/capture.py,sha256=D9QM16H_KfkYxglXUaXZ2P9-kHABpsTjrKa7dAu8nsc,1371
+timetracer/policies/redaction.py,sha256=zOxYWBfj0eCUtWVljX6u4dmLwSv2HU3SivICDEMA0gc,4388
+timetracer/replay/__init__.py,sha256=p-J2aHtdy_1PkYdtHNMR7Rm9CeWINtXoWHcHYMSkjP8,202
+timetracer/replay/engine.py,sha256=mtNC4wM4utv4CK-r6X7Vyoa8LJUCDaBg2edEiGzV0tk,2270
+timetracer/replay/errors.py,sha256=0nyTMxXeCNGdRZIbpkdRNpE8qocKn_3jY6Uo4iVhA4Y,189
+timetracer/replay/matching.py,sha256=GP4Lm0zl4l0u9_hwA8RGlVy2qJqKA09fUeSxO-3hKOE,2339
+timetracer/storage/__init__.py,sha256=IKUJaTjS_Cga_lDDpG06aAo33DAdHsiUCDv6d2lojfg,385
+timetracer/storage/s3.py,sha256=rAIAYuK9cst__N-IoyYvBDs81B_GgWxt9XgE5HXsj6Q,9946
+timetracer/timeline/__init__.py,sha256=WIXUSAfbBM4C5a0OUe295RQVt84VEf_yHFRg0-dpF-M,226
+timetracer/timeline/generator.py,sha256=stiG-8CCSy4kobO3KkNu_TuEfVtgELmdFR5RBNie2vk,4093
+timetracer/timeline/template.py,sha256=isHjUrDqk9gIx57s9ovD8lS2clnPm-wN7JdWGnvZxJE,10700
+timetracer/utils/__init__.py,sha256=Gx5r4W_9DcUa6PMUThEf1f-oniNe3-aO0Hhkqn1m8AU,188
+timetracer/utils/hashing.py,sha256=4yKZHfCguWcUYlA8PAx-sjGqZVSwIYElPVFbHO5TvJk,1638
+timetracer/utils/time.py,sha256=XHVBmfgOgd1LmFCU2FCwFwRht4Su9nYLxq_8FRg__lQ,2609
+timetracer-1.1.0.dist-info/licenses/LICENSE,sha256=ffV3XGF197Z-GTthIYyu18RzqviI7Fo2ZtpSbzBBD8Y,1079
+timetracer-1.1.0.dist-info/METADATA,sha256=iNRbtMcYy1AFQi21YQ7xoyaIANUIoCEkbKM1cUF4HH0,9122
+timetracer-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+timetracer-1.1.0.dist-info/entry_points.txt,sha256=wLj5_f4WLns9mY0cGUvtg6_ZW2SJM_LzG0k1Ta2aIh8,56
+timetracer-1.1.0.dist-info/top_level.txt,sha256=WCH_j7MW48lvuI3rWt6mcLlbtn7MT9lYZq_lEyiw0Vw,11
+timetracer-1.1.0.dist-info/RECORD,,

timetracer-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

timetracer-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+timetracer = timetracer.cli.main:main

timetracer-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timetrace Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

timetracer-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+timetracer