python-fide

🌍 Overview

python-fide is a Python package that provides an interface for retrieving detailed information about chess players from the FIDE API. This package allows users to access data such as player details, historical ratings, game statistics, and player opponents.

📦 Installation

You can install python-fide using pip:

pip install python-fide

📚 Usage

Importing the Client

To use the package, import the FidePlayerClient class and instantiate it:

from python_fide import FidePlayerClient

client = FidePlayerClient()

In addition, an asynchronous version of the client also exists and can be imported as follows:

from python_fide import AsyncFidePlayerClient

Retrieve Player Opponents

You can retrieve a list of opponents a player has faced using their FIDE ID:

from python_fide import FidePlayerID

fide_id = FidePlayerID(fide_id=123456)
opponents = client.get_opponents(fide_id)

print(opponents)

Example Output:

[
    FidePlayer(fide_id=FidePlayerID(fide_id=123456), name="Opponent Name", country="USA"),
    FidePlayer(fide_id=FidePlayerID(fide_id=123456), name="Another Opponent", country="UK")
]

Retrieve Rating Progress Chart

To get the rating progress chart of a player, use:

from python_fide import RatingPeriod

ratings = client.get_rating_progress_chart(fide_id, period=RatingPeriod.TWO_YEARS)

print(ratings)

Example Output:

[
    FidePlayerRating(
        month=Date(date_iso='2023-06-01', date_format='%Y-%b'),
        fide_id=FidePlayerID(fide_id=123456),
        standard=FideRating(games=10, rating=2500),
        rapid=FideRating(games=5, rating=2450),
        blitz=FideRating(games=8, rating=2400)
    )
]

Retrieve Game Statistics

To get game statistics for a player, optionally filtering by an opponent:

stats = client.get_game_stats(fide_id)

To get statistics against a specific opponent:

opponent_id = FidePlayerID(fide_id=654321)
stats = client.get_game_stats(fide_id, fide_id_opponent=opponent_id)

print(stats)

Example Output:

FidePlayerGameStats(
    fide_id=FidePlayerID(fide_id=123456),
    opponent=FidePlayerID(fide_id=654321),
    white=FideGamesSet(
        standard=FideGames(games_total=30, games_won=15, games_draw=10, games_lost=5),
        rapid=FideGames(games_total=20, games_won=10, games_draw=5, games_lost=5),
        blitz=FideGames(games_total=25, games_won=12, games_draw=8, games_lost=5)
    ),
    black=FideGamesSet(
        standard=FideGames(games_total=28, games_won=14, games_draw=9, games_lost=5),
        rapid=FideGames(games_total=18, games_won=9, games_draw=5, games_lost=4),
        blitz=FideGames(games_total=22, games_won=11, games_draw=7, games_lost=4)
    )
)

🔍 API Reference

Method	Description	Arguments	Returns
get_opponents(fide_player: FidePlayerID) -> List[FidePlayer]	Retrieves a list of opponents a player has faced.	fide_player (FidePlayerID): The FIDE ID of the player.	List[FidePlayer]: A list of FIDE players the given player has faced.
get_rating_progress_chart(fide_id: FidePlayerID, period: Optional[RatingPeriod] = None) -> List[FidePlayerRating]	Retrieves the rating progress chart for a player.	fide_id (FidePlayerID): The FIDE ID of the player. period (Optional[RatingPeriod]): The period to filter the rating history.	List[FidePlayerRating]: A list of rating history data.
get_game_stats(fide_id: FidePlayerID, fide_id_opponent: Optional[FidePlayerID] = None) -> FidePlayerGameStats	Retrieves game statistics for a player.	fide_id (FidePlayerID): The FIDE ID of the player. fide_id_opponent (Optional[FidePlayerID]): The FIDE ID of an opponent to filter game statistics.	FidePlayerGameStats: The game statistics for the given player.

🤝 License

This project is licensed under the MIT License. See the LICENSE file for more details.

📞 Contact

If you have any questions or need support, feel free to reach out by opening an issue on the GitHub repository.