pitchapi 0.1.0__tar.gz

pitchapi-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python build & cache artifacts
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/

pitchapi-0.1.0/LICENSE

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

pitchapi-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: pitchapi
+Version: 0.1.0
+Summary: Python SDK for the PitchAPI football-data API
+Project-URL: Homepage, https://pitchapi.dev
+Project-URL: Documentation, https://pitchapi.dev/#sdks
+Project-URL: Changelog, https://pitchapi.dev/#changelog
+Author: PitchAPI
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,football,opta,sdk,soccer,xg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pitchapi — Python SDK
+
+Typed Python client for the [PitchAPI](https://pitchapi.dev) football-data API.
+Match results, shots, xG, lineups, momentum, events, player stats, head-to-head,
+and Opta-derived advanced analytics.
+
+- Sync **and** async clients over one shared core (`httpx`)
+- Plain `dataclass` response models — a faithful mirror of the API's JSON, built
+  through a small `from_dict` converter (no Pydantic, one dependency)
+- Typed exceptions mapped from the API's stable `error.code`
+- Automatic retries on `429`/`5xx` with `Retry-After` honoured
+
+## Install
+
+```bash
+pip install pitchapi
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+from pitchapi import PitchAPI
+
+with PitchAPI(api_key="pk_live_...") as client:
+    day = client.date.get("2026-08-27")
+    for m in day.matches:
+        print(m.home_team.name, m.score_home, "-", m.score_away, m.away_team.name)
+
+    match = client.matches.get("m_4DP2fy")
+    shots = client.matches.shots(match.id)
+    adv = client.matches.advanced(match.id)          # team rollups
+    net = client.matches.advanced_network(match.id)  # pass networks
+```
+
+The key can also come from the `PITCHAPI_API_KEY` environment variable, in which
+case `PitchAPI()` needs no arguments.
+
+## Async
+
+```python
+import asyncio
+from pitchapi import AsyncPitchAPI
+
+async def main():
+    async with AsyncPitchAPI() as client:
+        league = await client.leagues.get("l_0bfbkO")
+        matches = await client.leagues.matches(league.id, season="2025-2026")
+        print(len(matches.matches), "matches")
+
+asyncio.run(main())
+```
+
+## Namespaces
+
+| Namespace | Methods |
+|---|---|
+| `client.date` | `get(date, status=None)` — `date` is a `str` (`YYYY-MM-DD`) or a `datetime.date` |
+| `client.matches` | `get`, `shots`, `shot`, `events`, `lineups`, `momentum`, `stats`, `players`, `player`, `player_shots`, `h2h`, `advanced`, `advanced_network`, `advanced_players`, `advanced_player` |
+| `client.leagues` | `list`, `get`, `matches(id, season=None, status=None)` |
+| `client.teams` | `get` |
+| `client.players` | `get` |
+
+Every method returns a typed dataclass from `pitchapi.models`. Per-player match
+`stats` is a raw `dict` because its shape varies by position.
+
+## Upcoming fixtures
+
+Match listings return played matches by default. Pass `status` to reach
+scheduled ones — `"upcoming"` for fixtures that have not kicked off, `"all"` for
+both. An upcoming match carries a kickoff `time_utc` and a `status`, but its
+scores are `None` until it is played.
+
+```python
+for m in client.date.get("2026-09-01", status="upcoming").matches:
+    print(m.time_utc, m.home_team.name, "vs", m.away_team.name)
+
+# Within a season. The season is resolved first, so asking for upcoming
+# fixtures of a finished campaign is an empty list, not next season's.
+client.leagues.matches("l_0bfbkO", season="2025-2026", status="all")
+```
+
+Lineups for a fixture may be a pre-match prediction rather than the real XI.
+`confirmed` is the flag to branch on; `lineup_type` carries the source's own
+label for a prediction and is `None` once the lineup is confirmed.
+
+```python
+lineups = client.matches.lineups("m_4DP2fy")
+if lineups.home.confirmed:
+    print(lineups.home.formation, [p.name for p in lineups.home.starters])
+else:
+    print("predicted only:", lineups.home.lineup_type)
+```
+
+## Errors
+
+```python
+from pitchapi import NotFoundError, PlanUpgradeRequiredError, RateLimitError
+
+try:
+    client.matches.advanced("m_unprocessed")
+except NotFoundError as e:
+    # code is RESOURCE_NOT_FOUND or ANALYTICS_UNAVAILABLE
+    print(e.code, e.request_id)
+except PlanUpgradeRequiredError:
+    ...  # league is Pro-only
+except RateLimitError as e:
+    print("retry after", e.retry_after, "s")
+```
+
+All exceptions derive from `pitchapi.PitchAPIError` and carry `code`,
+`status_code`, and `request_id` where available.
+
+## Configuration
+
+```python
+PitchAPI(
+    api_key="pk_live_...",
+    base_url="https://api.pitchapi.dev",  # override for self-hosting/tests
+    timeout=30.0,
+    max_retries=2,                        # 429/5xx + network errors; 0 disables
+)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest              # tests use httpx.MockTransport — no network
+mypy                # scoped to src/ by pyproject
+ruff check .
+ruff format --check .
+```
+
+## OpenAPI
+
+A full OpenAPI 3.1 description of the API lives at
+[`openapi/openapi.yaml`](../../openapi/openapi.yaml) in the repository root. The
+dataclass models in this SDK mirror its schemas one-to-one.
+
+## License
+
+This client library is released under the [MIT License](LICENSE).
+
+The licence covers the SDK source only. Access to the PitchAPI service and the
+football data it returns is governed separately by the PitchAPI terms of
+service — an MIT-licensed client does not grant any right to the data.

pitchapi-0.1.0/README.md

@@ -0,0 +1,148 @@
+# pitchapi — Python SDK
+
+Typed Python client for the [PitchAPI](https://pitchapi.dev) football-data API.
+Match results, shots, xG, lineups, momentum, events, player stats, head-to-head,
+and Opta-derived advanced analytics.
+
+- Sync **and** async clients over one shared core (`httpx`)
+- Plain `dataclass` response models — a faithful mirror of the API's JSON, built
+  through a small `from_dict` converter (no Pydantic, one dependency)
+- Typed exceptions mapped from the API's stable `error.code`
+- Automatic retries on `429`/`5xx` with `Retry-After` honoured
+
+## Install
+
+```bash
+pip install pitchapi
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+from pitchapi import PitchAPI
+
+with PitchAPI(api_key="pk_live_...") as client:
+    day = client.date.get("2026-08-27")
+    for m in day.matches:
+        print(m.home_team.name, m.score_home, "-", m.score_away, m.away_team.name)
+
+    match = client.matches.get("m_4DP2fy")
+    shots = client.matches.shots(match.id)
+    adv = client.matches.advanced(match.id)          # team rollups
+    net = client.matches.advanced_network(match.id)  # pass networks
+```
+
+The key can also come from the `PITCHAPI_API_KEY` environment variable, in which
+case `PitchAPI()` needs no arguments.
+
+## Async
+
+```python
+import asyncio
+from pitchapi import AsyncPitchAPI
+
+async def main():
+    async with AsyncPitchAPI() as client:
+        league = await client.leagues.get("l_0bfbkO")
+        matches = await client.leagues.matches(league.id, season="2025-2026")
+        print(len(matches.matches), "matches")
+
+asyncio.run(main())
+```
+
+## Namespaces
+
+| Namespace | Methods |
+|---|---|
+| `client.date` | `get(date, status=None)` — `date` is a `str` (`YYYY-MM-DD`) or a `datetime.date` |
+| `client.matches` | `get`, `shots`, `shot`, `events`, `lineups`, `momentum`, `stats`, `players`, `player`, `player_shots`, `h2h`, `advanced`, `advanced_network`, `advanced_players`, `advanced_player` |
+| `client.leagues` | `list`, `get`, `matches(id, season=None, status=None)` |
+| `client.teams` | `get` |
+| `client.players` | `get` |
+
+Every method returns a typed dataclass from `pitchapi.models`. Per-player match
+`stats` is a raw `dict` because its shape varies by position.
+
+## Upcoming fixtures
+
+Match listings return played matches by default. Pass `status` to reach
+scheduled ones — `"upcoming"` for fixtures that have not kicked off, `"all"` for
+both. An upcoming match carries a kickoff `time_utc` and a `status`, but its
+scores are `None` until it is played.
+
+```python
+for m in client.date.get("2026-09-01", status="upcoming").matches:
+    print(m.time_utc, m.home_team.name, "vs", m.away_team.name)
+
+# Within a season. The season is resolved first, so asking for upcoming
+# fixtures of a finished campaign is an empty list, not next season's.
+client.leagues.matches("l_0bfbkO", season="2025-2026", status="all")
+```
+
+Lineups for a fixture may be a pre-match prediction rather than the real XI.
+`confirmed` is the flag to branch on; `lineup_type` carries the source's own
+label for a prediction and is `None` once the lineup is confirmed.
+
+```python
+lineups = client.matches.lineups("m_4DP2fy")
+if lineups.home.confirmed:
+    print(lineups.home.formation, [p.name for p in lineups.home.starters])
+else:
+    print("predicted only:", lineups.home.lineup_type)
+```
+
+## Errors
+
+```python
+from pitchapi import NotFoundError, PlanUpgradeRequiredError, RateLimitError
+
+try:
+    client.matches.advanced("m_unprocessed")
+except NotFoundError as e:
+    # code is RESOURCE_NOT_FOUND or ANALYTICS_UNAVAILABLE
+    print(e.code, e.request_id)
+except PlanUpgradeRequiredError:
+    ...  # league is Pro-only
+except RateLimitError as e:
+    print("retry after", e.retry_after, "s")
+```
+
+All exceptions derive from `pitchapi.PitchAPIError` and carry `code`,
+`status_code`, and `request_id` where available.
+
+## Configuration
+
+```python
+PitchAPI(
+    api_key="pk_live_...",
+    base_url="https://api.pitchapi.dev",  # override for self-hosting/tests
+    timeout=30.0,
+    max_retries=2,                        # 429/5xx + network errors; 0 disables
+)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest              # tests use httpx.MockTransport — no network
+mypy                # scoped to src/ by pyproject
+ruff check .
+ruff format --check .
+```
+
+## OpenAPI
+
+A full OpenAPI 3.1 description of the API lives at
+[`openapi/openapi.yaml`](../../openapi/openapi.yaml) in the repository root. The
+dataclass models in this SDK mirror its schemas one-to-one.
+
+## License
+
+This client library is released under the [MIT License](LICENSE).
+
+The licence covers the SDK source only. Access to the PitchAPI service and the
+football data it returns is governed separately by the PitchAPI terms of
+service — an MIT-licensed client does not grant any right to the data.

pitchapi-0.1.0/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pitchapi"
+# Single-sourced from src/pitchapi/__init__.py, which is also what the
+# User-Agent reports — one place to bump, no way for the two to drift.
+dynamic = ["version"]
+description = "Python SDK for the PitchAPI football-data API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "PitchAPI" }]
+keywords = ["football", "soccer", "opta", "xg", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+# Upper bounds on the linters only: both change their default behaviour between
+# minor releases, and CI should fail on a real regression rather than on an
+# upstream rule that did not exist when the code was written.
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.21",
+    "mypy>=1.5,<2",
+    "ruff>=0.6,<0.17",
+]
+
+# Every URL here is rendered publicly on the PyPI project page. The source repo
+# is private, so it is deliberately not listed: linking it would publish both the
+# owner's account name and the repository name to anyone reading the page.
+[project.urls]
+Homepage = "https://pitchapi.dev"
+Documentation = "https://pitchapi.dev/#sdks"
+Changelog = "https://pitchapi.dev/#changelog"
+
+[tool.hatch.version]
+path = "src/pitchapi/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pitchapi"]
+
+# Listed explicitly rather than defaulting to "everything git does not ignore".
+# The sdist is a published artifact that anyone can download and read, so a file
+# added to this directory later — a release runbook, internal notes — must not
+# ship by accident. It ships only if it appears below.
+[tool.hatch.build.targets.sdist]
+include = [
+    "src",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+# Selected explicitly rather than relying on ruff's defaults, which grow between
+# minor releases — an unpinned ruff would otherwise start failing code that has
+# not changed. Two families are left out on purpose:
+#
+#   UP / FA — pyupgrade and the future-annotations rules want to rewrite
+#     `Optional[X]` to `X | None` and add `from __future__ import annotations`
+#     to the model modules. Both are wrong here. The package supports 3.9, where
+#     `X | None` is a runtime TypeError outside an annotation; and
+#     models/_convert.py reads `dataclasses.fields(cls)[i].type` as a real type
+#     object, which only holds while the model modules keep their annotations
+#     un-postponed. See the design notes in that module.
+select = ["E", "W", "F", "I", "B", "C4", "SIM", "RUF"]
+# `__all__` is grouped by meaning (clients, then models, then errors) and
+# mirrors the import block above it; alphabetical order would lose that.
+ignore = ["RUF022"]
+
+[tool.mypy]
+# Strict mode covers the shipped package. The tests are deliberately loose —
+# the httpx mock handlers take whatever shape each case needs — so `files`
+# scopes a bare `mypy` to src rather than leaving that to the caller.
+files = ["src"]
+# No `python_version`: mypy no longer accepts a 3.9 target, so the version under
+# test is whichever interpreter CI runs it on. The matrix covers 3.9 upward.
+strict = true
+warn_unused_ignores = false
+
+[tool.pyright]
+include = ["src", "tests"]
+extraPaths = ["src"]
+
+[tool.ruff.format]
+# The formatter owns Python code and nothing else. Recent ruff versions also
+# reformat fenced code in Markdown and docstrings by default, which flattens the
+# indented reST literal blocks the module docstrings rely on and rewraps the
+# hand-aligned trailing comments in README examples.
+docstring-code-format = false
+exclude = ["*.md"]

pitchapi-0.1.0/src/pitchapi/__init__.py

@@ -0,0 +1,44 @@
+"""PitchAPI — Python SDK for the PitchAPI football-data API.
+
+Example:
+    from pitchapi import PitchAPI
+
+    with PitchAPI(api_key="pk_live_...") as client:
+        for m in client.date.get("2026-08-27").matches:
+            print(m.home_team.name, m.score_home, "-", m.score_away, m.away_team.name)
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from . import models
+from .client import AsyncPitchAPI, PitchAPI
+from .errors import (
+    APIConnectionError,
+    AuthError,
+    InvalidParameterError,
+    NotFoundError,
+    PitchAPIError,
+    PlanUpgradeRequiredError,
+    RateLimitError,
+    ServerError,
+    SubscriptionSuspendedError,
+)
+
+__all__ = [
+    "__version__",
+    "PitchAPI",
+    "AsyncPitchAPI",
+    "models",
+    # errors
+    "PitchAPIError",
+    "APIConnectionError",
+    "InvalidParameterError",
+    "AuthError",
+    "SubscriptionSuspendedError",
+    "PlanUpgradeRequiredError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]

pitchapi-0.1.0/src/pitchapi/_transport.py

@@ -0,0 +1,101 @@
+"""Transport-level helpers shared by the sync and async clients.
+
+Keeping envelope handling, error mapping, and the retry policy here means the
+two clients differ only in how they run the HTTP call itself, not in how they
+interpret the result.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any, Optional
+
+from . import __version__
+from .errors import (
+    PitchAPIError,
+    RateLimitError,
+    ServerError,
+    exception_for_code,
+)
+
+DEFAULT_BASE_URL = "https://api.pitchapi.dev"
+API_PREFIX = "/v1"
+
+# Statuses that a GET may safely be replayed on. Everything else (400/401/403/
+# 404) is a deterministic client error and is surfaced immediately.
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+def user_agent() -> str:
+    return f"pitchapi-python/{__version__}"
+
+
+def build_headers(api_key: str, extra: Optional[dict[str, str]] = None) -> dict[str, str]:
+    headers = {
+        "X-API-KEY": api_key,
+        "Accept": "application/json",
+        "User-Agent": user_agent(),
+    }
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def should_retry(status: int, attempt: int, max_retries: int) -> bool:
+    return attempt < max_retries and status in _RETRY_STATUSES
+
+
+def backoff_seconds(attempt: int, retry_after: Optional[int]) -> float:
+    """Delay before the next attempt.
+
+    Honours a server-provided ``Retry-After`` exactly; otherwise falls back to
+    exponential backoff with full jitter so retried clients do not synchronise.
+    """
+    if retry_after is not None and retry_after >= 0:
+        return float(retry_after)
+    base = min(2.0**attempt, 8.0)
+    return random.uniform(0.0, base)
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def unwrap(status: int, payload: Any, request_id: Optional[str], retry_after: Optional[int]) -> Any:
+    """Return the ``data`` object on success, or raise the mapped exception.
+
+    ``payload`` is the already-decoded JSON body, or ``None`` when the body was
+    absent or not JSON (which is itself an error for this API).
+    """
+    if 200 <= status < 300:
+        if isinstance(payload, dict) and "data" in payload:
+            return payload["data"]
+        # A 2xx without the envelope should not happen; surface it rather than
+        # hand back a shape the models cannot parse.
+        raise PitchAPIError(
+            "malformed success response: missing 'data' envelope",
+            status_code=status,
+            request_id=request_id,
+        )
+
+    code: Optional[str] = None
+    message = f"HTTP {status}"
+    if isinstance(payload, dict):
+        err = payload.get("error")
+        if isinstance(err, dict):
+            code = err.get("code")
+            message = err.get("message", message)
+
+    exc_cls = exception_for_code(code, status)
+    if exc_cls is RateLimitError:
+        raise RateLimitError(
+            message, retry_after=retry_after, code=code, status_code=status, request_id=request_id
+        )
+    if exc_cls is ServerError and code is None:
+        message = f"server error (HTTP {status})"
+    raise exc_cls(message, code=code, status_code=status, request_id=request_id)