akinator.py

Installation

Python 3.3 or higher is required.

To install the stable version, do the following:

# Unix / macOS
python3 -m pip install "akinator"

# Windows
py -m pip install "akinator"

To install the development version, do the following:

$ git clone https://github.com/Ombucha/akinator.py

Make sure you have the latest version of Python installed, or if you prefer, a Python version of 3.9 or greater.

If you have have any other issues feel free to search for duplicates and then create a new issue on GitHub with as much detail as possible. Include the output in your terminal, your OS details and Python version.

Client

class akinator.Client(session: CloudScraper | None = None)

A class representing a client for the Akinator game.

Parameters:

session (Optional[CloudScraper]) – An optional CloudScraper object to use for making HTTP requests. If not provided, a new session will be created.

Variables:

  • flag_photo – The URL of the flag photo associated with the current game session.

  • photo – The URL of the character photo associated with the current game session.

  • pseudo – The pseudo name of the player in the current game session.

  • theme – The theme of the game session, which can be “c” (characters), “a” (animals), or “o” (objects).

  • session_id – The unique identifier for the current game session.

  • signature – The signature for the current game session.

  • identifiant – The unique identifier for the player in the current game session.

  • child_mode – A boolean indicating whether child mode is enabled for the game session.

  • language – The language used for the game session, represented as a string (e.g., “en” for English).

  • question – The current question being asked in the game session.

  • progression – The progression percentage of the game session, represented as a float.

  • step – The current step number in the game session.

  • akitude – The current akitude image associated with the game session.

  • step_last_proposition – The last proposition made in the current step.

  • finished – A boolean indicating whether the game session has finished.

  • win – A boolean indicating whether the player has won the game session.

  • id_proposition – The unique identifier for the current proposition in the game session.

  • name_proposition – The name of the current proposition in the game session.

  • description_proposition – The description of the current proposition in the game session.

  • proposition – The current proposition being made in the game session.

  • completion – The completion status of the game session, which can be “OK, “KO - TIMEOUT”, “SOUNDLIKE”, or other values.

  • confidence – The confidence level of the current question, represented as a float between 0 and 1.

  • theme_id – The ID of the current theme, represented as an integer.

  • theme_name – The name of the current theme, represented as a string.

  • akitude_url – The URL of the current akitude image associated with the game session.

property akitude_url: str

Returns the URL of the current akitude image.

answer(answer: str)

Submits an answer to the current question.

Parameters:

answer (str) – The answer to submit. Can be “yes”, “no”, “i don’t know”, “probably”, or “probably not”.

back()

Goes back to the previous question in the game.

Note

This method can only be called if the current step is greater than 0. If the step is 0, it raises a CantGoBackAnyFurther exception.

choose()

Chooses the current proposition as the answer to the game.

Note

This method can only be called after Akinator has proposed a win. If the game is already finished, it will raise a RuntimeError.

property confidence: float

Returns the confidence level of the current question.

defeat()

Handles the defeat scenario in the game.

exclude()

Excludes the current proposition from the game.

Note

This method can only be called after Akinator has proposed a win. If the game is already finished, it will call the defeat method.

start_game(*, language: str = 'en', child_mode: bool = False, theme: Literal['c', 'a', 'o'] = 'c')

Starts a new game session with the specified language, child mode, and theme.

Parameters:

  • language (str) – The language to use for the game. Defaults to “en” (English).

  • child_mode (bool) – Whether to enable child mode. Defaults to False.

  • theme (Literal["c", "a", "o"]) – The theme to use for the game. Can be “c” (characters), “a” (animals), or “o” (objects). Defaults to “c”.

property theme_id: int

Returns the ID of the current theme.

property theme_name: str

Returns the name of the current theme.

class akinator.Akinator(session: CloudScraper | None = None)

A class identical to Client, but created for compatibility with the previous version of the library.

class akinator.AsyncClient(session: CloudScraper | None = None)

