pychanga - python-based sports database manager

Pychanga (pronounced as the Chilean Spanish word) is a light-weight sports database manager written in python, using polars and parquet files. It is the db manager in golessonamores.cl, a Chilean football stats website launched in 2018. This code started as a rewritten version of this website's original code (written in php). As a python package aims to provide support for different sports and its user target are sports stats aficionados with some basic python knowledge and access to data.

Install

install it with pip: py -m pip install pychanga

Data configuration

pychanga is now data-root driven. Your app must point pychanga to a folder that contains:

• parquet/*.parquet for runtime queries
• optionally csv/*.csv if you run conversion scripts

You can configure it in two ways:

• Environment variable: PYCHANGA_DATA_DIR=/path/to/data_root
• Runtime setup:

import pychanga as pc

pc.set_data_dir("/path/to/data_root")
comp = pc.Competition("CHI-1A")

If neither is configured, pychanga will try a local .dirs file (for backwards compatibility), and then a bundled sample dataset.

Build sample dataset

To generate a minimal sample dataset from your Golessonamores data:

python dev/build_sample_dataset.py \
	--source-data-dir /path/to/golessonamores/data \
	--target-data-dir sample \
	--comp-id CHI-1A \
	--edition-id CHI-1A-1994

This creates sample/parquet/*.parquet with only:

• competition CHI-1A
• edition CHI-1A-1994
• teams that appear in those matches
• related reference tables (sports, countries, stages, sources, etc.)

Features

• It provides some classes to represent sports entities, such as: Competition, Edition, Team, Player, Match, Ground, Sport, among others.
• It provides classes to ask some common queries, such as: HeadToHead, Streaks,
• Each class provides methods to retrieve stats based on an id.
• The queries are all written in polars' DSL (domain specific language)

Example

Documentation

Collaboration