retrosheetpy

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

retrosheetpy brings modern 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, and ballparks directly into DuckDB, Parquet, Polars, pandas, and SQL databases 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.

Unified Ingestion & Querying

One API to download, parse, and stream baseball data into your favorite analytical stack:

import retrosheetpy as rs

# Ingest 2020 through 2024 into a local embedded analytical database
rs.to_duckdb(
    path="baseball.duckdb",
    years=range(2020, 2025),
    datasets=["events", "gamelogs", "rosters", "parks"],
)

import retrosheetpy as rs

# Blazing-fast play-by-play events in Polars
events_2024 = rs.events(year=2024, backend="polars")
print(events_2024.select(["GAME_ID", "BAT_ID", "PIT_ID", "EVENT_TX"]))

import retrosheetpy as rs

# 1871-present historical game logs
gl = rs.game_logs(year=2024, backend="pandas")
print(gl[["date", "visiting_team", "visiting_score", "home_team", "home_score"]].head())

import retrosheetpy as rs

# Export compressed columnar Parquet files
rs.to_parquet("gamelogs_1990_2024.parquet", dataset="gamelogs", years=range(1990, 2025))

import retrosheetpy as rs

# Stream multi-season datasets directly into PostgreSQL or Snowflake
rs.to_dlt(
    destination="postgres://postgres:postgres@localhost:5432/retrosheet",
    years=[2023, 2024],
    datasets=["rosters", "parks", "gamelogs"],
    dataset_name="public",
)

import retrosheetpy as rs

# Generate typed CREATE TABLE DDL for any dataset and database dialect
print(rs.get_ddl("events", dialect="postgres"))
print(rs.get_ddl("gamelogs", dialect="duckdb"))

Why retrosheetpy?

flowchart LR
    A["Retrosheet.org\n(HTTP Archives)"] --> B["Smart Cache\n(~/.cache/retrosheetpy)"]
    B --> C["Typed Parsers\n(chadwickpy + Arrow)"]
    C --> D1["DuckDB\n(Analytics)"]
    C --> D2["Parquet / Arrow\n(Data Lake)"]
    C --> D3["Polars / pandas\n(In-Memory)"]
    C --> D4["Postgres / Cloud\n(via dlt)"]

• Zero C Compiler Required: 100% pure Python / PyArrow wheels. Installable on Windows, macOS, and Linux in seconds with pip or uv.
• Explicit, Strongly Typed Schemas: Dates are parsed to DATE, counts and scores to INTEGER, flags to BOOLEAN. No untyped string conversions or silent failures.
• Smart Bandwidth Caching: Downloads once to ~/.cache/retrosheetpy/ with atomic writes, respecting Retrosheet server bandwidth.
• Pre-Existing Table Alignment: When ingesting into existing database tables, columns are automatically mapped by name—only matching columns are inserted.
• Complete Retrosheet Catalog: Regular season Events (play-by-play), Postseason, All-Star games, Game Logs (1871–present), Rosters, Ballparks, Schedules, Biographical encyclopedia, Ejections, and Player Transactions.

The Retrosheet Notice

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