universal-game-api 0.1.0__tar.gz

universal_game_api-0.1.0/.github/workflows/python-package.yml

@@ -0,0 +1,40 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python package
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest

universal_game_api-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

universal_game_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.0] — 2026-08-25
+
+### Added
+- **Lichess integration** (`lichess` slug) — player profiles and leaderboards via the public Lichess API.
+- **`compare_players(game, identifiers)`** — batch-fetch multiple players in one call (sync + async).
+- **`game_info(game)`** — introspect integration metadata (slug, auth requirements, source URL).
+- **Model helpers**:
+  - `Match.is_win`, `Match.is_loss`, `Match.is_draw`
+  - `Player.win_rate_pct()` — returns win rate as a 0–100 percentage
+  - `Leaderboard.top(n)` — slice the top N entries
+- **Live test suite** (`tests/test_live.py`) — run with `pytest -m live` to test against real APIs.
+- **Demo project** (`demo-project/`) — CLI tool and Rich dashboard built on top of `gameapi`.
+- **Examples** (`examples/`) — `basic_usage.py`, `async_usage.py`, `compare_players.py`.
+
+### Fixed
+- **HTTP base headers** — `HTTPClient` now correctly forwards `base_headers` to `httpx.Client` and `httpx.AsyncClient` (fixes missing `User-Agent` on requests).
+- **Retry-After handling** — 429 responses now respect the `Retry-After` header instead of always using exponential backoff.
+- **Missing import** — `GameAPI.__repr__` now properly imports `supported_games`.
+- **Pylance warnings** — guarded `game_data` access in tests to satisfy `reportOptionalMemberAccess`.
+
+### Changed
+- Bumped version to `0.2.0`.
+- `pyproject.toml` now includes `lichess` in keywords and classifiers.
+- `pytest.ini_options` adds a `live` marker for optional live API tests.
+
+## [0.1.0] — 2026-08-20
+
+### Added
+- Initial release with Chess.com integration.
+- Unified models: `Player`, `PlayerStats`, `Rank`, `Match`, `Leaderboard`, `LeaderboardEntry`.
+- Sync (`GameAPI`) and async (`AsyncGameAPI`) clients.
+- In-memory TTL cache (`MemoryCache`).
+- Retry logic with exponential backoff for 429/500/502/503/504.
+- Exception hierarchy: `GameAPIError`, `PlayerNotFoundError`, `RateLimitError`, etc.

universal_game_api-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing to gameapi
+
+Thanks for considering a contribution! The most common contribution is a
+new game integration, so that's covered in detail below.
+
+## Development setup
+
+```bash
+git clone https://github.com/F0xyN0xy/universal-game-api
+cd gameapi
+pip install -e ".[dev]"
+pytest
+```
+
+## Adding a new game integration
+
+1. **Confirm there's a legitimate public data source.** Only integrate APIs
+   that developers are permitted to access under their terms of service —
+   don't scrape sites in ways that violate their terms, and don't bypass
+   auth, rate limits, or anti-bot systems. If a game doesn't have a
+   suitable public API, don't add a fake/partial integration for it.
+
+2. **Create a new module** under `src/gameapi/games/<your_game>/`:
+
+   ```text
+   games/
+   └── your_game/
+       ├── __init__.py
+       ├── client.py      # subclasses GameIntegration
+       ├── models.py       # game-specific dataclasses (exposed via game_data)
+       └── endpoints.py     # URL builders
+   ```
+
+   Use `games/chess_com/` as the reference implementation.
+
+3. **Subclass `GameIntegration`** (`gameapi.games.base.GameIntegration`) and
+   implement at minimum `get_player` and `get_player_async`. Implement
+   `get_matches`/`get_matches_async` and `get_leaderboard`/
+   `get_leaderboard_async` only if the underlying API actually supports
+   them — the base class already raises a clear `NotImplementedError`
+   otherwise.
+
+   All HTTP calls should go through `self.http` (a shared `HTTPClient`) —
+   never call `httpx`/`requests` directly from a game integration. This
+   keeps retries, timeouts, and error translation consistent everywhere.
+
+4. **Map the game's data onto the unified models** (`Player`, `PlayerStats`,
+   `Rank`, `Match`, `Leaderboard`) wherever a field genuinely corresponds.
+   Don't force a field that doesn't generalize — put it on `game_data`
+   instead (a dataclass you define in your integration's `models.py`).
+
+5. **Register your integration** in `src/gameapi/games/registry.py`:
+
+   ```python
+   from .your_game.client import YourGameIntegration
+
+   GAME_REGISTRY["your_game"] = YourGameIntegration
+   ```
+
+6. **Translate errors.** Catch the upstream API's "not found" signal (often
+   an HTTP 404) and re-raise it as `PlayerNotFoundError(self.slug, identifier)`
+   with useful context. Let other `GameAPIError` subclasses raised by the
+   shared `HTTPClient` propagate as-is.
+
+7. **Write tests** in `tests/test_your_game.py` using `respx` to mock HTTP
+   responses — don't depend on the live API in the standard test suite.
+   See `tests/test_chess_com.py` for the pattern. If you want, add a
+   separate integration test (clearly marked) that hits the real API.
+
+8. **Document it** — add a row to the "Supported games" table in
+   `README.md`, including the data source, whether auth is required, and
+   a link to the upstream API's documentation.
+
+## Code style
+
+- Type hints on all public functions/methods.
+- Docstrings on all public classes and methods (Google style, as used
+  throughout the codebase).
+- Run `ruff check .` and `mypy src/` before submitting.
+
+## Pull requests
+
+- Keep PRs focused — one game integration or one fix per PR.
+- Include tests for anything you add or change.
+- Update `CHANGELOG.md` under an "Unreleased" heading.

