bronto-sdk 0.2.1__tar.gz

bronto_sdk-0.2.1/.gitignore

@@ -0,0 +1,69 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.cache
+.hypothesis/
+.pytest_cache/
+
+# Linters / type checkers
+.ruff_cache/
+.mypy_cache/
+
+# pyenv / uv — .python-version IS committed here (see the negation below) so that
+# every checkout and CI run develops on the same interpreter.
+.python-version
+!/.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Visual Studio Code — settings and extension recommendations are checked in
+# so every contributor and CI see the same diagnostics; everything else is local.
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+
+# Git
+*.orig
+
+# Internal planning notes. The full v0.1 plan names private sibling projects and
+# internal infrastructure; it lives outside this repository. Ignored here so a
+# stray copy can never be committed, or swept into an sdist by a build.
+/high-level-overview-plan.md
+/*-plan.md

bronto_sdk-0.2.1/.python-version

@@ -0,0 +1 @@
+3.14

bronto_sdk-0.2.1/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Breaking changes are listed first with a ⚠️ prefix.
+
+## [Unreleased]
+
+## [0.2.1] - 2026-11-11
+
+### Added
+
+- **Published on [PyPI](https://pypi.org/project/bronto-sdk/)** — install with
+  `pip install bronto-sdk` (or `bronto-sdk[mcp]`) instead of a GitHub Release
+  URL or a `git+https` requirement. Uploads use Trusted Publishing from the
+  release workflow (no API token exists) and carry PEP 740 provenance
+  attestations; PyPI receives exactly the files that are Sigstore-signed and
+  attached to the GitHub Release, which continues as before.
+  [SECURITY.md](https://github.com/bronto-community/bronto-sdk-python/blob/main/SECURITY.md#verifying-a-release)
+  covers verifying both.
+
+### Security
+
+- Refreshed `uv.lock` to PyJWT 2.15.1 and urllib3 2.8.0. Both reach the lock
+  only through the `mcp`/`langchain` extras and dev tooling; the SDK never
+  imports them and its published dependency ranges are unchanged, so installed
+  users resolve their own versions and are not affected.
+- Refreshed `uv.lock` to certifi 2026.10.23, which drops the emSign root CAs
+  whose intermediate keys were compromised (GHSA-6q48-6c7w-9gw2). certifi
+  reaches the lock only transitively through `httpx`; the SDK's published
+  dependency ranges are unchanged, so installed users resolve their own
+  certifi and should upgrade it in their own environments.
+
+### Changed
+
+- Refreshed `uv.lock` to pydantic 2.14.1, langchain-core 1.7.3, and newer dev
+  tooling (ruff 0.17.3, pytest 9.2.0, pytest-mock 3.17.0, pytest-asyncio
+  1.4.1.post1), and bumped the pinned CI actions. Published dependency ranges
+  are unchanged.
+
+## [0.2.0] - 2026-09-29
+
+### Added
+
+- **`client.metrics.retrieve_definition(metric_id)`** — `GET
+  /metrics/definitions/{id}`, returning a `MetricDefinition`.
+
+## [0.1.2] - 2026-09-18
+
+### Added
+
+- **Signed release artifacts.** The wheel and sdist are now signed with
+  [Sigstore](https://www.sigstore.dev/) during the release workflow, and a
+  `.sigstore.json` bundle is attached to the release beside each one. Signing is
+  keyless: the signature is made with a short-lived identity minted for that one
+  workflow run, so there is no signing key to hold and the repository still
+  stores no secrets. The signature attests that an artifact came from this
+  repository's release workflow running on the tag it claims.
+
+  Verifying needs only pip — `pip install sigstore`, then
+  `python -m sigstore verify identity`. [SECURITY.md](SECURITY.md) has the full
+  command. The release workflow verifies its own signatures before publishing,
+  so an artifact whose signature does not check never reaches a release.
+
+### Note
+
+- `v0.1.1` was tagged but never released: its release workflow failed while
+  signing, before anything was published. The tag is left in place because
+  release tags are immutable here. There is no v0.1.1 release, and nothing was
+  ever published under it.
+
+## [0.1.0] - 2026-09-17
+
+First release. Everything below is new.
+
+### Added
+
+- **Clients.** `BrontoClient` (sync) and `AsyncBrontoClient` (async) over
+  `httpx`, with identical method names, context-manager support, `close()` /
+  `aclose()`, and `from_env()` reading `BRONTO_API_KEY` plus `BRONTO_REGION` or
+  `BRONTO_BASE_URL`. A caller-supplied `http_client` is never closed by the SDK.
+  The async client adds a `max_concurrency` semaphore (default 20) bounding
+  in-flight requests. `client.get()` / `client.post()` remain public escape
+  hatches so an uncovered endpoint never blocks a consumer on an SDK release.
+- **Two-mode credentials.** A client is either *client-bound* (built with
+  `api_key` or `bearer_token`) or *per-request* (built with neither, holding no
+  credential). The modes never mix and there is no fallback between them, which
+  makes a long-lived multi-tenant client safe by construction. Bearer wins over
+  API key within one origin; an empty per-request credential fails closed.
+- **Error hierarchy.** `BrontoError`, `BrontoConfigError`,
+  `BrontoConnectionError` and `BrontoAPIError`, with status-mapped subclasses
+  for 400, 401, 403, 404, 429 (carrying `retry_after`) and 5xx. Errors expose
+  `status_code`, `correlation_id`, `details`, `error_type`, `body`, `headers`
+  and a `retryable` flag; `str()` always surfaces the status and correlation id.
+  No credential reaches an error, a `repr()` or a log line — headers are
+  redacted by key name and the stored body is bounded.
+- **Regional registry.** `validate_region`, `rest_base_url`, `mcp_url` and
+  `ingest_base_url`. Region is a validated slug rather than a closed enum, so a
+  new region works without an SDK release while a value that would smuggle a
+  host off `bronto.io` is rejected. `KNOWN_REGIONS` is a hint for error
+  messages, never an allow-list. Redirects are not followed, deliberately.
+- **Per-request options.** `RequestOptions` for `timeout`, `headers`, a
+  per-request credential, and an `idempotent` flag reserved for v0.2 retries.
+- **`bronto_sdk.models`:** Pydantic v2 models for the covered REST subset —
+  `SearchRequest`/`SearchResponse`, `Monitor`/`MonitorsResponse`,
+  `MonitorEventsResponse`, `Dataset`/`DatasetsResponse` and `ErrorResponse`.
+  Response models accept unknown fields so a new server-side field is additive,
+  and no sequence number or epoch-millisecond field is typed `float`.
+- **`bronto_sdk.resources`:** the typed operation surface, wired onto both
+  clients as `client.search`, `client.monitors` and `client.datasets` —
+  `search.run()`, `monitors.list()`, `monitors.retrieve()`, `monitors.events()`
+  and `datasets.list()`, each returning a parsed model. Path parameters are
+  URL-quoted.
+- **`bronto_sdk.domain`:** pure Bronto helpers with no I/O. `iso_to_ms`,
+  `ms_to_iso`, `parse_time_range` and `parse_window` resolve natural-language
+  windows the way the query engine does, with no `dateparser` dependency;
+  `quote_value`, `quote_attribute` and `wildcard_pattern` escape values for a
+  where clause — **opt-in, never automatic**; `project_dataset` reads both the
+  REST and MCP dataset shapes.
+- **`bronto_sdk.mcp`:** the MCP endpoint registry — `url()` (by region, or by
+  `base_url` for a staging deployment the region slug cannot name) and
+  `auth_headers()`. String and dict helpers only: no `mcp` or `langchain`
+  import, and no session opener until v0.2.
+- Documentation: a full README with quickstarts, the credential model, the
+  error hierarchy, the domain helpers and a migration table from an ad-hoc
+  client, plus four runnable scripts in `examples/`.
+
+### Not in this release
+
+Automatic retries and backoff, pagination iterators, an MCP session opener,
+LangChain tool decorators, OpenTelemetry hooks, an ingestion client (URL helper
+only), and REST coverage beyond the five operations above.
+
+[Unreleased]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/bronto-community/bronto-sdk-python/compare/v0.1.0...v0.1.2
+[0.1.0]: https://github.com/bronto-community/bronto-sdk-python/releases/tag/v0.1.0

bronto_sdk-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful, be constructive, assume good faith. Harassment or
+discriminatory behavior is not tolerated.
+
+Report violations privately to the maintainers via
+[GitHub's report-abuse flow](https://github.com/contact/report-abuse) or by
+opening a confidential security advisory on this repository.

bronto_sdk-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,205 @@
+# Contributing to bronto-sdk
+
+We welcome bug reports, feature requests, and pull requests. For anything that
+changes the public API or introduces substantial code, please open (or find) an
+issue first so we can agree on an approach before you write the code. Typo and
+documentation fixes do not need an issue.
+
+## 5-minute path
+
+```sh
+git clone https://github.com/bronto-community/bronto-sdk-python
+cd bronto-sdk-python
+uv sync          # create .venv and install the project + dev dependencies
+just prepare     # format, lint, typecheck, spec digest gate, tests
+```
+
+No network access or Bronto account is needed to run the test suite. All HTTP is
+mocked with `httpx.MockTransport`, so the fast suite never touches the network.
+
+## Development environment
+
+- **[`uv`](https://docs.astral.sh/uv/)** manages the virtual environment and
+  dependencies. `uv sync` creates `.venv` and installs everything; commit
+  `uv.lock` whenever dependencies change so CI stays reproducible.
+- **[`just`](https://just.systems/)** runs every project command through
+  `uv run`. `just --list` shows the recipes; the important ones are below.
+- Minimum supported Python is **3.11**. Local development happens on the newest
+  interpreter, but `pyright` and `ruff` are pinned to the 3.11 floor so
+  3.12+-only syntax cannot slip past and break the oldest CI leg.
+
+| Task | Command |
+| --- | --- |
+| Everything CI runs | `just prepare` |
+| Format | `just format` / `just format-check` |
+| Lint | `just lint` |
+| Lint the shell gates in `scripts/` | `just lint-shell` |
+| Typecheck (pyright strict on `src/bronto_sdk`) | `just typecheck` |
+| Tests | `just test` / `just test-one <name>` |
+| Build sdist + wheel | `just build` |
+| Verify the vendored spec digest | `just check-spec` |
+| Verify the three version files agree | `just check-version` |
+| Verify the built artifacts | `just check-dist` |
+| Verify the live ruleset matches the recorded checks | `just check-ruleset` |
+| Preview a release body | `just release-notes X.Y.Z` |
+
+## Tests
+
+- Prefer test-driven development for new behavior.
+- Use `pytest`, `pytest-mock`, and `pytest-asyncio` (`asyncio_mode = "auto"`).
+- Mock all HTTP with `httpx.MockTransport`; the fast suite must not hit the
+  network.
+- Sync and async clients expose identical method names — cover new client
+  behavior with the shared sync/async parity fixtures so both stay in step.
+- Coverage target is 90%+, realistic given the small surface.
+
+## The vendored OpenAPI spec
+
+`api/openapi.yaml` is a conformance reference, never a codegen source. It is
+digest-gated: any edit must ship with a regenerated `api/vendored.sha256` in the
+same commit. See `api/README.md` for the full re-vendoring checklist. `just
+check-spec` (part of `just prepare` and CI) fails on an unrecorded edit.
+
+## Changelog
+
+User-facing changes must add an entry under `## [Unreleased]` in
+`CHANGELOG.md` (Keep a Changelog format). List breaking changes first with a
+`⚠️` prefix. The pull request template has a `## Changelog` section for the same
+purpose.
+
+## Versioning
+
+Semver from day one. `v0.x` means the public API may still shift; breaking
+changes are called out with `⚠️` in the changelog. Bump the version with
+`just update-version X.Y.Z`, which writes `VERSION`, `src/bronto_sdk/_version.py`
+and `pyproject.toml` in one step.
+
+## Releasing (maintainers)
+
+A `vX.Y.Z` tag push runs `release.yml`, which builds the sdist and wheel,
+attaches both to a **GitHub Release**, then publishes the very same files to
+**[PyPI](https://pypi.org/project/bronto-sdk/)**. PyPI is what consumers
+install from (`pip install bronto-sdk`).
+
+PyPI uploads use [Trusted Publishing](https://docs.pypi.org/trusted-publishers/):
+the `publish` job exchanges a short-lived GitHub OIDC token for an upload
+credential, so there is no PyPI API token to store, rotate or leak. Do not add
+one, and do not upload by hand with `twine` — a hand upload has no attestation
+and is indistinguishable from a compromised one.
+
+To cut a release:
+
+1. Move the `## [Unreleased]` entries under a new `## [X.Y.Z] - YYYY-MM-DD`
+   heading in `CHANGELOG.md`, and add the link reference at the bottom. The
+   release body is extracted from this section, so a missing or empty one fails
+   the release — preview it with `just release-notes X.Y.Z`.
+2. `just update-version X.Y.Z`. It verifies its own work; a version it cannot
+   write to all three files is now an error rather than a silent no-op.
+3. `just prepare`, then commit.
+4. Tag `vX.Y.Z` and push the tag.
+5. **Approve the deployment.** The `release` job waits on the protected
+   `release` environment; approve it from the run's page in the Actions tab.
+   Either maintainer on the reviewer list can approve, including the person who
+   pushed the tag — the gate is there to make a release a deliberate, recorded
+   act, not to force a second pair of hands. The `publish` job runs on its own
+   once the GitHub Release exists; it needs no second approval.
+6. Check [pypi.org/project/bronto-sdk](https://pypi.org/project/bronto-sdk/)
+   shows the version, with "Provenance" on each file.
+
+If `publish` fails after the GitHub Release succeeded (PyPI outage,
+misconfigured publisher), fix the cause and use **Re-run failed jobs** on the
+same run. It re-uploads the artifacts the release job already signed; nothing
+is rebuilt and no version is spent.
+
+**A PyPI version is as permanent as its tag.** PyPI never accepts the same file
+name twice, even after the release is deleted. A bad release is yanked on PyPI
+(which hides it from new resolutions without breaking existing pins) and
+superseded by the next patch version — never deleted and re-uploaded.
+
+Signing is automatic and needs nothing from you: the workflow signs both
+artifacts with Sigstore using its own short-lived OIDC identity, verifies the
+signatures before publishing, and attaches a `.sigstore.json` bundle to each.
+[SECURITY.md](SECURITY.md) documents how a consumer checks them.
+
+The workflow gates the release on the tag matching the version files, then on
+the same lint/test/build checks a pull request runs — literally the same file,
+`.github/workflows/_checks.yml`, so a release cannot be verified on less than a
+pull request is.
+
+**Rehearse with `workflow_dispatch`, not with a tag.** Running `release.yml`
+from `main` exercises the version gate, the full test matrix and the build; the
+release and publish jobs are skipped because there is no tag.
+
+### One-time PyPI setup
+
+Already done for this repository; recorded so it can be checked or rebuilt.
+Trusted Publishing only works when both sides name each other exactly:
+
+- **PyPI**: the `bronto-sdk` project (owned by the Bronto PyPI organization) has
+  a GitHub trusted publisher with owner `bronto-community`, repository
+  `bronto-sdk-python`, workflow `release.yml`, environment `pypi`. Before the
+  first upload this is a *pending* publisher, added from the organization's
+  Publishing page so the project is created under the organization.
+- **GitHub**: a `pypi` environment (Settings → Environments) whose deployment
+  policy allows `v*` tags only, and no reviewers — approving `release` is the
+  gate. Restricting it to tags means a workflow run from a branch cannot obtain
+  a token PyPI will accept, even if the workflow file is edited on that branch.
+
+Renaming the workflow file or the environment breaks publishing until the PyPI
+publisher is updated to match.
+
+Do not push a throwaway `vX.Y.Zrc1` tag to rehearse. A repository ruleset makes
+every `v*` tag immutable — it cannot be moved or deleted once pushed, by anyone,
+including admins. That is deliberate: a tag a consumer has pinned must never
+change underneath them. The practical consequence is that any `v*` tag you push
+is permanent, so push one only when you mean it. A genuine pre-release is fine
+(a version with a letter in it, like `v1.2.0rc1`, is published as a GitHub
+pre-release and stays out of "latest"); a disposable one is not, because it
+cannot be disposed of.
+
+## What the repository enforces
+
+Settings are kept in step with the `bronto-cli` sibling so that the two repos
+are governed alike:
+
+- `main` takes changes only through a pull request, with linear history, all
+  review threads resolved, and the eight `Checks / …` jobs green. Force-pushes
+  and deletion are blocked, with no bypass for anyone.
+- `v*` tags cannot be moved or deleted (above).
+- Actions must be pinned to a commit SHA — GitHub rejects a tag reference
+  outright, which is the same rule `zizmor` enforces in CI.
+- Security vulnerabilities are reported privately; see [SECURITY.md](SECURITY.md).
+
+The names of those eight required checks are mirrored in
+`.github/required-status-checks.txt`. Two gates keep the mirror honest:
+`tests/unit/test_required_checks.py` fails when the list stops matching the
+names `ci.yml` and `_checks.yml` generate, and `just check-ruleset` (run weekly
+by `ruleset-drift.yml`) fails when it stops matching the live ruleset.
+
+### Renaming a required check
+
+Read this before touching a job name or the test matrix. **A pull request that
+renames or removes a required check wedges itself.** The old context stops
+reporting on that very pull request, GitHub shows it as pending rather than
+failed — a check that never reports is never late — and with no bypass actors
+nobody can merge it, including admins.
+
+Adding the new name to the ruleset first does not help: a required context that
+no job has produced yet blocks every open pull request immediately. The only
+order that never wedges anything is to **contract first**:
+
+1. Remove the outgoing context from the `protect-main` ruleset
+   (Settings → Rules, or `gh api`).
+2. Merge the pull request that renames the job or changes the matrix. It carries
+   the updated `.github/required-status-checks.txt`, which is what the offline
+   gate checks.
+3. Add the new context to the ruleset.
+
+Between steps 1 and 3 that one check is not enforced, which is the cost of never
+being locked out. Dropping a Python version renames six contexts at once, so
+expect to repeat step 1 for each.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By
+participating you agree to abide by it.

bronto_sdk-0.2.1/LICENSE

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