retrosheetpy

Fast, strongly-typed Retrosheet baseball data downloader, parser, and database ingestor.

---

retrosheetpy brings modern, typed data workflows to Retrosheet baseball archives. It enables baseball researchers, analysts, professors, and DBAs to download, parse, and ingest play-by-play events, historical game logs, rosters, schedules, and biographical encyclopedias directly into DuckDB, Parquet, Polars, pandas, and cloud SQL warehouses with strongly-typed schemas (integers, dates, booleans—never raw text dumps).

Powered by chadwickpy for multi-core play-by-play parsing with zero C compiler dependencies.

---

Key Features

• Zero C Compiler Required: 100% pure Python / PyArrow / DuckDB, installable on Windows, macOS, and Linux in seconds.
• Strongly Typed Schemas: Dates are parsed to DATE, counts and scores to INTEGER, flags to BOOLEAN—ready for instant SQL queries without manual casting.
• Complete Retrosheet Catalog:
  • Events (Play-by-play, 164 columns via chadwickpy)
  • Postseason & All-Star Games (World Series, LCS, LDS, All-Star play-by-play)
  • Game Logs (1871–present, 161 columns)
  • Official Schedules (1877–present, 13 columns)
  • Biographical Encyclopedia (biofile0.csv, 32 columns)
  • Team Rosters (.ROS player records, handedness, teams)
  • Ballparks (parkcode.txt, history, dates, coordinates)
  • Transactions & Ejections (tran.txt, ejections.csv)
• Compact CLI: Compact flags (-s, -y, -d, -c, -f, -o) for downloading, ingesting, exporting, and generating DDL.
• Cloud Warehouses via dlt: Stream directly into PostgreSQL, Snowflake, BigQuery, ClickHouse, or Databricks via optional dlt.
• LLM Context Ready: Includes llms.txt and llms-full.txt conforming to the llmstxt.org specification for AI agents.

---

Installation

# Core library (DuckDB, PyArrow, Polars, pandas, Parquet)
pip install retrosheetpy

# With cloud warehouse connectors (PostgreSQL, Snowflake, BigQuery)
pip install "retrosheetpy[dlt]"

---

Quickstart

Python API

import retrosheetpy as rs

# 1. Download & inspect 2024 MLB play-by-play events
events = rs.events(year=2024, backend="polars")
print(events.select(["GAME_ID", "BAT_ID", "PIT_ID", "EVENT_TX"]))

# 2. Historical Game Logs (1871-present)
gamelogs = rs.game_logs(year=range(2020, 2025), backend="polars")

# 3. Ballpark Directory & Rosters
parks = rs.parks(backend="arrow")
rosters_2024 = rs.rosters(year=2024, backend="polars")

# 4. Schedules, Biofile, Ejections, Transactions
schedules = rs.schedules(year=2024, backend="polars")
bio = rs.bio(backend="polars")
ejections = rs.ejections(backend="polars")
transactions = rs.transactions(backend="polars")

# 5. Ingest decades directly into DuckDB
rs.to_duckdb(
    path="retrosheet.duckdb",
    years=range(2000, 2025),
    datasets=["events", "gamelogs", "rosters", "parks", "schedules", "bio"],
)

# 6. Stream into PostgreSQL via dlt
rs.to_dlt(
    destination="postgres",
    years=[2024],
    datasets=["events", "gamelogs", "rosters", "parks"],
    credentials="postgresql://user:pass@localhost:5432/retrosheet",
)

Command-Line Interface (CLI)

# Download and cache all 2024 assets locally
retrosheetpy download -s all -y 2024

# Ingest into local DuckDB
retrosheetpy ingest -d duckdb -c retro.duckdb -s events,gamelogs -y 2020-2024

# Ingest into PostgreSQL warehouse
retrosheetpy ingest -d postgres -c "postgresql://user:pass@localhost:5432/retrosheet" -s all -y 2024

# Export specific dataset to Parquet
retrosheetpy export -s gamelogs -y 2024 -f parquet -o gamelogs_2024.parquet

# Generate production SQL DDL
retrosheetpy ddl -s events --dialect postgres
retrosheetpy ddl -s schedules --dialect bigquery

---

Documentation & LLM Resources

• Interactive Documentation: https://cbwinslow.github.io/retrosheetpy/
• LLM Summary Index: https://cbwinslow.github.io/retrosheetpy/llms.txt
• Full LLM Context: https://cbwinslow.github.io/retrosheetpy/llms-full.txt
• Robots.txt: https://cbwinslow.github.io/retrosheetpy/robots.txt
• Sitemap: https://cbwinslow.github.io/retrosheetpy/sitemap.xml

---

License & Attribution

retrosheetpy is licensed under GPL-3.0-or-later.

The information used in this project is obtained free of charge from and is copyrighted by Retrosheet. Interested parties may contact Retrosheet at www.retrosheet.org.