overfast-client 0.1.0__tar.gz

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

@@ -0,0 +1,58 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  # Allow manual runs (e.g. re-publishing the same tag after a build-only fix).
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    # The environment name must match what you configure on PyPI under
+    # "Manage → Publishing → Trusted publishers".
+    environment:
+      name: pypi
+      url: https://pypi.org/project/overfast-client/
+    permissions:
+      # Required for OIDC token exchange with PyPI.
+      id-token: write
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

overfast_client-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v

overfast_client-0.1.0/.gitignore

@@ -0,0 +1,83 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.env.*
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs / editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# mypy / ruff / pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+.pyright/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Project-local scratch
+openapi_tmp.json
+*.zip

overfast_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-14
+
+### Added
+- Initial release.
+- Async client for the [OverFast API](https://overfast-api.tekrop.fr/) built on `httpx`.
+- Services: `HeroesService`, `MapsService`, `GamemodesService`, `RolesService`, `PlayersService`.
+- Pydantic v2 models for heroes, maps, gamemodes, roles, and player data (summary, stats, career, search).
+- Enums synchronized with the OverFast API schema: `Hero`, `Role`, `Region`, `Platform`, `Rank`, `CompetitiveDivisionFilter`, `HeroGamemode`, `PlayerGamemode`, `Privacy`, `BackgroundImageSize`, `CareerStatCategory`.
+- HTTP-layer caching via [hishel](https://hishel.com) (memory / sqlite / file backends), opt-in through `ClientConfig.cache`.
+- Automatic retries for transient failures via `httpx-retries`.
+- Typed exceptions mapped to OverFast API responses: `BadRequestError` (400), `NotFoundError` (404), `ValidationError` (422), `RateLimitError` (429), `InternalServerError` (500), `ServiceUnavailableError` (503), `ParserBlizzardError` (504).
+- `py.typed` marker for PEP 561 type-checker support.
+
+[Unreleased]: https://github.com/Leo890728/overwatch_py/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Leo890728/overwatch_py/releases/tag/v0.1.0

overfast_client-0.1.0/LICENSE

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

overfast_client-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: overfast-client
+Version: 0.1.0
+Summary: Async Python client for the OverFast API (Overwatch data).
+Project-URL: Homepage, https://github.com/Leo890728/overwatch_py
+Project-URL: Repository, https://github.com/Leo890728/overwatch_py
+Project-URL: Issues, https://github.com/Leo890728/overwatch_py/issues
+Project-URL: Changelog, https://github.com/Leo890728/overwatch_py/blob/main/CHANGELOG.md
+Author-email: Leo890728 <Leo890728@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,async,httpx,overfast,overwatch,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: hishel<0.2,>=0.0.30
+Requires-Dist: httpx-retries>=0.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# overfast-client
+
+Async Python client for the [OverFast API](https://overfast-api.tekrop.fr) — comprehensive Overwatch data (heroes, maps, gamemodes, player stats) via a typed, pydantic-backed interface.
+
+## Install
+
+```bash
+pip install overfast-client
+```
+
+> The PyPI distribution is `overfast-client`; the import name is `overwatch_py`.
+
+Or from source (editable):
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+import asyncio
+from overwatch_py import Client
+from overwatch_py.enums import Hero, Locale, Role, HeroGamemode, PlayerGamemode, Platform
+
+async def main():
+    client = Client()
+
+    # List heroes
+    heroes = await client.get_heroes(role=Role.SUPPORT, locale=Locale.EN_US)
+    for h in heroes:
+        print(h.key, h.name)
+
+    # Full hero data (abilities, story, hitpoints, ...)
+    ana = await client.get_hero_data(Hero.ANA)
+    print(ana.hitpoints, len(ana.abilities))
+
+    # Maps & gamemodes
+    maps = await client.get_maps()
+    gamemodes = await client.get_gamemode_details()
+
+    # Hero usage stats (pickrate / winrate)
+    stats = await client.get_heroes_stats(
+        platform=Platform.PC,
+        gamemode=PlayerGamemode.COMPETITIVE,
+    )
+
+    # Players
+    result = await client.search_players("TeKrop", limit=10)
+    player = await client.get_player(result.results[0].player_id)
+    summary = await client.get_player_summary("TeKrop-2217")
+    stats_summary = await client.get_player_stats("TeKrop-2217", gamemode=PlayerGamemode.COMPETITIVE)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+from overwatch_py import Client
+from overwatch_py.config import Config
+from overwatch_py.session import HTTPSession
+
+config = Config(
+    timeout=10,          # seconds
+    retries=3,           # retries on 5xx
+    cache=True,          # HTTP-level cache (hishel), respects server Cache-Control
+    cache_backend="sqlite",  # "memory" | "sqlite" | "file"
+)
+client = Client(HTTPSession(config))
+```
+
+### Caching
+
+Caching is disabled by default. When enabled, [hishel](https://hishel.com) sits in the httpx transport stack and honors each endpoint's `Cache-Control` / `Age` headers (e.g. `/heroes` is cached ~1 day, `/heroes/stats` ~1 hour by the upstream API).
+
+## Exceptions
+
+All non-2xx responses map to subclasses of `APIError`:
+
+| Status | Exception |
+|--------|-----------|
+| 400    | `BadRequestError` |
+| 404    | `NotFoundError` |
+| 422    | `ValidationError` |
+| 429    | `APIRateLimitError` |
+| 500    | `InternalServerError` |
+| 503    | `BlizzardRateLimitError` |
+| 504    | `BlizzardServerError` |
+
+```python
+from overwatch_py.exceptions import NotFoundError, APIRateLimitError
+
+try:
+    await client.get_player_summary("does-not-exist-1234")
+except NotFoundError:
+    ...
+except APIRateLimitError as e:
+    print("rate limited:", e.response.headers.get("retry-after"))
+```
+
+## API surface
+
+Exposed on `Client`:
+
+- **Heroes** — `get_heroes`, `get_hero_data`, `get_heroes_stats`
+- **Maps / Gamemodes** — `get_maps`, `get_gamemode_details`
+- **Players** — `search_players`, `get_player`, `get_player_summary`, `get_player_stats`, `get_player_career_stats`, `get_player_career_stats_with_labels`, `get_player_full_stats`
+
+The underlying services (`client.heros`, `client.maps`, `client.players`) are also available if you prefer service-level access.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                     # unit + mocked HTTP tests
+pytest -m live             # hits the real API (rate-limited)
+pytest -m 'live or not live'  # run everything
+```
+
+## License
+
+MIT.

overfast_client-0.1.0/README.md

@@ -0,0 +1,123 @@
+# overfast-client
+
+Async Python client for the [OverFast API](https://overfast-api.tekrop.fr) — comprehensive Overwatch data (heroes, maps, gamemodes, player stats) via a typed, pydantic-backed interface.
+
+## Install
+
+```bash
+pip install overfast-client
+```
+
+> The PyPI distribution is `overfast-client`; the import name is `overwatch_py`.
+
+Or from source (editable):
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+import asyncio
+from overwatch_py import Client
+from overwatch_py.enums import Hero, Locale, Role, HeroGamemode, PlayerGamemode, Platform
+
+async def main():
+    client = Client()
+
+    # List heroes
+    heroes = await client.get_heroes(role=Role.SUPPORT, locale=Locale.EN_US)
+    for h in heroes:
+        print(h.key, h.name)
+
+    # Full hero data (abilities, story, hitpoints, ...)
+    ana = await client.get_hero_data(Hero.ANA)
+    print(ana.hitpoints, len(ana.abilities))
+
+    # Maps & gamemodes
+    maps = await client.get_maps()
+    gamemodes = await client.get_gamemode_details()
+
+    # Hero usage stats (pickrate / winrate)
+    stats = await client.get_heroes_stats(
+        platform=Platform.PC,
+        gamemode=PlayerGamemode.COMPETITIVE,
+    )
+
+    # Players
+    result = await client.search_players("TeKrop", limit=10)
+    player = await client.get_player(result.results[0].player_id)
+    summary = await client.get_player_summary("TeKrop-2217")
+    stats_summary = await client.get_player_stats("TeKrop-2217", gamemode=PlayerGamemode.COMPETITIVE)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+from overwatch_py import Client
+from overwatch_py.config import Config
+from overwatch_py.session import HTTPSession
+
+config = Config(
+    timeout=10,          # seconds
+    retries=3,           # retries on 5xx
+    cache=True,          # HTTP-level cache (hishel), respects server Cache-Control
+    cache_backend="sqlite",  # "memory" | "sqlite" | "file"
+)
+client = Client(HTTPSession(config))
+```
+
+### Caching
+
+Caching is disabled by default. When enabled, [hishel](https://hishel.com) sits in the httpx transport stack and honors each endpoint's `Cache-Control` / `Age` headers (e.g. `/heroes` is cached ~1 day, `/heroes/stats` ~1 hour by the upstream API).
+
+## Exceptions
+
+All non-2xx responses map to subclasses of `APIError`:
+
+| Status | Exception |
+|--------|-----------|
+| 400    | `BadRequestError` |
+| 404    | `NotFoundError` |
+| 422    | `ValidationError` |
+| 429    | `APIRateLimitError` |
+| 500    | `InternalServerError` |
+| 503    | `BlizzardRateLimitError` |
+| 504    | `BlizzardServerError` |
+
+```python
+from overwatch_py.exceptions import NotFoundError, APIRateLimitError
+
+try:
+    await client.get_player_summary("does-not-exist-1234")
+except NotFoundError:
+    ...
+except APIRateLimitError as e:
+    print("rate limited:", e.response.headers.get("retry-after"))
+```
+
+## API surface
+
+Exposed on `Client`:
+
+- **Heroes** — `get_heroes`, `get_hero_data`, `get_heroes_stats`
+- **Maps / Gamemodes** — `get_maps`, `get_gamemode_details`
+- **Players** — `search_players`, `get_player`, `get_player_summary`, `get_player_stats`, `get_player_career_stats`, `get_player_career_stats_with_labels`, `get_player_full_stats`
+
+The underlying services (`client.heros`, `client.maps`, `client.players`) are also available if you prefer service-level access.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                     # unit + mocked HTTP tests
+pytest -m live             # hits the real API (rate-limited)
+pytest -m 'live or not live'  # run everything
+```
+
+## License
+
+MIT.

overfast_client-0.1.0/overwatch_py/__init__.py

@@ -0,0 +1,4 @@
+from .client import Client
+
+__version__ = "0.1.0"
+__all__ = ["Client", "__version__"]

overfast_client-0.1.0/overwatch_py/client.py

@@ -0,0 +1,96 @@
+from typing import Optional
+
+from .services import HerosService, MapsService, PlayersService
+from .services.players import HeroFilter
+from .session import HTTPSession
+from .models import (
+    GamemodeDetails,
+    HeroData,
+    HeroPlayerCareerStats,
+    HeroShort,
+    HeroStats,
+    MapDetails,
+    Player,
+    PlayerSearchResult,
+    PlayerStats,
+    PlayerStatsSummary,
+    PlayerSummary,
+)
+from .enums import (
+    CompetitiveDivisionFilter,
+    Hero,
+    HeroGamemode,
+    Locale,
+    Map,
+    MapGamemode,
+    Platform,
+    PlayerGamemode,
+    Region,
+    Role,
+)
+
+
+class Client:
+    def __init__(self, session: HTTPSession = None):
+        self.session = session or HTTPSession()
+        self.heros = HerosService(self.session)
+        self.maps = MapsService(self.session)
+        self.players = PlayersService(self.session)
+
+    async def get_heroes(self, role: Role = None, locale: Locale = Locale.EN_US, gamemode: Optional[HeroGamemode] = None) -> list[HeroShort]:
+        """Get a list of Overwatch heroes, which can be filtered using roles or gamemodes."""
+        return await self.heros.get_heroes(role, locale, gamemode)
+
+    async def get_hero_data(self, hero: Hero, locale: Locale = Locale.EN_US) -> HeroData:
+        """Get data about an Overwatch hero : description, abilities, stadium powers, story, etc."""
+        return await self.heros.get_hero_data(hero, locale)
+
+    async def get_maps(self, map_gamemode: Optional[MapGamemode] = None) -> list[MapDetails]:
+        """Get a list of Overwatch maps : Hanamura, King's Row, Dorado, etc."""
+        return await self.maps.get_maps(map_gamemode)
+
+    async def get_gamemode_details(self) -> list[GamemodeDetails]:
+        """Get a list of Overwatch gamemodes : Assault, Escort, Flashpoint, Hybrid, etc."""
+        return await self.maps.get_gamemode_details()
+
+    async def get_heroes_stats(self, platform: Platform = Platform.PC, gamemode: PlayerGamemode = PlayerGamemode.COMPETITIVE,
+                               region: Region = Region.ASIA, role: Optional[Role] = None, map: Optional[Map] = None,
+                               competitive_division: Optional[CompetitiveDivisionFilter] = None, order_by: Optional[str] = "hero:asc") -> list[HeroStats]:
+        """Get hero statistics usage, filtered by platform, region, role, etc. Only Role Queue gamemodes are concerned."""
+        return await self.heros.get_heroes_stats(platform, gamemode, region, role, map, competitive_division, order_by)
+
+    async def search_players(self, name: str, order_by: Optional[str] = None,
+                             offset: Optional[int] = None, limit: Optional[int] = None) -> PlayerSearchResult:
+        """Search for players by BattleTag name."""
+        return await self.players.search_players(name, order_by, offset, limit)
+
+    async def get_player(self, player_id: str, gamemode: Optional[PlayerGamemode] = None,
+                         platform: Optional[Platform] = None) -> Player:
+        """Get all player data: summary and statistics."""
+        return await self.players.get_player(player_id, gamemode, platform)
+
+    async def get_player_summary(self, player_id: str) -> PlayerSummary:
+        """Get player summary: name, avatar, endorsement, competitive ranks."""
+        return await self.players.get_player_summary(player_id)
+
+    async def get_player_stats(self, player_id: str, gamemode: Optional[PlayerGamemode] = None,
+                               platform: Optional[Platform] = None) -> PlayerStatsSummary:
+        """Get player stats summary (general / roles / heroes)."""
+        return await self.players.get_player_stats(player_id, gamemode, platform)
+
+    async def get_player_career_stats(self, player_id: str, gamemode: PlayerGamemode,
+                                      platform: Optional[Platform] = None,
+                                      hero: Optional[HeroFilter] = None) -> dict[str, Optional[HeroPlayerCareerStats]]:
+        """Get player career stats as flat {label: value} maps per hero."""
+        return await self.players.get_player_career_stats(player_id, gamemode, platform, hero)
+
+    async def get_player_career_stats_with_labels(self, player_id: str, gamemode: PlayerGamemode,
+                                                  platform: Optional[Platform] = None,
+                                                  hero: Optional[HeroFilter] = None):
+        """Get player career stats with labels and categories per hero."""
+        return await self.players.get_player_career_stats_with_labels(player_id, gamemode, platform, hero)
+
+    async def get_player_full_stats(self, player_id: str, gamemode: Optional[PlayerGamemode] = None,
+                                    platform: Optional[Platform] = None) -> PlayerStats:
+        """Get a player's full per-platform stats (pc/console)."""
+        return await self.players.get_player_full_stats(player_id, gamemode, platform)

overfast_client-0.1.0/overwatch_py/config.py

@@ -0,0 +1,11 @@
+from typing import Literal
+
+from pydantic import BaseModel, HttpUrl
+
+
+class Config(BaseModel):
+    base_url: HttpUrl = "https://overfast-api.tekrop.fr"
+    timeout: int = 10
+    retries: int = 3
+    cache: bool = False
+    cache_backend: Literal["memory", "sqlite", "file"] = "memory"

overfast_client-0.1.0/overwatch_py/enums/__init__.py

@@ -0,0 +1,28 @@
+from .background_image_size import BackgroundImageSize
+from .career_stat_category import CareerStatCategory
+from .map_gamemode import MapGamemode
+from .hero import Hero
+from .locale import Locale
+from .platform import Platform
+from .region import Region
+from .role import Role
+from .map import Map
+from .gamemode import HeroGamemode, PlayerGamemode
+from .rank import Rank, CompetitiveDivisionFilter
+
+
+__all__ = [
+    "BackgroundImageSize",
+    "CareerStatCategory",
+    "CompetitiveDivisionFilter",
+    "Hero",
+    "HeroGamemode",
+    "Locale",
+    "Map",
+    "MapGamemode",
+    "Platform",
+    "PlayerGamemode",
+    "Rank",
+    "Region",
+    "Role",
+]

overfast_client-0.1.0/overwatch_py/enums/background_image_size.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+
+class BackgroundImageSize(str, Enum):
+    MIN = "min"
+    XS = "xs"
+    SM = "sm"
+    MD = "md"
+    LG = "lg"
+    XL_PLUS = "xl+"

overfast_client-0.1.0/overwatch_py/enums/career_stat_category.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class CareerStatCategory(str, Enum):
+    ASSISTS = "assists"
+    AVERAGE = "average"
+    BEST = "best"
+    COMBAT = "combat"
+    GAME = "game"
+    HERO_SPECIFIC = "hero_specific"
+    MATCH_AWARDS = "match_awards"
+    MISCELLANEOUS = "miscellaneous"

overfast_client-0.1.0/overwatch_py/enums/gamemode.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class HeroGamemode(str, Enum):
+    """Gamemodes a hero can be played in (used by /heroes filter and HeroShort.gamemodes)."""
+    QUICKPLAY = "quickplay"
+    STADIUM = "stadium"
+
+
+class PlayerGamemode(str, Enum):
+    """Gamemodes used by player-stats endpoints."""
+    QUICKPLAY = "quickplay"
+    COMPETITIVE = "competitive"