gamesheet-sdk-py

Unofficial Python SDK and command-line interface for the GameSheet Inc. platform.

CI Tests CodeQL Docs Dependency Review pre-commit pre-commit.ci status codecov

Ruff Checked with ty pre-commit

PyPI version PyPI - Python Version PyPI - Wheel PyPI - Status PyPI - Downloads License: MIT Typed Hatch project

GitHub release GitHub stars GitHub forks GitHub issues GitHub pull requests GitHub contributors GitHub commit activity

GitHub last commit Maintenance Dependabot GitHub repo size GitHub code size

1. ⚠️ Disclaimer

This project is not affiliated with, endorsed by, or sponsored by GameSheet Inc. GameSheet Inc. does not publish a public REST/GraphQL API for the operations this SDK covers. Where a native API is absent, this library automates the GameSheet WebUI (using HTTP requests, HTML parsing, and headless-browser automation).

Because this approach depends on third-party UI structure, it may break without warning when GameSheet ships changes. Check the GitHub Releases page before upgrading in production.

Use of this software must comply with the GameSheet Inc. Terms of Service. You are responsible for any automation you perform.

2. Quick Links

3. Features

  • Authentication — Browser-driven login flow with persistent session storage
  • Resource-oriented CLI — Intuitive verb-noun command structure with aliases (ls, rm, get, etc.)
  • Comprehensive resource coverage — Manage associations, leagues, seasons, divisions, teams, games, referees, rosters (players & coaches), locations, and broadcasters
  • Python API — Fully typed Python SDK with pydantic models for all resources
  • Multiple output formats — JSON, YAML, CSV, TSV, or 13 tabulate table formats
  • Shell completion — Tab completion for bash, zsh, fish
  • Typed (PEP 561) — Ships py.typed marker, passes ty check
  • 100% test coverage — Comprehensive test suite with VCR cassettes and browser automation tests
  • Automated releases — Conventional Commits + python-semantic-release
  • Docker support — Pre-built container images with Playwright bundled

4. Requirements

  • Python 3.11+ (3.11, 3.12, 3.13, or 3.14)
  • Chromium (managed by Playwright) — required for login flow

5. Installation

5.1. Via PyPI / uv

uv add gamesheet-sdk-py

# Install Playwright browser (required for login)
uv run playwright install chromium

5.2. Via Docker

Pre-built images include Playwright (Chromium) for seamless browser automation.

# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/bdperkin/gamesheet-sdk-py:latest

# Show available CLIs
docker run --rm ghcr.io/bdperkin/gamesheet-sdk-py:latest

# Run the admin CLI
docker run --rm ghcr.io/bdperkin/gamesheet-sdk-py:latest gamesheet-admin --help

# Run with persistent session storage (recommended for multi-command workflows)
docker run --rm -v ~/.gamesheet:/home/gamesheet/.gamesheet \
  ghcr.io/bdperkin/gamesheet-sdk-py:latest gamesheet-admin associations list

# Example: login and list associations
docker run -it --rm -v ~/.gamesheet:/home/gamesheet/.gamesheet \
  -e GAMESHEET_USERNAME=you@example.com \
  -e GAMESHEET_PASSWORD=secret \
  ghcr.io/bdperkin/gamesheet-sdk-py:latest gamesheet-admin login

docker run --rm -v ~/.gamesheet:/home/gamesheet/.gamesheet \
  ghcr.io/bdperkin/gamesheet-sdk-py:latest gamesheet-admin associations list --format json

Available Docker tags:

  • latest — most recent release from main branch
  • <version> — specific version (e.g., 0.2.2, 0.2, 0)
  • <branch>-<sha> — specific commit for traceability

5.3. From Source

git clone https://github.com/bdperkin/gamesheet-sdk-py.git
cd gamesheet-sdk-py
uv sync --all-extras
uv run playwright install chromium

# Or build the Docker image locally
make docker-build
make docker-run

See Development Setup for detailed instructions.

6. Available Resources

The CLI and Python API provide comprehensive coverage of GameSheet resources:

Resource CLI Command Description
Associations associations Top-level organizational units
Leagues leagues Leagues within associations
Seasons seasons Seasons within leagues
Divisions divisions Divisions within seasons
Teams teams Teams within divisions
Games games scheduled, games completed, games brackets Scheduled, completed, and bracket games
Referees referees Referee management and reports
Roster roster players, roster coaches Season-level roster management
Team Roster teams roster players, teams roster coaches Team-level roster management
Locations locations Game locations and venues
iPad Keys ipad-keys iPad scoring access keys

