slapshot

Purpose

slapshot is a synchronous and asynchronous client for the unofficial NHL API. It covers the four public NHL services behind a single, typed interface: api-web.nhle.com, api.nhle.com/stats/rest, records.nhl.com, and the player search at search.d3.nhle.com.

Why slapshot?

The NHL exposes a large, undocumented surface of endpoints spread across several hosts, each with its own path conventions, query parameters, and payload shapes. slapshot wraps them behind one typed interface, so the caller works with the data rather than with URL construction and response parsing.

Stable payloads decode into msgspec structs with snake_case attributes, while volatile payloads come back as decoded JSON. Decoding ignores unknown fields, so new NHL fields never break existing code. Every URL template lives in an enum, so no path is ever built from a loose string.

How It Works

slapshot has four layers:

• Client (NHL, AsyncNHL): owns the httpx transport and exposes one attribute per resource.
• Resources (client.standings, client.players, ...): group related endpoints into methods.
• Request builders (slapshot.resources.*): validate arguments and produce a Request of URL and query parameters.
• Endpoints (WebEndpoint, StatsEndpoint, RecordsEndpoint, SearchEndpoint): hold every URL template as a StrEnum.

The synchronous NHL and asynchronous AsyncNHL clients expose the same resources and the same method names. AsyncNHL mirrors NHL; its methods are awaitable.

Core Features

• Synchronous and Asynchronous: an identical API on NHL and AsyncNHL, chosen per call site.
• Typed Models: stable payloads decode into msgspec structs; volatile payloads return raw JSON.
• Forward Compatible: decoding ignores unknown response fields, so new NHL fields never break existing code.
• No Loose Paths: every endpoint is a StrEnum template, and slapshot validates identifiers, seasons, and dates before it sends a request.
• Bring Your Own Transport: inject a preconfigured httpx client for proxies, retries, or custom headers.
• Typed Errors: a single NHLError hierarchy covers transport, HTTP status, decode, and parameter failures.

Backing APIs

Installation

Prerequisites

• Python 3.11 or newer
• uv (recommended) or pip

From PyPI

uv add slapshot

Or with pip:

pip install slapshot

From Source

git clone https://github.com/braycarlson/slapshot
cd slapshot
uv sync

Usage

Runnable scripts for every resource live in examples/. Run one with uv run python examples/quickstart.py.

Synchronous

from slapshot import NHL, Milestone, Team


with NHL() as client:
    standings = client.standings.now()
    print(standings.standings[0].team_name.default)

    player = client.players.landing(8478402)
    print(player.first_name.default, player.last_name.default)

    skaters = client.stats.skaters(season=20252026, limit=5)
    milestone = client.records.milestone(Milestone.GOAL_CAREER_500)
    roster = client.teams.roster(Team.EDMONTON)

Asynchronous

import asyncio

from slapshot import AsyncNHL, GameType, Team


async def main() -> None:
    async with AsyncNHL() as client:
        schedule = await client.schedule.club_week(Team.EDMONTON)
        log = await client.players.game_log(8478402, season=20252026, game_type=GameType.REGULAR)
        results = await client.players.search('mcdavid', limit=3)


asyncio.run(main())

Resources

Every resource comes in both a synchronous and an asynchronous form, under the same attribute name and with the same method signatures.

Models

Stable payloads decode into msgspec structs with snake_case attributes: StandingsResponse / StandingsTeam, Roster / RosterPlayer, PlayerLanding, PlayerSearchResult, and the ResultSet envelope (data, total) shared by every stats and records report. Volatile payloads (gamecenter, play-by-play, schedules, draft, leaders, config) return decoded JSON as-is.

A LocalizedName wraps localized text; its default attribute holds the English value.

The raw payload for any endpoint remains available through the request builders:

from slapshot.resources.standings import standings_now

request = standings_now()
raw = client.get(request)

Every URL template lives in slapshot.endpoints as a StrEnum (WebEndpoint, StatsEndpoint, RecordsEndpoint, and SearchEndpoint), so no path is built from a loose string:

from slapshot import WebEndpoint, request_build

url = WebEndpoint.PLAYER_LANDING.format(player=8478402)
request = request_build(url)
raw = client.get(request)

Enums

Team, GameType, Language, Milestone, and SortDirection are StrEnum / IntEnum values accepted anywhere the corresponding string or integer is.

Errors

Every exception inherits from slapshot.NHLError.

• HTTP status: BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, RateLimitError, ServerError, or the base APIStatusError.
• Transport: NHLTimeoutError or NHLConnectionError.
• Response: UnexpectedContentTypeError for a non-JSON response, and ResponseDecodeError when a body cannot be decoded or does not match the expected model.
• Parameters: InvalidParameterError, which is also a ValueError, so existing except ValueError handlers keep working.

Detecting Unknown Fields

By default, decoding ignores fields the models do not define. To surface them instead, so nothing is silently dropped, construct a client with warn_unknown_fields=True. Any typed response whose payload carries an undefined field emits an UnknownFieldWarning naming the field paths.

from slapshot import NHL

with NHL(warn_unknown_fields=True) as client:
    client.standings.now()

The unknown_fields helper performs the same check directly, and tests/test_drift.py (marked network) runs it against the live API for every typed endpoint:

from slapshot import unknown_fields
from slapshot.models import StandingsResponse

missing = unknown_fields(raw_payload, StandingsResponse)

client.get(request) always returns the raw payload, so no data is lost regardless of the models.

Documentation

Full documentation lives in docs/, built with MkDocs. Serve it locally:

uv run --with mkdocs-material mkdocs serve

• Installation: How to install slapshot and its dependencies
• Quickstart: A first synchronous and asynchronous request
• Client: Constructing NHL and AsyncNHL, timeouts, and custom transports
• Resources: Every resource and method, with parameters and return types
• Models: The msgspec structs returned by typed endpoints
• Enums: Team, GameType, Language, Milestone, and SortDirection
• Errors: The exception hierarchy and when each error is raised
• Raw Requests: Dropping down to request builders and endpoints

Development

uv sync installs the development dependencies. Three tools check the project:

Tests marked network hit the live NHL API; pytest deselects them by default. Run them with uv run python -m pytest -m network.