Metadata-Version: 2.4
Name: openmatchkit
Version: 0.2.1
Summary: Unofficial open-source football match data toolkit using public sources.
Project-URL: Homepage, https://github.com/patilprashan246/openmatchkit
Project-URL: Repository, https://github.com/patilprashan246/openmatchkit
Project-URL: Issues, https://github.com/patilprashan246/openmatchkit/issues
Author: Prashant Patil
License: MIT License
Keywords: cli,fixtures,football,open-data,prediction,scores,soccer,world-cup
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: httpx>=0.27
Requires-Dist: lxml>=5.0
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

# openmatchkit

[![CI](https://github.com/patilprashan246/openmatchkit/actions/workflows/ci.yml/badge.svg)](https://github.com/patilprashan246/openmatchkit/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/patilprashan246/openmatchkit)](https://github.com/patilprashan246/openmatchkit/releases)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Unofficial open-source football match data toolkit for fixtures, results, best-effort live score adapters, standings, exports, and simple prediction models.

> This project is unofficial and not affiliated with FIFA, any league, club, broadcaster, federation, or data provider. It does not provide official FIFA data.

## Why openmatchkit?

openmatchkit gives Python developers a clean, source-attributed way to work with public football match facts without paid API keys. It starts with open/public datasets, keeps scraping optional and conservative, and returns structured JSON-ready models.

## Install

```bash
pip install git+https://github.com/patilprashan246/openmatchkit.git
```

For a pinned release:

```bash
pip install git+https://github.com/patilprashan246/openmatchkit.git@v0.2.1
```

For local development:

```bash
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
pytest
```

## Quick Start

```python
from openmatchkit import MatchClient

client = MatchClient()
next_match = client.next_match(competition="worldcup", season="2026")

print(next_match.model_dump(mode="json"))
```

```bash
openmatch next-match --competition worldcup --season 2026
```

## Python API

```python
from openmatchkit import MatchClient

client = MatchClient()

fixtures = client.fixtures(competition="worldcup", season="2026")
results = client.results(competition="worldcup", season="2026")
live = client.live_scores()
next_match = client.next_match(competition="worldcup", season="2026")
prediction = client.predict(home="Mexico", away="South Africa", history=results)

client.export_json(fixtures, "fixtures.json")
client.export_csv(fixtures, "fixtures.csv")
```

League datasets from OpenFootball can be fetched with codes such as:

```python
matches = client.fixtures(competition="en.1", season="2015-16")
```

## CLI

```bash
openmatch fixtures --competition worldcup --season 2026
openmatch results --competition en.1 --season 2015-16 --format csv --output results.csv
openmatch next-match --competition worldcup --season 2026
openmatch standings --competition worldcup --season 2026
openmatch predict --home Mexico --away "South Africa" --competition worldcup --season 2026
```

Detailed JSON feeds can expose richer scoreboards and player history:

```bash
openmatch scoreboards --data-file tests/fixtures/sample_detailed_source.json
openmatch scoreboard --match-id detail-1 --data-file tests/fixtures/sample_detailed_source.json
openmatch live-scoreboards --data-file tests/fixtures/sample_detailed_source.json
openmatch player-history --player "Alex Demo" --data-file tests/fixtures/sample_detailed_source.json
```

```python
from openmatchkit import MatchClient
from openmatchkit.sources.json_file import JsonFileSource

client = MatchClient(sources=[JsonFileSource("tests/fixtures/sample_detailed_source.json")])
scoreboard = client.scoreboard(match_id="detail-1")
history = client.player_history("Alex Demo")
print(scoreboard.model_dump(mode="json"))
print(history.model_dump(mode="json"))
```

## Example Output

```json
{
  "competition": "World Cup 2026",
  "home": {"name": "Canada"},
  "away": {"name": "Bosnia & Herzegovina"},
  "status": "scheduled",
  "source": "openfootball"
}
```

## Features

- Unified match, scoreboard, player history, standings, and prediction models
- OpenFootball JSON adapter
- Football-Data.co.uk CSV adapter
- Local detailed JSON adapter for authorized/public detailed feeds
- Generic optional public HTML adapter
- Safe HTTP client with robots.txt checks, caching, user agent, and per-origin delay
- Fixtures, results, next match, live score adapter interface, team info, standings
- Detailed scoreboards: clock, events, lineups, team stats, and player match stats when provided
- Player histories aggregated from player-level source data
- Simple Poisson prediction baseline and small Elo rating helper
- JSON and CSV export helpers
- Offline tests using local fixtures

## Current Status

- Stable enough for demos, research, education, and early open-source feedback
- Not official live FIFA data
- True live/player-level data requires a lawful source adapter that provides those facts
- Public roadmap: [ROADMAP.md](ROADMAP.md)
- Release notes: [CHANGELOG.md](CHANGELOG.md)

## Source and legal policy

The package code is MIT licensed. Third-party data sources have their own licenses and terms. Optional scraping adapters must respect Terms of Service, robots.txt, caching, and rate limits. Player-level data should only come from public or authorized sources and should contain public sporting facts, not private or sensitive information.

See [DATA_SOURCES.md](DATA_SOURCES.md), [PRIVACY.md](PRIVACY.md), and [CONTRIBUTING.md](CONTRIBUTING.md).

## Development

```bash
python -m pip install -e ".[dev]"
ruff check .
ruff format .
pytest
python -m build
```

The prediction output is an educational baseline only. It is not betting, financial, or professional advice.
