pitchside 0.1.0__tar.gz

pitchside-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Secrets. Never commit a real API key.
+.env
+.env.*
+!.env.example
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/

pitchside-0.1.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-28
+
+First release. Wraps all 118 documented endpoints of the Big Balls Sports
+Data API, sync and async.
+
+### Added
+
+- **Clients.** `Pitchside` and `AsyncPitchside`, with identical method
+  names and signatures across 22 resource namespaces. A contract test
+  enforces that they do not drift apart.
+- **Envelope normalisation.** The API uses at least five response shapes
+  depending on the route, and `pitchside.envelope` reduces them to one.
+  Collections nested under route-specific keys (`data.matches`,
+  `data.leaders`, `data.groups`, …) are unwrapped to plain lists.
+- **Typed errors.** Full hierarchy under `PitchsideError`, with
+  `PlanRequiredError.required_plan` parsed from the upstream message or
+  `upgrade_path`, and `RateLimitError.is_circuit_breaker` distinguishing
+  quota exhaustion from the 4xx breaker.
+- **Unified "not found".** A real `404`, a `200` with `data: null`, and a
+  `200` carrying `meta.coverage: false` all raise `NotFoundError`.
+- **Retries.** Exponential backoff with full jitter, honouring
+  `Retry-After`, capped so a day-long quota reset fails fast rather than
+  hanging. Only idempotent requests are replayed.
+- **Pagination.** `Page` / `AsyncPage` with `auto_paging_iter()`.
+  Routes that accept `?offset=` but report no pagination block get a
+  synthesised one, so paging works there too.
+- **Rate-limit tracking.** `client.rate_limit` parses `X-RateLimit-*`,
+  including the per-route budgets that sit on top of the account-wide one.
+- **Models.** Lenient by design, so unknown fields are preserved and
+  reachable via `.get()`, since the published spec and the live service
+  disagree in many places. Upstream data-quality issues are normalised on
+  parse (padded player names, string percentages, mixed jersey types).
+- **Webhooks.** Subscription CRUD with idempotency, plus
+  `pitchside.webhooks.verify_signature()` for delivery verification,
+  constant-time comparison and a replay window.
+- **Streaming.** Polling-based live scores, sync and async, single-match
+  and whole-slate, with an interval floor to protect quota.
+- **CLI.** `pitchside` via the `cli` extra, with `--json` on every command.
+
+### Notes on the upstream API
+
+Documented in full in the README, and pinned by tests that report when the
+vendor fixes them:
+
+- `GET /v1/teams/{id}/season` returns `500` unconditionally.
+- `GET /v1/matches/{id}/events` returns a fixed demo payload unrelated to
+  the requested fixture.
+- `GET /v1/players/{id}` requires an undocumented `?sport=`, then times
+  out. Use `client.players.profile()`.
+- `GET /v1/injuries` requires `sport` or `team` despite the spec marking
+  both optional, and often exceeds 30 seconds.
+- The advertised WebSocket at `wss://api.bigballsdata.com/live` is
+  non-functional, because every URL and auth style tested has its
+  handshake rejected with `400`. `pitchside.streaming` polls instead.
+- Identifiers are not interchangeable between routes. See the README.
+- `WebhookEvent` follows the server validator, which disagrees with both
+  the OpenAPI spec and the public docs page.
+
+[0.1.0]: https://pypi.org/project/pitchside/0.1.0/

pitchside-0.1.0/LICENSE

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