Each resource supports intuitive verbs: list (or ls), get (or show/view), create (or add/new), update (or set/edit), delete (or rm/remove) where applicable. Most resources default to list when invoked without a verb (e.g., gamesheet-admin associations runs list).

7. Quick Start

7.1. CLI

# Authenticate (credentials can also come from env vars)
gamesheet-admin login --email you@example.com

# List associations
gamesheet-admin associations list --format json
# Shorthand: gamesheet-admin associations (default=list)

# List leagues in an association
gamesheet-admin leagues list 38 --format json

# List seasons in a league
gamesheet-admin seasons list 1148580 --format json

# Get season details
gamesheet-admin seasons get --season-id 15020 --format json

# Get iPad/Scoring keys
gamesheet-admin ipad-keys get 15020 --format json

# Manage divisions
gamesheet-admin divisions list --season-id 15020 --format json
gamesheet-admin divisions create --season-id 15020 --name "Bantam A" --format json

# Manage teams
gamesheet-admin teams list --division-id 123 --format json
gamesheet-admin teams create --division-id 123 --name "Hawks" --format json

# List games (scheduled, completed, brackets)
gamesheet-admin games scheduled --season-id 15020 --format json
gamesheet-admin games completed --season-id 15020 --format json
gamesheet-admin games brackets --season-id 15020 --format json

# Manage referees
gamesheet-admin referees list --season-id 15020 --format json
gamesheet-admin referees get --referee-id 456 --format json

# Manage roster (players and coaches)
gamesheet-admin roster players list --season-id 15020 --format json
gamesheet-admin roster coaches list --season-id 15020 --format json

# Tab completion setup
gamesheet-admin completion bash > ~/.gamesheet-admin-completion.bash
source ~/.gamesheet-admin-completion.bash

See the CLI Reference for complete usage.

7.2. Python API

from gamesheet_sdk import (
    AuthenticatedSession,
    Config,
    get_season,
    list_associations,
    list_divisions,
    list_ipad_keys,
    list_leagues,
    list_seasons,
    list_teams,
    load_access_token,
    load_refresh_token,
    save_tokens,
)

# Configure and authenticate
config = Config()
access = load_access_token(config)
refresh = load_refresh_token(config)

with AuthenticatedSession(
    config,
    access_token=access or "",
    refresh_token=refresh or "",
    on_refresh=lambda tokens: save_tokens(config, **tokens),
) as session:
    # List all associations
    for assoc in list_associations(session):
        print(f"Association: {assoc.title}")

        # List leagues
        for league in list_leagues(session, assoc.id):
            print(f"  League: {league.title}")

            # List seasons
            for season in list_seasons(session, league.id):
                print(f"    Season: {season.title}")

                # Get detailed season info
                detail = get_season(session, season.id)
                print(f"      Sport: {detail.sport}")

                # Get iPad keys
                keys = list_ipad_keys(session, season.id)
                for key in keys:
                    print(f"        Key: {key.value}")

                # List divisions
                divisions = list_divisions(session, season.id)
                for division in divisions:
                    print(f"      Division: {division.name}")

                    # List teams in division
                    teams = list_teams(session, division.id)
                    for team in teams:
                        print(f"        Team: {team.name}")

All functions return fully typed pydantic models with comprehensive field validation.

8. Configuration

Configuration via environment variables or CLI flags. See Configuration Reference for details.

export GAMESHEET_USERNAME=you@example.com
export GAMESHEET_PASSWORD=secret
export GAMESHEET_TIMEOUT=60

gamesheet-admin login

9. Documentation

Full documentation is available at https://bdperkin.github.io/gamesheet-sdk-py/

The docs follow the Diataxis framework:

10. Project Status

Status: Alpha — Active development, breaking changes possible before 1.0.0

  • Current version: 0.2.2
  • Python support: 3.11, 3.12, 3.13, 3.14
  • Version strategy: Patch-only bumps until 1.0.0 (see Release Process)
  • Test coverage: 100% (enforced locally and via Codecov)
  • Type checking: ty check passes on all source code
  • Code quality: All blocks maintain cyclomatic complexity grade A (cc ≤ 5)
  • CI/CD: Comprehensive test matrix across Python versions, multi-OS testing (nightly), security scanning (Semgrep, Trivy, GitGuardian, OSV-Scanner, CodeQL), and automated PyPI releases

11. Contributing

Contributions are welcome! Before opening a PR:

  1. Read Development Setup
  2. Follow Conventional Commits format
  3. Ensure tests pass: pytest --cov
  4. Run quality gates: pre-commit run --all-files
  5. Maintain 100% test coverage
  6. Keep complexity at grade A (run make metrics)