universal_game_api-0.1.0/LICENSE

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

universal_game_api-0.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.5
+Name: universal-game-api
+Version: 0.1.0
+Summary: A unified, developer-friendly Python interface for public game data and statistics.
+Project-URL: Homepage, https://github.com/F0xyN0xy/universal-game-api
+Project-URL: Documentation, https://github.com/F0xyN0xy/universal-game-api#readme
+Project-URL: Issues, https://github.com/F0xyN0xy/universal-game-api/issues
+Project-URL: Changelog, https://github.com/F0xyN0xy/universal-game-api/blob/main/CHANGELOG.md
+Author-email: F0xyN0xy <foxynoxy07@proton.me>
+License: MIT License
+        
+        Copyright (c) 2026 F0xyN0xy
+        
+        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.
+License-File: LICENSE
+Keywords: api,chess,games,gaming,lichess,python,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.25
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Universal Game API (`gameapi`)
+
+> One interface. Every game. No API archaeology.
+
+`gameapi` is a Python library that unifies public game APIs behind a single, consistent interface. Instead of learning a new client for every game, you write the same code for Chess.com, Lichess, and whatever comes next.
+
+```python
+from gameapi import GameAPI
+
+with GameAPI() as api:
+    player = api.player(game="chess_com", identifier="hikaru")
+    print(player.name, player.rank.rating)   # hikaru 2800
+```
+
+---
+
+## Why
+
+Every game API looks different:
+
+```python
+# Without gameapi
+chess_client.get_profile(...)
+rl_client.fetch_stats(...)
+mc_client.player_lookup(...)
+```
+
+`gameapi` gives you one shape instead:
+
+```python
+# With gameapi
+api.player(game="chess_com", identifier="...")
+api.player(game="lichess", identifier="...")
+api.player(game="rocket_league", identifier="...")  # once implemented
+```
+
+Common fields (`name`, `stats`, `rank`) are normalized. Anything that doesn't generalize lives on `player.game_data`.
+
+---
+
+## Supported Games
+
+| Game      | Slug        | Auth Required | Data Source                          |
+|-----------|-------------|---------------|--------------------------------------|
+| Chess.com | `chess_com` | No            | Chess.com Published-Data API         |
+| Lichess   | `lichess`   | No            | Lichess Public API                   |
+
+```python
+from gameapi import supported_games
+print(supported_games())  # ['chess_com', 'lichess']
+```
+
+---
+
+## Installation
+
+```bash
+pip install gameapi
+```
+
+Requires Python 3.9+.
+
+### Development
+
+```bash
+git clone https://github.com/F0xyN0xy/universal-game-api.git
+cd universal-game-api
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## Quick Start
+
+### Player Profile
+
+```python
+from gameapi import GameAPI
+
+with GameAPI() as api:
+    player = api.player(game="chess_com", identifier="hikaru")
+    print(player.name)           # hikaru
+    print(player.rank.tier)      # GM
+    print(player.rank.rating)    # 2800
+    print(player.stats)          # PlayerStats(games_played=..., wins=...)
+```
+
+### Recent Matches
+
+```python
+for match in api.matches(game="chess_com", identifier="hikaru", limit=10):
+    print(match.result, match.opponent, match.played_at)
+```
+
+### Leaderboard
+
+```python
+board = api.leaderboard(game="chess_com")
+for entry in board.top(5):
+    print(entry.position, entry.name, entry.rating)
+```
+
+### Batch Lookups
+
+```python
+players = api.compare_players("chess_com", ["hikaru", "magnuscarlsen", "nihalsarin"])
+for p in players:
+    print(p.name, p.rank.rating)
+```
+
+### Async
+
+```python
+import asyncio
+from gameapi import AsyncGameAPI
+
+async def main():
+    async with AsyncGameAPI() as api:
+        player = await api.player(game="lichess", identifier="drnykterstein")
+        print(player.name)
+
+asyncio.run(main())
+```
+
+---
+
+## Caching
+
+Optional in-process caching reduces redundant requests:
+
+```python
+api = GameAPI(cache=True, cache_ttl=60)  # seconds
+```
+
+Nothing sensitive is ever cached — only parsed response data.
+
+---
+
+## Rate Limits & Retries
+
+`gameapi` retries transient failures (HTTP 429/500/502/503/504) with exponential backoff, then raises typed exceptions:
+
+```python
+from gameapi import RateLimitError
+
+try:
+    player = api.player(game="chess_com", identifier="hikaru")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+```
+
+429 responses respect the upstream `Retry-After` header when provided.
+
+---
+
+## Error Handling
+
+All exceptions inherit from `GameAPIError`:
+
+```python
+from gameapi import (
+    GameAPIError,
+    GameNotSupportedError,
+    PlayerNotFoundError,
+    AuthenticationError,
+    RateLimitError,
+    APIUnavailableError,
+    InvalidResponseError,
+)
+```
+
+---
+
+## API Reference
+
+### `GameAPI(api_key=None, cache=False, cache_ttl=60.0, timeout=10.0, max_retries=2)`
+
+| Method | Returns |
+|--------|---------|
+| `player(game, identifier)` | `Player` |
+| `matches(game, identifier, limit=20)` | `list[Match]` |
+| `leaderboard(game, region=None)` | `Leaderboard` |
+| `compare_players(game, identifiers)` | `list[Player]` |
+| `game_info(game)` | `dict` |
+| `close()` | — |
+
+Context-manager compatible: `with GameAPI() as api:`
+
+`AsyncGameAPI` has identical signatures, `await`-ed.
+
+### Models
+
+- `Player` — `name`, `game`, `identifier`, `stats`, `rank`, `game_data`, `avatar_url`
+- `PlayerStats` — `games_played`, `wins`, `losses`, `draws`, `win_rate`
+- `Rank` — `tier`, `rating`, `position`, `raw`
+- `Match` — `id`, `game`, `played_at`, `result`, `opponent`, `game_data`
+- `Leaderboard` / `LeaderboardEntry` — `position`, `name`, `rating`
+
+Every model is a `@dataclass`, so `dataclasses.asdict(player)` works out of the box.
+
+---
+
+## Demo Project
+
+A small CLI and dashboard built on `gameapi` lives in `demo-project/`:
+
+```bash
+cd demo-project
+pip install -e "."
+
+# Look up a player
+python -m demo_project chess_com hikaru -m 5 -l
+
+# Compare two players side-by-side
+python src/demo_project/dashboard.py chess_com hikaru magnuscarlsen
+```
+
+---
+
+## Contributing
+
+See `CONTRIBUTING.md` for how to add a new game integration. The pattern is:
+
+1. Create `src/gameapi/games/<game>/`
+2. Subclass `GameIntegration`
+3. Register it in `games/registry.py`
+
+No changes to `client.py` or `async_client.py` are needed.
+
+---
+
+## License
+
+MIT
+
+## Legal
+
+`gameapi` only integrates with public APIs that permit this kind of access under their terms of service. It does not scrape websites in ways that violate their terms, and does not attempt to bypass authentication, rate limits, or anti-bot protections.