gamesheet-sdk-py 0.1.20

Unofficial Python SDK and CLI for the GameSheet Inc. platform — automates WebUI procedures where a native API is absent.

gamesheet-sdk-py

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

---

⚠️ 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.

---

Quick Links

• Documentation — Full documentation (tutorials, how-tos, API reference)
• Installation — Get started quickly
• Quick Start — First commands to try
• CLI Reference — Command-line usage
• Configuration — Environment variables and settings
• Development Setup — Contributing guide
• Release Process — Automated releases with Conventional Commits
• CHANGELOG — Release history

---

Features

• Authentication — Browser-driven login flow with persistent session storage
• Resource-oriented CLI — associations, leagues, seasons, ipad-keys commands with intuitive aliases
• Python API — list_associations(), list_leagues(), list_seasons(), get_season(), list_ipad_keys()
• 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 mypy --strict
• Automated releases — Conventional Commits + python-semantic-release

---

Requirements

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

---

Installation

Via PyPI

pip install gamesheet-sdk-py

# Install Playwright browser (required for login)
python -m playwright install chromium

Via Docker

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

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

# Run with persistent session storage
docker run --rm -v ~/.gamesheet:/home/gamesheet/.gamesheet ghcr.io/bdperkin/gamesheet-sdk-py:latest associations list

Available Docker tags:

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

From Source

git clone https://github.com/bdperkin/gamesheet-sdk-py.git
cd gamesheet-sdk-py
pip install -e ".[all]"
python -m playwright install chromium

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

See Development Setup for detailed instructions.

---

Quick Start

CLI

# Authenticate (credentials can also come from env vars)
gamesheet-sdk-py login --email [e-mail]

# List associations
gamesheet-sdk-py associations list --format json

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

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

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

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

See the CLI Reference for complete usage.

Python API

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

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 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}")

---

Configuration

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

export GAMESHEET_USERNAME=[e-mail]
export GAMESHEET_PASSWORD=secret
export GAMESHEET_TIMEOUT=60

gamesheet-sdk-py login

---

Documentation

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

The docs follow the Diátaxis framework:

• Tutorials — Step-by-step learning guides
• How-To Guides — Task-oriented recipes
• Reference — API and CLI documentation
• Explanation — Understanding the architecture

---

Project Status

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

• Version strategy: Patch-only bumps until 1.0.0 (see Release Process)
• Test coverage: 100% (enforced via Codecov)
• Type checking: mypy --strict passes
• Complexity: All blocks at cyclomatic complexity grade A (cc ≤ 5)

---

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.

---

Security

To report a vulnerability, see SECURITY.md. Please use the private reporting channel — do not open public issues for security reports.

---

License

Distributed under the MIT License. © 2026 bdperkin.

---

Links

• PyPI: https://pypi.org/project/gamesheet-sdk-py/
• Documentation: https://bdperkin.github.io/gamesheet-sdk-py/
• Source: https://github.com/bdperkin/gamesheet-sdk-py
• Issues: https://github.com/bdperkin/gamesheet-sdk-py/issues
• Changelog: CHANGELOG.md
• Releases: https://github.com/bdperkin/gamesheet-sdk-py/releases