cricinfo-stats 2.0.0

Python library for loading cricket statistics from ESPN Cricinfo into pandas DataFrames

cricinfo

Python library for loading cricket statistics from ESPN Cricinfo into pandas DataFrames.

• Documentation
• GitHub
• PyPI

Installation

pip install cricinfo-stats

Requires Python 3.10+.

Features

• Career batting, bowling, fielding, and all-round statistics for international cricketers.
• Partnership statistics for international cricket teams.
• Aggregated team statistics in international cricket.

Usage

from cricinfo import Cricinfo, Team, MatchFormat, StatType

# Retrieve batting stats for Pakistan in T20Is
df = Cricinfo.retrieve_stats(
    team=Team.Pakistan,
    match_format=MatchFormat.T20I,
    stat_type=StatType.BATTING,
)

# Retrieve team stats across all teams in Tests
df = Cricinfo.retrieve_stats(
    team=None,
    match_format=MatchFormat.Test,
    stat_type=StatType.TEAM,
)

Sample Output

>>> df.head()
                Player  Mat  Inns    Runs     HS   Ave    SR  100  50  ...
0       Babar Azam (PK)   99   93    3485  122*  46.46  129.0  9  26  ...
1  Mohammad Rizwan (PK)   72   65    2088   88*  38.66  126.0  0  19  ...

Error Handling

retrieve_stats may raise:

• requests.HTTPError if ESPN Cricinfo is unreachable or returns an error.
• ValueError if the response HTML cannot be parsed.

Supported Teams

Enum Value	Team
Team.England	England
Team.Australia	Australia
Team.SouthAfrica	South Africa
Team.WestIndies	West Indies
Team.NewZealand	New Zealand
Team.India	India
Team.Pakistan	Pakistan
Team.SriLanka	Sri Lanka
Team.Zimbabwe	Zimbabwe
Team.Bangladesh	Bangladesh
Team.Ireland	Ireland
Team.Afghanistan	Afghanistan

Pass team=None to retrieve stats for all teams.

Supported Formats

Enum Value	Format
MatchFormat.Test	Test
MatchFormat.ODI	ODI
MatchFormat.T20I	T20I
MatchFormat.International	International (aggregated)

Stat Types

Enum Value	Description
StatType.BATTING	Career batting statistics
StatType.BOWLING	Career bowling statistics
StatType.FIELDING	Career fielding statistics
StatType.ALLROUND	Career all-round statistics
StatType.PARTNERSHIP	Partnership statistics
StatType.TEAM	Team statistics
StatType.AGGREGATE	Aggregated team statistics

Development

Testing

coverage run -m pytest -v -s
coverage report -m

Linting

ruff check .

Documentation

Documentation is hosted on Read the Docs and rebuilds automatically on every push to main (configured via .readthedocs.yaml). Sphinx pulls docstrings from source using autodoc.

To build locally:

cd docs/
make clean
make html

Packaging

Update the version in:

1. setup.py
2. docs/source/conf.py