Python SDK for Premier Padel data APIs.

---

Access live scores, player rankings, tournament calendars, match statistics, news, media, and broadcaster data from the Premier Padel APIs making them easily accessible.

---

Table of Contents

• Installation
• Quick Start
• Services
• Pagination
• Error Handling
• Configuration
• Architecture
• Examples
• Contributing
• License

---

Installation

pip install pypadel

Or with uv:

uv add pypadel

Requires Python 3.10+. The only runtime dependency is httpx.

---

Quick Start

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
Tournaments	client.tournaments	Calendar, draws, entrants, results	docs/tournaments.md
Matches	client.matches	Live scores, upcoming, match detail	docs/matches.md
News	client.news	Article listing and detail	docs/news.md
Media	client.media	Videos, reels, video page	docs/media.md
Watch	client.watch	Broadcasters, where-to-watch info	docs/watch.md
Rankings	client.rankings	Convenience alias over player rankings	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:

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 for the full API.

---

Error Handling

All exceptions inherit from PremierPadelError:

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

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 for details on each exception type.

---

Configuration

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/ directory for runnable scripts:

File	Description
live_scores.py	Stream live match scores for a tournament
player_search.py	Search and display player profiles
tournament_results.py	Fetch and print tournament results

---

License

MIT — see LICENSE for details.

---

Disclaimer

This is an unofficial, community-maintained SDK.