A class representing an asynchronous client for the Akinator game.

Parameters:

session (Optional[CloudScraper]) – An optional CloudScraper object to use for making HTTP requests. If not provided, a new session will be created.

Variables:

  • flag_photo – The URL of the flag photo associated with the current game session.

  • photo – The URL of the character photo associated with the current game session.

  • pseudo – The pseudo name of the player in the current game session.

  • theme – The theme of the game session, which can be “c” (characters), “a” (animals), or “o” (objects).

  • session_id – The unique identifier for the current game session.

  • signature – The signature for the current game session.

  • identifiant – The unique identifier for the player in the current game session.

  • child_mode – A boolean indicating whether child mode is enabled for the game session.

  • language – The language used for the game session, represented as a string (e.g., “en” for English).

  • question – The current question being asked in the game session.

  • progression – The progression percentage of the game session, represented as a float.

  • step – The current step number in the game session.

  • akitude – The current akitude image associated with the game session.

  • step_last_proposition – The last proposition made in the current step.

  • finished – A boolean indicating whether the game session has finished.

  • win – A boolean indicating whether the player has won the game session.

  • id_proposition – The unique identifier for the current proposition in the game session.

  • name_proposition – The name of the current proposition in the game session.

  • description_proposition – The description of the current proposition in the game session.

  • proposition – The current proposition being made in the game session.

  • completion – The completion status of the game session, which can be “OK, “KO - TIMEOUT”, “SOUNDLIKE”, or other values.

  • confidence – The confidence level of the current question, represented as a float between 0 and 1.

  • theme_id – The ID of the current theme, represented as an integer.

  • theme_name – The name of the current theme, represented as a string.

  • akitude_url – The URL of the current akitude image associated with the game session.

property akitude_url: str

Returns the URL of the current akitude image.

async answer(answer: str)

Submits an answer to the current question.

Parameters:

answer (str) – The answer to submit. Can be “yes”, “no”, “i don’t know”, “probably”, or “probably not”.

async back()

Goes back to the previous question in the game.

Note

This method can only be called if the current step is greater than 0. If the step is 0, it raises a CantGoBackAnyFurther exception.

async choose()

Chooses the current proposition as the answer to the game.

Note

This method can only be called after Akinator has proposed a win. If the game is already finished, it will raise a RuntimeError.

property confidence: float

Returns the confidence level of the current question.

async defeat()

Handles the defeat scenario in the game.

async exclude()

Excludes the current proposition from the game.

Note

This method can only be called after Akinator has proposed a win. If the game is already finished, it will call the defeat method.

async start_game(*, language: str = 'en', child_mode: bool = False, theme: Literal['c', 'a', 'o'] = 'c')

Starts a new game session with the specified language, child mode, and theme.

Parameters:

  • language (str) – The language to use for the game. Defaults to “en” (English).

  • child_mode (bool) – Whether to enable child mode. Defaults to False.

  • theme (Literal["c", "a", "o"]) – The theme to use for the game. Can be “c” (characters), “a” (animals), or “o” (objects). Defaults to “c”.

property theme_id: int

Returns the ID of the current theme.

property theme_name: str

Returns the name of the current theme.

class akinator.AsyncAkinator(session: CloudScraper | None = None)

A class identical to AsyncClient, but created for compatibility with the previous version of the library.

Exceptions

class akinator.AkinatorException

Base exception for Akinator-related errors.

class akinator.CantGoBackAnyFurther(message: str = 'You are already at the first question.')

Raised when the user tries to go back but cannot.

class akinator.InvalidChoiceError(message: str = 'Invalid choice. Please choose a valid option.')

Raised when an invalid choice is made.

class akinator.InvalidThemeError(message: str = 'Invalid theme specified.')

Raised when an invalid theme is specified.

class akinator.InvalidLanguageError(message: str = 'Invalid language specified.')

Raised when an invalid language is specified.