pyrock-core 0.1.0__tar.gz

pyrock_core-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+
+# Environments and tools
+.venv/
+venv/
+.python-version
+.uv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.dmypy.json
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Profiles and editors
+*.prof
+*.pprof
+.idea/
+.vscode/
+.DS_Store
+
+# Profiler output
+*.prof
+prof.out

pyrock_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+Notable changes to pyrock are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases use
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Because pyrock is
+pre-1.0, minor releases may include intentional API or behavior changes; each
+one is listed with a migration note.
+
+## Unreleased
+
+No changes yet.
+
+## [0.1.0] - 2026-11-08
+
+The initial release: a zero-dependency Python port of
+[Bedrock](https://github.com/kzs0/bedrock) for CPython 3.11+, including the
+free-threaded build.
+
+Published on PyPI as `pyrock-core` (`pip install pyrock-core`); the import
+package is `pyrock`. The name `pyrock` is taken on PyPI.
+
+### Added
+
+- Core API: `pyrock.init()`, `pyrock.Bedrock`, and `operation`, `step` and
+  `source` as sync/async context managers and as decorators for functions,
+  coroutines, generators and async generators. Also `start_operation` for a
+  manual lifecycle, `register`, `current`, `current_operation`,
+  `current_span` and `current_span_context`.
+- Operation metrics with the same names as Go (`<name>_count`, `_successes`,
+  `_failures`, `_duration_ms`), labels declared up front with a `"_"` default,
+  static labels, and series and family limits.
+- Success by default: an escaping exception marks failure and is re-raised;
+  `expected=` exceptions do not. Error attributes (`error`, `error.type`,
+  `error.fingerprint`, `error.chain`, `error.group.count`, `error.types`) come
+  from `attr.error`.
+- `no_trace`, numbered duplicate span names, and preallocated noop objects
+  when nothing is active.
+- Context helpers for threads: `bind`, `ContextThreadPoolExecutor` and
+  `pyrock.Thread` (with `context=`).
+- Tracing: `Tracer`/`Span`/`SpanContext`, W3C Trace Context (`trace.w3c`), an
+  HTTP propagator, a `Propagator` protocol with `CompositePropagator`, and the
+  `AlwaysOn`, `AlwaysOff`, `Ratio` and `ParentBased` samplers.
+- OTLP trace export over HTTP/JSON (`urllib`) and gRPC, through a minimal
+  in-house HTTP/2 client (TLS with ALPN or h2c) and a hand-written protobuf
+  encoder; a bounded batch processor with export statistics.
+- Metrics: a thread-safe registry of counters, gauges and histograms with
+  `.labels()`, histogram timers, runtime metrics (`python_*`, `process_*`), and
+  validated Prometheus text exposition.
+- Logging on stdlib `logging`: a JSON or text handler, `CorrelationFilter`,
+  the `debug`/`info`/`warning`/`warn`/`error`/`log` helpers, canonical
+  `operation.complete` records, and `log_install` modes (`root`, `pyrock`,
+  `none`).
+- HTTP: WSGI and ASGI 3 middleware (opt-in websocket operations), stdlib
+  `http.server` instrumentation (`http.instrument_http_server`), and an
+  instrumented `urllib` client (`http.get`/`post`/`request`, `build_opener`,
+  `TracingHandler`) plus `inject_headers` for third-party clients.
+- The observability server (`/metrics`, `/health`, `/ready`, optional
+  `/debug/pprof/*`) with Go's security defaults and a connection cap.
+- Profiles: CPU, WALL, HEAP, THREADS (`GOROUTINE`), MUTEX and BLOCK, encoded
+  as OTLP Profiles (v0.2.0) and pprof, exported over HTTP
+  (`ProfileExportConfig`) and served by the optional `profile.debug` handler,
+  which works with `go tool pprof`. Instrumented `Lock`, `RLock`, `Condition`
+  and `Semaphore` feed MUTEX and BLOCK.
+- The cloud backend (`pyrock.cloud`, `CloudConfig`): gRPC traces with
+  `x-bedrock-key`, retry with configurable `retry_backoff`, fan-out to a local
+  `trace_url`, metrics push and profile push.
+- `privacy.Policy` enforced on spans, events, logs, metric labels and profile
+  labels.
+- Environment detection (process, git, Kubernetes, container, AWS, GCP) under
+  a 500 ms budget.
+- `Config` with `BEDROCK_*` environment variables in Go's syntax, plus the
+  Python-only `BEDROCK_LOG_INSTALL` and `BEDROCK_SERVER_MAX_CONNECTIONS`;
+  `ConfigError` lists every problem. `env.parse` reads typed dataclasses.
+- `pyrock.testing.capture()` and the `pyrock_capture` pytest fixture
+  (registered by entry point; pyrock never imports pytest).
+- Fork safety: an `os.register_at_fork` hook resets state and restarts
+  background threads in the child.
+- Runnable stdlib examples (`examples/http_server.py`, `asgi_app.py`,
+  `worker.py`) and copy-in recipes for httpx, requests, grpcio, Flask, Django
+  and FastAPI.
+- `README.md`, `CONTRIBUTING.md` and `SECURITY.md`; CI on Python 3.11–3.15
+  and 3.14t (`PYTHON_GIL=0`), a 3.14t stress job, macOS and Windows runs, the
+  compat suite (official OTLP protos, a real grpcio collector) and a
+  pure-wheel build check.
+
+### Behavior decisions
+
+These differ from Go Bedrock, or settle points the design left open:
+
+- `Ratio` samples deterministically on the trace ID, and `ParentBased` drops
+  spans whose parent is unsampled.
+- JSON log levels use Go's names (`DEBUG`, `INFO`, `WARN`, `ERROR`);
+  `CRITICAL` stays `CRITICAL`.
+- Counters raise `ValueError` on negative or NaN increments. A different
+  `help` on re-registration is not a conflict (the first registration wins,
+  as in Go).
+- Decorators always wrap and resolve the active instance at call time, so
+  functions decorated before `init()` are instrumented.
+- Numbering applies only to siblings under the same operation or step; root
+  operations and direct children of a source are never numbered.
+- There is no process-wide default instance and no monkey-patching of
+  `threading`. Middleware captures the instance at construction and activates
+  it per request. On interpreters that inherit context into new threads
+  (free-threaded 3.14), threads see the active instance.
+- `http.user_agent`, `http.target` and `http.url` are emitted only when the
+  privacy policy allowlists them.
+- `Config.log_level` takes level names only; the log helpers also take ints.
+- `/debug/pprof` without a trailing slash is 404, and a CPU profile longer
+  than 30 s is rejected with 400, as in Go.
+- CPU samples carry no asyncio task label; the profile exporter collects the
+  first profiles immediately on start.
+- `Activation`, `MetricConflictError` and `MetricLimitError` can be imported
+  from `pyrock` but are not part of `__all__`.

pyrock_core-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing to pyrock
+
+Thanks for helping improve pyrock. Small, focused changes with tests and clear
+compatibility notes are easiest to review.
+
+## Before starting
+
+Search the [issue tracker](https://github.com/kzs0/pyrock/issues) for related
+work. Open an issue before a large feature, public API change or behavior
+change, so the scope can be agreed before implementation. Security reports
+must follow [SECURITY.md](SECURITY.md), not the public issue tracker.
+
+You need [uv](https://docs.astral.sh/uv/). `uv sync` creates `.venv` with the
+dev tools (pytest, coverage, ruff, mypy); uv installs any interpreter the
+targets ask for. Clone your fork, create a topic branch, and keep unrelated
+changes in separate pull requests.
+
+## Rules for every change
+
+- **Zero runtime dependencies.** Everything under `src/` imports only the
+  standard library; `[project.dependencies]` stays empty. A structural test
+  enforces this. Test-only packages belong in a dependency group (`compat`),
+  and their tests must skip cleanly when the packages are missing. Do not add
+  or update tool dependencies unless the change requires it and the pull
+  request explains the tradeoff.
+- **Python 3.11 baseline.** Code must stay valid on 3.11: use
+  `from __future__ import annotations`, PEP 604 unions, `typing.Self` and
+  `dataclass(slots=True)`, and no 3.12+ syntax (`type X = ...`, PEP 695
+  generics). Newer stdlib APIs (for example `sys._is_gil_enabled`) are allowed
+  only behind feature detection in `pyrock._compat`.
+- **Free-threaded safety.** Never rely on the GIL. Shared mutable state is
+  guarded by a `threading.Lock`; CI runs the suite on 3.14t with
+  `PYTHON_GIL=0` and repeats the concurrency-sensitive tests (`make stress`).
+- **Keep the design.** No process-wide globals (state lives in
+  `contextvars`), no monkey-patching, controlled metric cardinality, and the
+  dependency boundaries in `tests/structure/test_structure.py`. Heavy modules
+  stay lazy, so `import pyrock` remains cheap.
+- **Tests are the contract.** Test observable behavior (OTLP bytes, exposition
+  text, log JSON, HTTP responses), not internals. Do not weaken or rewrite an
+  existing test to make a change pass; if you believe a test is wrong, say so
+  in the pull request and change it deliberately, with a changelog entry.
+  Cover success, failure, boundary, cancellation and concurrency where
+  relevant.
+- **Deterministic tests.** Wait on events, barriers and test servers, not
+  `time.sleep`. Bind every test server to `127.0.0.1:0`. Use the fakes in
+  `tests/support/`.
+- **Docs.** Update `README.md` (and `DESIGN.md` when the design changes) and
+  the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md) when behavior,
+  configuration or API changes.
+
+## Validate
+
+```bash
+make fmt                # ruff format + ruff check --fix
+make ci                 # what CI's lint and coverage jobs run
+```
+
+`make ci` runs `ruff format --check`, `ruff check`, `mypy --strict src`, and
+the full test suite under coverage with an 80% branch-coverage gate. Also run,
+as relevant:
+
+- `make matrix` for every supported interpreter (3.11 to 3.15 and 3.14t with
+  the GIL disabled);
+- `make stress` after touching threads, fork handling, the batch processor or
+  the server;
+- `make compat` after touching OTLP encoding or gRPC (official protos, a real
+  grpcio collector);
+- `make build` after packaging changes (the wheel must stay pure Python with no
+  `Requires-Dist`).
+
+CI runs the same commands on Linux for every interpreter, a 3.14t stress job,
+3.14 on macOS and Windows, the compat suite and a wheel check.
+
+## Compatibility
+
+pyrock is below 1.0. Minor releases may contain intentional API or behavior
+changes, but changes should still minimize disruption. A breaking change
+needs:
+
+- a clear reason and migration path;
+- tests for the new contract;
+- documentation updates; and
+- an explicit changelog entry under `Changed`.
+
+Wire compatibility with Go Bedrock (metric names, span attributes, log shape,
+`BEDROCK_*` variables) is a feature. A deliberate difference must be listed in
+the README's "Differences from Go Bedrock" section.
+
+Bug fixes may reject input that was previously accepted incorrectly, or make
+shutdown and network behavior stricter. Call these effects out so operators
+can test their configuration before upgrading.
+
+## Pull requests
+
+Describe the problem, the chosen behavior, compatibility or security impact,
+and the commands used to validate the change. Link related issues. Keep
+commits reviewable; maintainers may squash or rebase when merging.
+
+## Release process
+
+Releases are maintainer-driven tags, published by the `Release` workflow
+(`.github/workflows/release.yml`). For a release, a maintainer:
+
+1. sets the version in `src/pyrock/_version.py` (`X.Y.Z`, or `X.Y.ZaN`,
+   `X.Y.ZbN` or `X.Y.ZrcN` for a prerelease) and moves the relevant
+   `Unreleased` entries to a dated `## [X.Y.Z] - YYYY-MM-DD` section;
+2. verifies `make ci`, `make matrix` and `make compat` on the release commit
+   (`python3 scripts/release.py check vX.Y.Z` checks the version and
+   changelog locally);
+3. merges the release change to `main`;
+4. creates and pushes the tag `vX.Y.Z` (exactly `v` plus the version) on that
+   commit of `main`:
+
+   ```bash
+   git tag -a v0.1.0 -m "pyrock 0.1.0" <commit-on-main>
+   git push origin v0.1.0
+   ```
+
+5. lets the workflow run. It
+   - checks the tag matches the package version, the changelog has a dated
+     section for it, and the commit is on `main`;
+   - runs the full CI workflow as a gate;
+   - publishes the exact wheel and sdist CI built and checked to PyPI, using
+     trusted publishing (no API token is stored); and
+   - creates the GitHub Release with the changelog section as notes and the
+     distribution files attached, marked as a prerelease for `a`/`b`/`rc`
+     versions; and
+6. starts a fresh `Unreleased` section and a `.dev0` version on `main`.
+
+Release tags must point to `main`. Never move or reuse an existing tag;
+publish a new patch version for corrections. A failed run can be re-run: each
+publishing step is safe to repeat once its predecessor succeeded.
+
+### One-time PyPI setup
+
+PyPI trusted publishing has to be configured once, by a maintainer with a PyPI
+account:
+
+1. On PyPI, add a *pending* trusted publisher for the project `pyrock-core`
+   (Account settings → Publishing): owner `kzs0`, repository `pyrock`,
+   workflow `release.yml`, environment `pypi`.
+2. On GitHub, create the `pypi` environment (Settings → Environments). Adding
+   required reviewers there makes every PyPI upload wait for an approval.