# Football API Client - Project Instructions

## Overview
Python API client for [football-data.org](https://www.football-data.org) API v4.
Public PyPI package: `football-api`.

## Tech Stack
- **Python**: 3.11+
- **HTTP**: `httpx` (async + sync)
- **Models**: `pydantic` v2
- **Build**: `hatchling`
- **Tests**: `pytest` + `pytest-asyncio` + `respx`
- **Linting**: `ruff`
- **Type checking**: `mypy`

## Project Structure
```
football_api/          # source package (underscore, not hyphen)
  __init__.py          # public API re-exports
  client.py            # FootballClient (sync) + AsyncFootballClient
  models.py            # Pydantic response models
  exceptions.py        # Custom exception hierarchy
tests/
  conftest.py          # shared fixtures
  test_client.py       # client method tests
  test_models.py       # model parsing tests
```

## Conventions
- All code, comments, docstrings, and documentation in **English only**
- Use `ruff` for formatting and linting (`ruff check --fix && ruff format`)
- Run `pytest` before every commit
- Keep models flat — mirror the API JSON structure, don't over-nest
- Use `__all__` in `__init__.py` to define public API
- Prefer `httpx` over `requests` for both sync and async support
- Never hardcode API tokens — always pass via constructor or env var

## Git Rules
- Never commit to `main` directly
- Use feature branches: `feature/<name>` or `fix/<name>`
- Do NOT add Co-Authored-By trailers
- Do NOT add Claude as co-author

## API Reference
- Base URL: `https://api.football-data.org/v4/`
- Auth header: `X-Auth-Token: <token>`
- Docs: https://docs.football-data.org/general/v4/index.html
