py-understat 0.1.0__tar.gz

py_understat-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions: {}
+
+jobs:
+  build:
+    name: Test and build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run ty check
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/py-understat
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

py_understat-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.env
+.venv
+testing/**
+__pycache__/
+*.py[cod]
+.pytest_cache/
+build/
+dist/
+*.egg-info/

py_understat-0.1.0/.python-version

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

py_understat-0.1.0/CONTEXT.md

@@ -0,0 +1,25 @@
+# Understat Data
+
+This context retrieves football statistics published by Understat. It presents Understat resources through a stable Python API without redefining the source data.
+
+## Language
+
+**Understat resource**:
+A top-level published data subject: a League, Team, Player, or Match.
+_Avoid_: endpoint, entity
+
+**Competition season**:
+The campaign beginning in a given calendar year and ending in the next, represented publicly as `YYYY/YYYY+1`.
+_Avoid_: year, calendar year
+
+**Resource snapshot**:
+The complete set of data Understat returns for one resource query.
+_Avoid_: table, endpoint response
+
+**Team handle**:
+The exact URL-safe name Understat assigns to a Team, such as `Manchester_United`.
+_Avoid_: team name, slug
+
+**Understat ID**:
+The positive integer that identifies a Player or Match in Understat data.
+_Avoid_: identifier, string ID

py_understat-0.1.0/LICENSE

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

py_understat-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: py-understat
+Version: 0.1.0
+Summary: An asynchronous client for Understat football statistics
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.5
+Description-Content-Type: text/markdown
+
+# py-understat
+
+An asynchronous, typed client for football statistics published by [Understat](https://understat.com/). This is an unofficial client and is not affiliated with Understat.
+
+## Install
+
+```bash
+uv add py-understat
+```
+
+From a checkout, install the package and its development tools with:
+
+```bash
+uv sync --all-groups
+```
+
+## Query data
+
+`UnderstatClient` owns its HTTP resources. Use it as an async context manager.
+
+```python
+import asyncio
+
+from py_understat import League, UnderstatClient
+
+
+async def main() -> None:
+    async with UnderstatClient() as client:
+        premier_league = await client.league(League.EPL).get("2025/2026")
+
+    top_scorer = max(premier_league.players, key=lambda player: player.goals)
+    print(top_scorer.player_name, top_scorer.goals)
+
+
+asyncio.run(main())
+```
+
+Each `get()` call returns the complete snapshot Understat supplies for that resource:
+
+```python
+async with UnderstatClient() as client:
+    league = await client.league(League.BUNDESLIGA).get("2025/2026")
+    team = await client.team("Bayern_Munich").get("2025/2026")
+    player = await client.player(8260).get()
+    match = await client.match(28778).get()
+
+league.players  # PlayerStatistic records
+league.matches  # MatchRecord records
+league.teams  # TeamSeason records keyed by Understat team ID
+team.statistics  # Typed team statistic categories
+player.matches  # PlayerMatch records
+player.shots  # Shot records
+match.rosters  # RosterEntry records grouped by home/away side
+match.shots  # Shot records grouped by home/away side
+```
+
+## Identifiers
+
+- `League` is an enum containing Understat's six supported competitions.
+- Team queries take the exact Understat team handle, such as `"Manchester_United"`.
+- Player and Match queries take a positive Understat integer ID.
+- League and Team queries take a competition season written as `"YYYY/YYYY+1"`, for example `"2025/2026"`. `Season("2025/2026")` is available when a reusable value is useful.
+
+Invalid identifiers fail locally with `InvalidIdentifierError` before making a request.
+
+## Data and failures
+
+Known fields are normalized to native Python values: IDs and counts become `int`, expected-goal values become `float`, and source timestamps become `datetime`. Models are frozen, and source fields that the package does not yet name are available through each model's read-only `extra` mapping.
+
+The client retries temporary transport failures, `429`, and `5xx` responses with bounded exponential backoff. It honors `Retry-After` up to the configured maximum delay. Catch package-level errors rather than HTTPX implementation errors:
+
+```python
+from py_understat import RateLimitError, ResourceNotFoundError, UnderstatError
+
+try:
+    async with UnderstatClient() as client:
+        snapshot = await client.player(8260).get()
+except ResourceNotFoundError:
+    print("Unknown Understat player")
+except RateLimitError:
+    print("Understat still rate-limited the request after retries")
+except UnderstatError as error:
+    print(f"Understat is unavailable: {error}")
+```
+
+The client sends an identifying user agent. It intentionally has no automatic cache or global rate limiter; callers needing either should apply them around immutable snapshots.

py_understat-0.1.0/README.md

@@ -0,0 +1,86 @@
+# py-understat
+
+An asynchronous, typed client for football statistics published by [Understat](https://understat.com/). This is an unofficial client and is not affiliated with Understat.
+
+## Install
+
+```bash
+uv add py-understat
+```
+
+From a checkout, install the package and its development tools with:
+
+```bash
+uv sync --all-groups
+```
+
+## Query data
+
+`UnderstatClient` owns its HTTP resources. Use it as an async context manager.
+
+```python
+import asyncio
+
+from py_understat import League, UnderstatClient
+
+
+async def main() -> None:
+    async with UnderstatClient() as client:
+        premier_league = await client.league(League.EPL).get("2025/2026")
+
+    top_scorer = max(premier_league.players, key=lambda player: player.goals)
+    print(top_scorer.player_name, top_scorer.goals)
+
+
+asyncio.run(main())
+```
+
+Each `get()` call returns the complete snapshot Understat supplies for that resource:
+
+```python
+async with UnderstatClient() as client:
+    league = await client.league(League.BUNDESLIGA).get("2025/2026")
+    team = await client.team("Bayern_Munich").get("2025/2026")
+    player = await client.player(8260).get()
+    match = await client.match(28778).get()
+
+league.players  # PlayerStatistic records
+league.matches  # MatchRecord records
+league.teams  # TeamSeason records keyed by Understat team ID
+team.statistics  # Typed team statistic categories
+player.matches  # PlayerMatch records
+player.shots  # Shot records
+match.rosters  # RosterEntry records grouped by home/away side
+match.shots  # Shot records grouped by home/away side
+```
+
+## Identifiers
+
+- `League` is an enum containing Understat's six supported competitions.
+- Team queries take the exact Understat team handle, such as `"Manchester_United"`.
+- Player and Match queries take a positive Understat integer ID.
+- League and Team queries take a competition season written as `"YYYY/YYYY+1"`, for example `"2025/2026"`. `Season("2025/2026")` is available when a reusable value is useful.
+
+Invalid identifiers fail locally with `InvalidIdentifierError` before making a request.
+
+## Data and failures
+
+Known fields are normalized to native Python values: IDs and counts become `int`, expected-goal values become `float`, and source timestamps become `datetime`. Models are frozen, and source fields that the package does not yet name are available through each model's read-only `extra` mapping.
+
+The client retries temporary transport failures, `429`, and `5xx` responses with bounded exponential backoff. It honors `Retry-After` up to the configured maximum delay. Catch package-level errors rather than HTTPX implementation errors:
+
+```python
+from py_understat import RateLimitError, ResourceNotFoundError, UnderstatError
+
+try:
+    async with UnderstatClient() as client:
+        snapshot = await client.player(8260).get()
+except ResourceNotFoundError:
+    print("Unknown Understat player")
+except RateLimitError:
+    print("Understat still rate-limited the request after retries")
+except UnderstatError as error:
+    print(f"Understat is unavailable: {error}")
+```
+
+The client sends an identifying user agent. It intentionally has no automatic cache or global rate limiter; callers needing either should apply them around immutable snapshots.

py_understat-0.1.0/main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from py-understat!")
+
+
+if __name__ == "__main__":
+    main()

py_understat-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "py-understat"
+version = "0.1.0"
+description = "An asynchronous client for Understat football statistics"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.3.0",
+    "pytest>=9.1.1",
+    "ruff>=0.16.5",
+    "ty>=0.0.75",
+]
+
+[build-system]
+requires = ["hatchling>=1.28.0"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

py_understat-0.1.0/src/py_understat/__init__.py

@@ -0,0 +1,36 @@
+"""An asynchronous, typed client for Understat football statistics."""
+
+from .client import League, RetryPolicy, Season, UnderstatClient
+from .exceptions import (
+    InvalidIdentifierError,
+    PayloadValidationError,
+    RateLimitError,
+    ResourceNotFoundError,
+    UnderstatError,
+    UpstreamError,
+)
+from .models import (
+    LeagueSnapshot,
+    MatchSnapshot,
+    PlayerSnapshot,
+    TeamSnapshot,
+)
+
+__all__ = [
+    "InvalidIdentifierError",
+    "League",
+    "LeagueSnapshot",
+    "MatchSnapshot",
+    "PayloadValidationError",
+    "PlayerSnapshot",
+    "RateLimitError",
+    "ResourceNotFoundError",
+    "RetryPolicy",
+    "Season",
+    "TeamSnapshot",
+    "UnderstatClient",
+    "UnderstatError",
+    "UpstreamError",
+]
+
+__version__ = "0.1.0"