nullscope 0.1.0__tar.gz

nullscope-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: Validate on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync --all-extras --dev --python ${{ matrix.python-version }}
+
+      - name: Run lint
+        run: uv run --python ${{ matrix.python-version }} ruff check .
+
+      - name: Run type checks
+        run: uv run --python ${{ matrix.python-version }} mypy src tests
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest -q
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: validate
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nullscope
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python for build
+        run: uv python install 3.12
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          generate_release_notes: true
+
+      - name: Publish to PyPI
+        run: uv publish

nullscope-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Checks on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync --all-extras --dev --python ${{ matrix.python-version }}
+
+      - name: Run lint
+        run: uv run --python ${{ matrix.python-version }} ruff check .
+
+      - name: Run type checks
+        run: uv run --python ${{ matrix.python-version }} mypy src tests
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest -q

nullscope-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__
+.venv
+.ruff_cache
+.pytest_cache
+.mypy_cache
+.DS_Store
+uv.lock

nullscope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Brar
+
+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.

nullscope-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: nullscope
+Version: 0.1.0
+Summary: Zero-cost telemetry for Python. No-op when disabled, rich context when enabled.
+Project-URL: Homepage, https://github.com/seanbrar/nullscope
+Project-URL: Repository, https://github.com/seanbrar/nullscope
+Project-URL: Documentation, https://github.com/seanbrar/nullscope/tree/main/docs
+Project-URL: Issues, https://github.com/seanbrar/nullscope/issues
+Author-email: Sean Brar <hello@seanbrar.com>
+License: MIT
+License-File: LICENSE
+Keywords: metrics,nullscope,observability,telemetry,tracing,zero-cost
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.10
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# Nullscope
+
+[![PyPI](https://img.shields.io/pypi/v/nullscope)](https://pypi.org/project/nullscope/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Zero-cost telemetry for Python. No-op when disabled, rich context when enabled.
+
+## Why Nullscope?
+
+Most telemetry libraries have runtime cost even when you don't need them. Nullscope is different:
+
+- **Disabled**: Returns a singleton no-op object. No allocations, no timing calls, no overhead.
+- **Enabled**: Full-featured timing and metrics with automatic scope hierarchy.
+
+This makes Nullscope ideal for **libraries** (users can enable telemetry if they want) and **applications** where you want zero production overhead but rich debugging capability.
+
+```python
+from nullscope import TelemetryContext
+
+# When NULLSCOPE_ENABLED != "1", this is literally just returning a cached object
+telemetry = TelemetryContext()
+
+with telemetry("database.query"):  # No-op when disabled
+    results = db.execute(query)
+```
+
+## What Nullscope Is Not
+
+- **A distributed tracing system.** No trace propagation, no span IDs, no context injection for cross-service correlation. If you need that, use OpenTelemetry directly. Nullscope can *feed* OTel, but it doesn't replace it.
+
+- **A metrics aggregation layer.** Nullscope reports raw events to reporters. It doesn't compute percentiles, histograms, or roll up data. That's the reporter's job (or the backend's).
+
+- **Auto-instrumentation.** Nullscope won't patch your HTTP client or database driver. You instrument what you want, explicitly.
+
+- **A logging framework.** Scopes are for timing and metrics, not structured log events. (Though a reporter *could* emit logs.)
+
+## Installation
+
+```bash
+pip install nullscope
+```
+
+With OpenTelemetry support:
+
+```bash
+pip install nullscope[otel]
+```
+
+## Quick Start
+
+```python
+import os
+os.environ["NULLSCOPE_ENABLED"] = "1"  # Enable telemetry
+
+from nullscope import TelemetryContext, SimpleReporter
+
+# Create a reporter to see output
+reporter = SimpleReporter()
+telemetry = TelemetryContext(reporter)
+
+# Time operations with automatic hierarchy
+with telemetry("request"):
+    with telemetry("auth"):
+        validate_token()
+
+    with telemetry("handler"):
+        process_data()
+
+# See what was collected
+reporter.print_report()
+```
+
+Output:
+
+```text
+=== Nullscope Report ===
+
+--- Timings ---
+request:
+  auth                           | Calls: 1    | Avg: 0.0012s | Total: 0.0012s
+  handler                        | Calls: 1    | Avg: 0.0234s | Total: 0.0234s
+```
+
+## Configuration
+
+| Environment Variable  | Description                          |
+| --------------------- | ------------------------------------ |
+| `NULLSCOPE_ENABLED=1` | Enable telemetry (default: disabled) |
+
+Note: environment flags are read at import time. In tests, reload `nullscope` after changing env vars.
+
+## API
+
+### TelemetryContext
+
+```python
+from nullscope import TelemetryContext
+
+telemetry = TelemetryContext()  # Uses default SimpleReporter when enabled
+telemetry = TelemetryContext(my_reporter)  # Custom reporter
+telemetry = TelemetryContext(reporter1, reporter2)  # Multiple reporters
+```
+
+### Scopes (Timing)
+
+```python
+with telemetry("operation"):
+    do_work()
+
+# With metadata
+with telemetry("http.request", method="GET", path="/api/users"):
+    handle_request()
+```
+
+### Metrics
+
+```python
+telemetry.count("cache.hit")  # Increment counter
+telemetry.count("items.processed", 5)  # Increment by N
+telemetry.gauge("queue.depth", len(queue))  # Point-in-time value
+telemetry.metric("custom", value, metric_type="counter")  # Generic
+```
+
+### Check Status
+
+```python
+if telemetry.is_enabled:
+    # Do expensive debug logging
+    pass
+```
+
+## OpenTelemetry Adapter
+
+Export to OpenTelemetry backends:
+
+```python
+from nullscope import TelemetryContext
+from nullscope.adapters.opentelemetry import OTelReporter
+
+# Configure OTel SDK first (providers, exporters, etc.)
+# Then use Nullscope with OTel reporter
+telemetry = TelemetryContext(OTelReporter(service_name="my-service"))
+```
+
+The adapter emits:
+
+- **Timings** → Histogram (seconds) + synthetic Span when wall-clock bounds are present
+- **Counters** → Counter
+- **Gauges** → Histogram (sampled values, since Python OTel sync gauge support is limited)
+
+## Documentation
+
+- [Design](docs/design.md) - Architecture and implementation details
+- [Examples](docs/examples.md) - Real-world usage patterns
+- [Comparison](docs/comparison.md) - When to use Nullscope vs alternatives
+- [Roadmap](ROADMAP.md) - Version milestones and planned features
+
+## License
+
+[MIT](LICENSE)

nullscope-0.1.0/README.md

@@ -0,0 +1,160 @@
+# Nullscope
+
+[![PyPI](https://img.shields.io/pypi/v/nullscope)](https://pypi.org/project/nullscope/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Zero-cost telemetry for Python. No-op when disabled, rich context when enabled.
+
+## Why Nullscope?
+
+Most telemetry libraries have runtime cost even when you don't need them. Nullscope is different:
+
+- **Disabled**: Returns a singleton no-op object. No allocations, no timing calls, no overhead.
+- **Enabled**: Full-featured timing and metrics with automatic scope hierarchy.
+
+This makes Nullscope ideal for **libraries** (users can enable telemetry if they want) and **applications** where you want zero production overhead but rich debugging capability.
+
+```python
+from nullscope import TelemetryContext
+
+# When NULLSCOPE_ENABLED != "1", this is literally just returning a cached object
+telemetry = TelemetryContext()
+
+with telemetry("database.query"):  # No-op when disabled
+    results = db.execute(query)
+```
+
+## What Nullscope Is Not
+
+- **A distributed tracing system.** No trace propagation, no span IDs, no context injection for cross-service correlation. If you need that, use OpenTelemetry directly. Nullscope can *feed* OTel, but it doesn't replace it.
+
+- **A metrics aggregation layer.** Nullscope reports raw events to reporters. It doesn't compute percentiles, histograms, or roll up data. That's the reporter's job (or the backend's).
+
+- **Auto-instrumentation.** Nullscope won't patch your HTTP client or database driver. You instrument what you want, explicitly.
+
+- **A logging framework.** Scopes are for timing and metrics, not structured log events. (Though a reporter *could* emit logs.)
+
+## Installation
+
+```bash
+pip install nullscope
+```
+
+With OpenTelemetry support:
+
+```bash
+pip install nullscope[otel]
+```
+
+## Quick Start
+
+```python
+import os
+os.environ["NULLSCOPE_ENABLED"] = "1"  # Enable telemetry
+
+from nullscope import TelemetryContext, SimpleReporter
+
+# Create a reporter to see output
+reporter = SimpleReporter()
+telemetry = TelemetryContext(reporter)
+
+# Time operations with automatic hierarchy
+with telemetry("request"):
+    with telemetry("auth"):
+        validate_token()
+
+    with telemetry("handler"):
+        process_data()
+
+# See what was collected
+reporter.print_report()
+```
+
+Output:
+
+```text
+=== Nullscope Report ===
+
+--- Timings ---
+request:
+  auth                           | Calls: 1    | Avg: 0.0012s | Total: 0.0012s
+  handler                        | Calls: 1    | Avg: 0.0234s | Total: 0.0234s
+```
+
+## Configuration
+
+| Environment Variable  | Description                          |
+| --------------------- | ------------------------------------ |
+| `NULLSCOPE_ENABLED=1` | Enable telemetry (default: disabled) |
+
+Note: environment flags are read at import time. In tests, reload `nullscope` after changing env vars.
+
+## API
+
+### TelemetryContext
+
+```python
+from nullscope import TelemetryContext
+
+telemetry = TelemetryContext()  # Uses default SimpleReporter when enabled
+telemetry = TelemetryContext(my_reporter)  # Custom reporter
+telemetry = TelemetryContext(reporter1, reporter2)  # Multiple reporters
+```
+
+### Scopes (Timing)
+
+```python
+with telemetry("operation"):
+    do_work()
+
+# With metadata
+with telemetry("http.request", method="GET", path="/api/users"):
+    handle_request()
+```
+
+### Metrics
+
+```python
+telemetry.count("cache.hit")  # Increment counter
+telemetry.count("items.processed", 5)  # Increment by N
+telemetry.gauge("queue.depth", len(queue))  # Point-in-time value
+telemetry.metric("custom", value, metric_type="counter")  # Generic
+```
+
+### Check Status
+
+```python
+if telemetry.is_enabled:
+    # Do expensive debug logging
+    pass
+```
+
+## OpenTelemetry Adapter
+
+Export to OpenTelemetry backends:
+
+```python
+from nullscope import TelemetryContext
+from nullscope.adapters.opentelemetry import OTelReporter
+
+# Configure OTel SDK first (providers, exporters, etc.)
+# Then use Nullscope with OTel reporter
+telemetry = TelemetryContext(OTelReporter(service_name="my-service"))
+```
+
+The adapter emits:
+
+- **Timings** → Histogram (seconds) + synthetic Span when wall-clock bounds are present
+- **Counters** → Counter
+- **Gauges** → Histogram (sampled values, since Python OTel sync gauge support is limited)
+
+## Documentation
+
+- [Design](docs/design.md) - Architecture and implementation details
+- [Examples](docs/examples.md) - Real-world usage patterns
+- [Comparison](docs/comparison.md) - When to use Nullscope vs alternatives
+- [Roadmap](ROADMAP.md) - Version milestones and planned features
+
+## License
+
+[MIT](LICENSE)

nullscope-0.1.0/ROADMAP.md

@@ -0,0 +1,37 @@
+# Nullscope Roadmap
+
+## Version 0.1.0 (Current)
+
+- [x] Zero-cost no-op pattern
+- [x] Enabled context with scope hierarchy
+- [x] Context vars for async safety
+- [x] Pluggable reporter protocol
+- [x] SimpleReporter for development
+- [x] OpenTelemetry adapter
+- [x] `py.typed` marker for PEP 561
+- [x] Basic test coverage
+
+## Version 0.2.0 - Ergonomics
+
+- [ ] Decorator support (`@nullscope.timed("operation")`)
+- [ ] Reporter lifecycle methods (`flush()`, `shutdown()`)
+- [ ] Async documentation and explicit testing
+- [ ] Improved error messages
+
+## Version 0.3.0 - Observability
+
+- [ ] Exception tracking in scopes (record exception info)
+- [ ] Logging-based reporter adapter
+- [ ] Scope tags/labels support
+
+## Version 0.4.0 - Polish
+
+- [ ] Real-world usage feedback incorporated
+- [ ] API refinements based on feedback
+- [ ] Performance benchmarks
+
+## Version 1.0.0 - Stable
+
+- [ ] API freeze
+- [ ] Comprehensive documentation
+- [ ] Stability commitment

nullscope-0.1.0/docs/comparison.md

@@ -0,0 +1,119 @@
+# Nullscope vs Alternatives
+
+When to use Nullscope versus other observability tools.
+
+## vs OpenTelemetry SDK
+
+**OpenTelemetry** is the industry standard for observability. It provides comprehensive tracing, metrics, and logging with a rich ecosystem of exporters and integrations.
+
+| Aspect | Nullscope | OpenTelemetry SDK |
+|--------|-----------|-------------------|
+| Zero-cost when disabled | Yes (singleton no-op) | No (still creates spans/contexts) |
+| Setup complexity | Minimal | Moderate to high |
+| Ecosystem | Limited | Extensive |
+| Protocol compliance | None | OTLP standard |
+| Best for | Application code, libraries | Production observability |
+
+**Use Nullscope when:**
+- You're writing a library and want optional telemetry
+- You need truly zero overhead in production
+- You want simple, focused timing/metrics without full tracing
+- You'll export to OTel anyway (via the adapter)
+
+**Use OpenTelemetry directly when:**
+- You need distributed tracing across services
+- You want baggage propagation, trace context, etc.
+- You're building production infrastructure
+- You need W3C Trace Context compliance
+
+**Best of both worlds:** Use Nullscope in your application code with `OTelReporter` to get zero-cost no-op behavior with OTel export when enabled.
+
+## vs structlog
+
+**structlog** is a structured logging library that makes logs more useful with context and formatting.
+
+| Aspect | Nullscope | structlog |
+|--------|-----------|-----------|
+| Primary purpose | Timing and metrics | Structured logging |
+| Output format | Reporter-defined | Log events |
+| Context tracking | Scope hierarchy | Bound loggers |
+| Zero-cost disable | Yes | No (logs are written) |
+
+**Use Nullscope when:**
+- You need timing data, not log events
+- You want to record numeric metrics
+- Zero overhead when disabled is critical
+
+**Use structlog when:**
+- You need rich, structured log output
+- You want contextual logging throughout your app
+- You're building audit trails or debug logs
+
+**They complement each other:** Use structlog for logging, Nullscope for metrics/timing. They solve different problems.
+
+## vs prometheus_client
+
+**prometheus_client** is the official Python client for Prometheus metrics.
+
+| Aspect | Nullscope | prometheus_client |
+|--------|-----------|-------------------|
+| Metric types | Counters, gauges, timings | Full Prometheus types |
+| Scope hierarchy | Built-in | Manual labels |
+| Zero-cost disable | Yes | No |
+| Export format | Reporter-defined | Prometheus exposition |
+| Spans/timing | Yes (with wall clock) | Histograms only |
+
+**Use Nullscope when:**
+- You want automatic scope hierarchy
+- Zero overhead when disabled matters
+- You're not running Prometheus
+
+**Use prometheus_client when:**
+- You have a Prometheus infrastructure
+- You need summaries, histograms with buckets
+- You want direct Prometheus integration
+
+## vs timing decorators / manual timing
+
+Many projects use simple timing:
+
+```python
+import time
+start = time.perf_counter()
+do_work()
+duration = time.perf_counter() - start
+```
+
+| Aspect | Nullscope | Manual timing |
+|--------|-----------|---------------|
+| Zero-cost disable | Yes | No (unless you add conditionals) |
+| Scope hierarchy | Automatic | Manual |
+| Multiple reporters | Built-in | DIY |
+| Async safety | Context vars | DIY |
+
+**Use Nullscope when:**
+- You want consistent telemetry patterns
+- You need hierarchy tracking
+- You might disable telemetry in production
+
+**Use manual timing when:**
+- You have one or two timing points
+- You don't need hierarchy
+- Simplicity is paramount
+
+## Summary: When to Choose Nullscope
+
+Choose Nullscope if you value:
+
+1. **Zero overhead** when telemetry is disabled
+2. **Simple API** for timing and metrics
+3. **Automatic hierarchy** for nested operations
+4. **Library-friendly** design (no global state pollution)
+5. **Async-safe** out of the box
+
+Consider alternatives if you need:
+
+1. **Full distributed tracing** → OpenTelemetry
+2. **Structured logging** → structlog
+3. **Prometheus-native metrics** → prometheus_client
+4. **One-off timing** → manual `time.perf_counter()`