Metadata-Version: 2.3
Name: chess-com-api
Version: 1.1.0
Summary: An async Python wrapper for the Chess.com API
Project-URL: Homepage, https://github.com/Stupidoodle/chess-com-api
Project-URL: Documentation, https://Stupidoodle.github.io/chess-com-api
Project-URL: Repository, https://github.com/Stupidoodle/chess-com-api.git
Project-URL: Bug Tracker, https://github.com/Stupidoodle/chess-com-api/issues
Project-URL: Changelog, https://github.com/Stupidoodle/chess-com-api/blob/main/CHANGELOG.md
Author-email: Bryan Tran <bryan.tran.xyz@gmail.com>
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: typing-extensions>=4.0.0; python_version < '3.9'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mkdocs-material>=9.0.0; extra == 'dev'
Requires-Dist: mkdocs>=1.4.0; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.22.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: tox>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Chess.com API Client

[![PyPI version](https://badge.fury.io/py/chess-com-api.svg)](https://badge.fury.io/py/chess-com-api)
[![Python versions](https://img.shields.io/pypi/pyversions/chess-com-api.svg)](https://pypi.org/project/chess-com-api/)
[![Documentation Status](https://readthedocs.org/projects/chess-com-api/badge/?version=latest)](https://chess-com-api.readthedocs.io/en/latest/?badge=latest)
[![GitHub Actions](https://github.com/Stupidoodle/chess-com-api/workflows/CI/badge.svg)](https://github.com/Stupidoodle/chess-com-api/actions)
[![Coverage](https://codecov.io/gh/Stupidoodle/chess-com-api/branch/main/graph/badge.svg)](https://codecov.io/gh/Stupidoodle/chess-com-api)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A modern, fully typed, asynchronous Python wrapper for the Chess.com API.

## Features

- 🚀 **Fully Async**: Built with `aiohttp` for high-performance async operations
- 📦 **Type Safety**: Complete type hints and runtime type checking
- 🛡️ **Robust Error Handling**: Comprehensive error types and automatic retries
- 🔄 **Rate Limiting**: Built-in rate limit handling with smart backoff
- 📚 **Rich Data Models**: Intuitive object-oriented interface to API data
- ✨ **Modern Python**: Supports Python 3.8+
- 📈 **Production Ready**: Thoroughly tested and production hardened

## Installation

```bash
pip install chess-com-api
```

## Quick Start

```python
import asyncio
from chess_com_api import ChessComClient

async def main():
    async with ChessComClient() as client:
        # Get player profile
        player = await client.get_player("hikaru")
        print(f"Title: {player.title}")
        print(f"Rating: {player.rating}")
        
        # Get recent games
        games = await client.get_player_current_games("hikaru")
        for game in games:
            print(f"Game URL: {game.url}")
            print(f"Time Control: {game.time_control}")

asyncio.run(main())
```

## Advanced Usage

### Custom Session Configuration

```python
import aiohttp
from chess_com_api import ChessComClient

async def main():
    # Configure custom timeout and headers
    timeout = aiohttp.ClientTimeout(total=60)
    session = aiohttp.ClientSession(
        timeout=timeout,
        headers={"User-Agent": "MyApp/1.0"}
    )
    
    client = ChessComClient(
        session=session,
        max_retries=5,
        rate_limit=100
    )
    
    try:
        # Your code here
        pass
    finally:
        await client.close()

asyncio.run(main())
```

### Error Handling

```python
from chess_com_api.exceptions import NotFoundError, RateLimitError

async def get_player_info(username: str):
    try:
        async with ChessComClient() as client:
            player = await client.get_player(username)
            return player
    except NotFoundError:
        print(f"Player {username} not found")
    except RateLimitError:
        print("Rate limit exceeded, please try again later")
    except Exception as e:
        print(f"An error occurred: {e}")
```

## Documentation

For full documentation, please visit [chess-com-api.readthedocs.io](https://chess-com-api.readthedocs.io/).

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Install development dependencies (`pip install -e ".[dev]"`)
4. Make your changes
5. Run tests (`pytest`)
6. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
7. Push to the branch (`git push origin feature/AmazingFeature`)
8. Open a Pull Request

Please make sure to update tests as appropriate and follow the existing code style.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Chess.com for providing the public API
- The Python community for valuable feedback and contributions

## Support

If you encounter any problems or have any questions, please [open an issue](https://github.com/Stupidoodle/chess-com-api/issues/new/choose) on GitHub.