pyteamtv

Python SDK for the TeamTV platform.

Quick start

pip install pyteamtv pyiceberg[s3fs] polars

Set TEAMTV_API_TOKEN in your environment or .env file.

Working with observation data (Polars)

Use get_catalog() to access observation data as a Polars DataFrame. This returns pre-materialised data — fast and filterable.

from pyteamtv import get_team
import polars as pl

team = get_team("My Team")
catalog = team.get_catalog()
df = catalog.load_table("observations").scan().to_polars()

# Filter to shots
shots = df.filter(pl.col("code") == "SHOT")

# Group by player
shots.group_by("full_name").len().sort("len", descending=True)

# Filter to a specific match
match = df.filter(pl.col("sporting_event_name") == "Team A - Team B")

# Distinguish own vs shared data
own = df.filter(pl.col("source_resource_group_id") == team.resource_group_id)
shared = df.filter(pl.col("source_resource_group_id") != team.resource_group_id)

Use with DuckDB

table = catalog.load_table("observations")
con = table.scan().to_duckdb("observations")
con.sql("SELECT code, COUNT(*) FROM observations GROUP BY code").show()

Available columns

Column	Description
`sporting_event_id`	Match UUID
`sporting_event_name`	Match name (e.g. "Team A - Team B")
`sporting_event_scheduled_at`	Scheduled time (UTC)
`observation_id`	Observation UUID
`code`	Observation type (e.g. SHOT, POSSESSION, CUSTOM)
`description`	Free-text description
`start_time`, `end_time`	Timing (seconds)
`clock_id`	Clock identifier
`team_id`, `team_name`, `team_ground`	Team context
`person_id`, `first_name`, `last_name`, `full_name`, `number`	Primary person
`attributes`	Raw observation attributes (JSON string)
`persons`	Additional persons by role (JSON string)
`source_resource_group_id`, `source_resource_group_name`	Data provenance
`enrichment`, `enrichment_version`	Computed fields (JSON string)

Examples

See pyteamtv/examples/analyze_observations.py for a complete working script.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyteamtv-0.41.1.tar.gz (50.8 kB view details)

Uploaded Apr 30, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyteamtv-0.41.1-py3-none-any.whl (61.0 kB view details)

Uploaded Apr 30, 2026 Python 3

File details

Details for the file pyteamtv-0.41.1.tar.gz.

File metadata

Download URL: pyteamtv-0.41.1.tar.gz
Upload date: Apr 30, 2026
Size: 50.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for pyteamtv-0.41.1.tar.gz
Algorithm	Hash digest
SHA256	`9a1510cd85f0b464bd5e055306f53f57337a00ec70117e1c83b6794a1d913e86`
MD5	`9fba3231e5df3fc7674f0c51b8aef115`
BLAKE2b-256	`39d6ad9526a608c5c5446ab0464a3eb5dd95f0c37d8b77a469af4112a217257f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyteamtv-0.41.1.tar.gz:

Publisher: release.yml on teamtv/pyteamtv

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pyteamtv-0.41.1.tar.gz
- Subject digest: 9a1510cd85f0b464bd5e055306f53f57337a00ec70117e1c83b6794a1d913e86
- Sigstore transparency entry: 1409751245
- Sigstore integration time: Apr 30, 2026
Source repository:
- Permalink: teamtv/pyteamtv@0b308187f2b6826bde514bf430ef34efafb046ad
- Branch / Tag: refs/heads/main
- Owner: https://github.com/teamtv
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@0b308187f2b6826bde514bf430ef34efafb046ad
- Trigger Event: workflow_dispatch