Metadata-Version: 2.4
Name: pypadel
Version: 0.1.0
Summary: Python SDK for Premier Padel public sports data APIs.
Project-URL: Homepage, https://github.com/Frxnesvo/pyPadel
Project-URL: Repository, https://github.com/Frxnesvo/pyPadel
Project-URL: Issues, https://github.com/Frxnesvo/pyPadel/issues
Project-URL: Documentation, https://github.com/Frxnesvo/pyPadel#readme
Project-URL: Changelog, https://github.com/Frxnesvo/pyPadel/blob/main/CHANGELOG.md
Author: Francesco Gallo
License: MIT
License-File: LICENSE
Keywords: api,padel,premier padel,sdk,sports
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<0.12,>=0.11; extra == 'dev'
Description-Content-Type: text/markdown

<h1 align="center">
  <!-- Replace with your actual logo -->
  <img src=".github/assets/logo.png" alt="Premier Padel Python SDK" width="400" />
</h1>

<h2 align="center">Python SDK for Premier Padel data APIs.</h2>

---

Access live scores, player rankings, tournament calendars, match statistics, news, media, and broadcaster data from the [Premier Padel](https://www.premierpadel.com/) APIs making them easily accessible.

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Services](#services)
- [Pagination](#pagination)
- [Error Handling](#error-handling)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)

---

## Installation

```bash
pip install pypadel
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv add pypadel
```

Requires Python 3.10+. The only runtime dependency is [httpx](https://www.python-httpx.org/).

---

## Quick Start

```python
from pypadel import PremierPadelClient, Gender, ResultsDrawType

with PremierPadelClient() as client:
    # Top-ranked male players
    rankings = client.players.list(Gender.MALE)
    print(rankings[0].full_name)

    # Full player profile
    profile = client.players.get(rankings[0].slug)

    # Tournament calendar
    tournaments = client.tournaments.list("March", 2026)

    # Live match scores
    live = client.matches.live("cancun-p2-2")
    for match in live:
        print(f"{match.team_1.player.name} vs {match.team_2.player.name}")

    # Tournament results
    results = client.tournaments.results(
        "cancun-p2-2", "2026-03-22", ResultsDrawType.WOMEN
    )
```

---

## Services

The client exposes seven resource-oriented services. Each one has its own detailed documentation:

| Service | Access | Description | Docs |
|---------|--------|-------------|------|
| **Players** | `client.players` | Rankings, search, profiles, moments | [docs/players.md](docs/players.md) |
| **Tournaments** | `client.tournaments` | Calendar, draws, entrants, results | [docs/tournaments.md](docs/tournaments.md) |
| **Matches** | `client.matches` | Live scores, upcoming, match detail | [docs/matches.md](docs/matches.md) |
| **News** | `client.news` | Article listing and detail | [docs/news.md](docs/news.md) |
| **Media** | `client.media` | Videos, reels, video page | [docs/media.md](docs/media.md) |
| **Watch** | `client.watch` | Broadcasters, where-to-watch info | [docs/watch.md](docs/watch.md) |
| **Rankings** | `client.rankings` | Convenience alias over player rankings | [docs/players.md](docs/players.md) |

> Every method that accepts a tournament, player, or match identifier is flexible: pass a model instance, an `int` ID, or a `str` slug — the SDK resolves it automatically.

---

## Pagination

Paginated endpoints return a `Page[T]` object:

```python
page = client.players.list(Gender.FEMALE)

# Iterate current page
for player in page:
    print(player.full_name)

# Check metadata
print(page.current_page, page.total_pages, page.has_next_page)

# Fetch next page
next_page = page.next_page()

# Lazy iteration across ALL pages
for player in page.iter_all():
    print(player.full_name)
```

See [docs/pagination.md](docs/pagination.md) for the full API.

---

## Error Handling

All exceptions inherit from `PremierPadelError`:

```
PremierPadelError
├── NetworkError
│   └── TimeoutError
├── HTTPStatusError
│   └── RateLimitError
├── ApiResponseError
│   └── NotFoundError
└── ValidationError
```

```python
from pypadel import (
    PremierPadelClient,
    NotFoundError,
    RateLimitError,
    NetworkError,
    PremierPadelError,
)

with PremierPadelClient() as client:
    try:
        player = client.players.get("non-existent-slug")
    except NotFoundError:
        print("Player not found")
    except RateLimitError:
        print("Rate limited — back off and retry")
    except NetworkError:
        print("Could not reach the API")
    except PremierPadelError:
        print("Something else went wrong")
```

See [docs/errors.md](docs/errors.md) for details on each exception type.

---

## Configuration

```python
from pypadel import PremierPadelClient

client = PremierPadelClient(
    lang="es",          # Response language (default: "en")
    timeout=15.0,       # Request timeout in seconds (default: 10.0)
    retries=3,          # Retry count for 5xx / timeout (default: 2)
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `lang` | `str` | `"en"` | Language code for localized responses |
| `timeout` | `float` | `10.0` | HTTP request timeout in seconds |
| `retries` | `int` | `2` | Number of retries on transient failures |
| `base_url` | `str` | Premier Padel API | Override the API base URL |
| `user_agent` | `str` | `pypadel-python/{version}` | Custom User-Agent header |
| `transport` | `httpx.BaseTransport` | `None` | Inject a custom httpx transport (useful for testing) |

---

## Architecture

```
src/pypadel/
├── client.py           # PremierPadelClient — public entrypoint
├── config.py           # ClientConfig dataclass
├── enums.py            # Gender, RankingScope, BracketDrawType, ...
├── exceptions.py       # Exception hierarchy
├── pagination.py       # Page[T] generic container
├── transport.py        # HTTP transport, retry logic, envelope parsing
├── models/             # Frozen dataclasses for every API resource
│   ├── common.py       #   Competitor, Statistic, StatisticValue
│   ├── matches.py      #   MatchCard, MatchDetail, LiveMatchDetail, ...
│   ├── players.py      #   PlayerSummary, PlayerDetail, PlayerMoment
│   ├── tournaments.py  #   Tournament, TournamentDraw, TournamentResults, ...
│   ├── news.py         #   NewsArticleSummary, NewsArticle
│   ├── media.py        #   Video, ShortReel, VideoPage, ...
│   └── watch.py        #   Broadcaster, CountryBroadcasters, WatchInfo, ...
├── parsers/            # Defensive JSON → model normalization
│   ├── common.py       #   Shared helpers (optional_str, optional_int, ...)
│   ├── matches.py
│   ├── players.py
│   ├── tournaments.py
│   ├── news.py
│   ├── media.py
│   └── watch.py
└── services/           # Resource-oriented service layer
    ├── base.py         #   BaseService with resolver helpers
    ├── matches.py
    ├── players.py
    ├── tournaments.py
    ├── news.py
    ├── media.py
    ├── rankings.py
    └── watch.py
```

The design follows a strict layered pattern:

1. **Transport** — Handles HTTP, retries, rate-limit detection, and envelope parsing
2. **Parsers** — Normalize raw JSON into typed dataclasses defensively
3. **Services** — Orchestrate transport calls, argument resolution, and caching
4. **Client** — Wires services together and manages the in-memory cache

---

## Examples

See the [`examples/`](examples/) directory for runnable scripts:

| File | Description |
|------|-------------|
| [`live_scores.py`](examples/live_scores.py) | Stream live match scores for a tournament |
| [`player_search.py`](examples/player_search.py) | Search and display player profiles |
| [`tournament_results.py`](examples/tournament_results.py) | Fetch and print tournament results |

---

## License

MIT — see [LICENSE](LICENSE) for details.

---

## Disclaimer

This is an **unofficial**, community-maintained SDK.