See CONTRIBUTING.md for detailed guidelines. We follow the Contributor Covenant Code of Conduct.

12. Security

Security is a top priority. This project employs multiple layers of automated security scanning:

  • Static analysis: Semgrep (SAST), CodeQL (semantic analysis)
  • Dependency scanning: OSV-Scanner, pip-audit
  • Container scanning: Trivy (with CVE suppression documented in .trivyignore.yaml, each entry carrying a rationale and an expiry date)
  • Secret detection: GitGuardian
  • Code quality: Pre-commit hooks enforce security best practices

Reporting vulnerabilities: See SECURITY.md. Please use the private reporting channel — do not open public issues for security reports.

13. License

Distributed under the MIT License. © 2026 bdperkin.

14. Support

Need help? See SUPPORT.md for:

  • Common issues and solutions
  • How to ask questions (GitHub Discussions)
  • How to report bugs (GitHub Issues)
  • Response time expectations

15. Links

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.5.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for bdperkin from gravatar.com bdperkin

Credits

Author: bdperkin

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License)

Requires

Python <3.15, >=3.11

Provides Extra

absolufy-imports add-trailing-comma architecture blank-line-after-blocks blocklint checks codespell configuration deptry detect-secrets dev docs editorconfig-checker format format-json interrogate markdown markdown-heading-numbering markdown-toc-creator mdformat pymarkdown pyproject-fmt pyroma pytest python-semantic-release quality radon ruff security semgrep ssort tools ty type-stubs types unimport validate-pyproject vulture xenon yamlfix yamllint

Tags

automation cli gamesheet hockey scraper sdk sports

Classifiers

Report project as malware

Download files

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

Source Distribution

gamesheet_sdk_py-0.4.26.tar.gz (297.4 kB view details)

Uploaded Source

Built Distribution

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

gamesheet_sdk_py-0.4.26-py3-none-any.whl (178.9 kB view details)

Uploaded Python 3

File details

Details for the file gamesheet_sdk_py-0.4.26.tar.gz.

File metadata

  • Download URL: gamesheet_sdk_py-0.4.26.tar.gz
  • Upload date:
  • Size: 297.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gamesheet_sdk_py-0.4.26.tar.gz
Algorithm Hash digest
SHA256 0709dc11f00943bcc8fbb05318bfdf0e35768c720d6a0b1dcb611bad43791a1e
MD5 987ba51a0ba07c8f8ca06f340d1e7bc9
BLAKE2b-256 cf94708a40d06a41fbdb99a312c8d832543c39ac984ccff2cbe28f08a71f7313

See more details on using hashes here.

Provenance

The following attestation bundles were made for gamesheet_sdk_py-0.4.26.tar.gz:

Publisher: release.yml on bdperkin/gamesheet-sdk-py

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

File details

Details for the file gamesheet_sdk_py-0.4.26-py3-none-any.whl.

File metadata

File hashes

Hashes for gamesheet_sdk_py-0.4.26-py3-none-any.whl
Algorithm Hash digest
SHA256 cb841ccacd545b1a9796784799eccf602830ea8dc2ff7b94431ef4e404733f44
MD5 d9fd751aa70fa593a9f655dc04198ad2
BLAKE2b-256 dc195134146380f8e8fdeeb74412349e54a3257f3489aa0f4abef3118a7d40b1

See more details on using hashes here.

Provenance

The following attestation bundles were made for gamesheet_sdk_py-0.4.26-py3-none-any.whl:

Publisher: release.yml on bdperkin/gamesheet-sdk-py

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

Release history Release notifications | RSS feed

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.38

2 files

0.4.37

2 files

0.4.36

2 files

0.4.35

2 files

0.4.34

2 files

0.4.33

2 files

0.4.32

2 files

0.4.31

2 files

0.4.30

2 files

0.4.29

2 files

0.4.28

2 files

0.4.27

2 files

This release

0.4.26 This release

2 files

0.4.25

2 files

0.4.24

2 files

0.4.23

2 files

0.4.22

2 files

0.4.21

2 files

0.4.20

2 files

0.4.19

2 files

0.4.18

2 files

0.4.17

2 files

0.4.16

2 files

0.4.15

2 files

0.4.14

2 files

0.4.13

2 files

0.4.12

2 files

0.4.11

2 files

0.4.10

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.0

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.58

2 files

0.1.57

2 files

0.1.56

2 files

0.1.55

2 files

0.1.54

2 files

0.1.53

2 files

0.1.38

2 files

0.1.37

2 files

0.1.36

2 files

0.1.35

2 files

0.1.34

2 files

0.1.33

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

Pre-release

0.0.1a1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page