Metadata-Version: 2.4
Name: chess-extractor
Version: 0.2.0
Summary: FIDE rating and game data extractor
Author: Karamazov2007
License: MIT
Keywords: chess,fide,ratings,scraping,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: beautifulsoup4
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Chess Extractor

![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![Status](https://img.shields.io/badge/status-active-success)
![License](https://img.shields.io/badge/license-MIT-green)
![Data](https://img.shields.io/badge/data-FIDE-orange)
![CLI](https://img.shields.io/badge/cli-fide--games-blue)

A Python-based data extraction tool that retrieves FIDE rating history
and individual game data (available from April 2008 onwards), merging them into structured datasets
for statistical and performance analysis.

## What is this for?
This tool allows you to build structured datasets from official FIDE data, enabling:
- Player performance analysis
- Rating progression tracking
- Statistical research on chess results
## Data Coverage

Game-level data is only available from April 2008 onwards due to FIDE endpoint limitations.

Earlier periods are not available through the FIDE endpoint used for game extraction.
## Requirements
- Python 3.9+
- Internet connection (FIDE scraping)
## Limitations

- Only FIDE data available from official endpoints
- Game data starts from April 2008
- Requires internet connection
## Features

### Data extraction
- Extract complete monthly rating history from FIDE
- Retrieve all rated games for each rating period
- Detect opponent, rating, result and color (white/black)

### Data processing
- Merge game data with player rating at the time
- Filter games by date range (--date-from, --date-to)

### Interface
- Command-line interface (CLI) with positional arguments
- CLI tool: `fide-tools fetch` and `fide-tools analyze`

### Output & storage
- Export structured datasets (.tsv / .csv)
- Local caching is optional and must be explicitly enabled (`--cache`)
- Installable command-line tool (`fide-tools`) via pip


## Example output
Example extracted game dataset:
```
federation	opponent	o_rating	color	result	month	p_rating	k_chg
AZE	Mamedyarov, Shakhriyar	2760	Black	1.00	2008-04	2765	5.40
UKR	Eljanov, Pavel	2692	White	1.00	2008-04	2765	4.40
ENG	Adams, Michael	2726	Black	0.50	2008-04	2765	-0.10
ARM	Aronian, Levon	2739	White	0.50	2008-04	2765	0.10
UKR	Ivanchuk, Vassily	2751	Black	0.50	2008-04	2765	0.30
```
## Installation

```bash
pip install chess-extractor
```
### Or install locally (development mode)
```bash
pip install -e .
```
## Commands

### `fetch`

Extract FIDE rating history and game data for a player.
#### Arguments

- `id` (required)  
  FIDE player ID (numeric identifier)

#### Options

- `--date-from YYYY-MM` — Start date filter (inclusive)
- `--date-to YYYY-MM` — End date filter (inclusive)
- `--cache` — Enable local caching of FIDE requests
- `--export FILE` — Export results to a TSV file

#### Syntax

```bash
fide-tools fetch <id> [--date-from YYYY-MM] [--date-to YYYY-MM] [--cache] [--export FILE]
```
## Examples
### Basic

```bash
fide-tools fetch 1503014
```
### Advanced
```bash
fide-tools fetch 1503014 --date-from 2018-01 --date-to 2025-12 --export Carlsen.tsv --cache
```
Download sample dataset:
[Carlsen.tsv](./Carlsen.tsv)

---
### `analyze`

Analyze extracted FIDE game dataset.

#### Options

- `--id FIDE_ID` — Fetch and analyze directly from FIDE
    - `--performance` — Compute FIDE performance rating
    - `--elo-change` — Compare expected rating impact (FIDE K-factor sum) vs observed rating change

    - `--elo-diff-range` — Filter games by opponent Elo difference
        - `--elo-diff-lower INT` — Lower bound
        - `--elo-diff-upper INT` — Upper bound

    - `--date-from YYYY-MM` — Start date filter (inclusive)
    - `--date-to YYYY-MM` — End date filter (inclusive)

    - `--cache` — Enable caching (only if using --id)

- `--file FILE` — Analyze local TSV file
    - (WIP: planned for offline analysis mode)

#### Syntax

```bash
fide-tools analyze (--id <id> | --file <file>) [options]
```
Note: You must provide either `--id` (live FIDE data) or `--file` (local dataset). They are mutually exclusive.
## Examples
### Basic

```bash
fide-tools analyze --id 1503014 --performance
```
### Advanced
```bash
fide-tools analyze --id 1503014 --performance --elo-diff-range --elo-diff-lower -150 --elo-diff-upper 150 --cache
```

## Troubleshooting

If you get empty results:

- Check your FIDE ID is valid
- Ensure the player has games after 2008-04
- Try without `--date-from` / `--date-to`
## How it works

1. Scrape rating history from FIDE profile
2. Iterate through each rating period
3. Retrieve all games for each month
   - Note: Game-level data is only available from April 2008 onwards
   - Optionally filter games by date range before processing
4. Merge games with player rating
5. Export structured dataset
## Possible Analysis
- Rating progression over time
- Winrate vs opponent rating
- Performance with White vs Black
- Average opponent strength
- Rating gain per tournament
## Technical Notes
- Uses BeautifulSoup for HTML parsing
- Requests for HTTP calls
- FIDE endpoints used:
  - /a_indv_calculations.php
  - /profile/{id}
- Game data endpoint coverage begins in April 2008
- Handles inconsistent HTML tables
- Filters non-game rows (headers, summaries)
- Detects color via span classes (white_note / black_note)
## Future Improvements

### Performance & internal improvements
- Add cache expiration system (TTL-based caching)
- Investigate FIDE rate limits before enabling concurrency
- Parallelize monthly game fetching to reduce execution time
  (currently processed sequentially)

### Data & export features
- Export directly to Excel (.xlsx)

### User features
- Improve CLI UX (filters, validation, better date range handling)
- Visualization (matplotlib / seaborn)
- Multi-player comparison
- Web dashboard (Streamlit)

### Distribution & packaging
- Package distribution via PyPI
- Windows executable (.exe via PyInstaller)

## License

MIT License
