A modern, easy-to-use Python wrapper for the Akinator web game, supporting both synchronous and asynchronous usage.

Background

Originally, there was a popular Python library called akinator.py, which provided a simple interface to interact with the Akinator API. However, this library suddenly disappeared from public repositories without notice. In response, a mirror was created here to preserve its functionality. Unfortunately, it too stopped working after Akinator made changes to their backend API. Later, another library called akipy emerged to fill the gap, but it also became non-functional when Cloudflare protection was introduced on Akinator's endpoints. This library revives Akinator interaction by replacing the standard requests library with cloudscraper, allowing it to bypass Cloudflare's anti-bot measures and restoring full functionality.

Features

• Play Akinator in Python (sync and async)
• Supports all official Akinator languages and themes
• Simple, Pythonic interface
• Type hints for better editor support
• Custom exceptions for robust error handling
• Well-tested and documented
• Actively maintained and open source

Requirements

• Python 3.9 or higher
• cloudscraper

Installation

To install the latest stable version:

python3 -m pip install akinator

To install the development version:

git clone https://github.com/Ombucha/akinator.py
cd akinator.py
python3 -m pip install -e .

Getting Started

Synchronous Example

import akinator

aki = akinator.Akinator()
aki.start_game()

while not aki.finished:
    print(f"\nQuestion: {str(aki)}")
    user_input = input(
        "Your answer ([y]es/[n]o/[i] don't know/[p]robably/[pn] probably not, [b]ack): "
    ).strip().lower()
    if user_input == "b":
        try:
            aki.back()
        except akinator.CantGoBackAnyFurther:
            print("You can't go back any further!")
    else:
        try:
            aki.answer(user_input)
        except akinator.InvalidChoiceError:
            print("Invalid answer. Please try again.")

print("\n--- Game Over ---")
print(f"Proposition: {aki.name_proposition}")
print(f"Description: {aki.description_proposition}")
print(f"Pseudo: {aki.pseudo}")
print(f"Photo: {aki.photo}")
print(f"Final Message: {aki.question}")

Asynchronous Example

import asyncio
import akinator

aki = akinator.Akinator()

async def play():
    await aki.start_game()

    while not aki.finished:
        print(f"\nQuestion: {str(aki)}")
        user_input = input(
            "Your answer ([y]es/[n]o/[i] don't know/[p]robably/[pn] probably not, [b]ack): "
        ).strip().lower()
        if user_input == "b":
            try:
                await aki.back()
            except akinator.CantGoBackAnyFurther:
                print("You can't go back any further!")
        else:
            try:
                await aki.answer(user_input)
            except akinator.InvalidChoiceError:
                print("Invalid answer. Please try again.")

    print("\n--- Game Over ---")
    print(f"Proposition: {aki.name_proposition}")
    print(f"Description: {aki.description_proposition}")
    print(f"Pseudo: {aki.pseudo}")
    print(f"Photo: {aki.photo}")
    print(f"Final Message: {aki.question}")

asyncio.run(play())

Advanced Usage

• Languages: All official Akinator languages are supported (see LANG_MAP in the code).
• Themes: Use "c" for characters, "a" for animals, "o" for objects (not all themes are available in all languages).
• Error Handling: All errors raise custom exceptions like CantGoBackAnyFurther, InvalidLanguageError, InvalidChoiceError, and InvalidThemeError.
• Custom Session: You can pass your own cloudscraper.CloudScraper session for advanced usage.
• Async and Sync: Both sync and async clients are available for all use cases.
• Testing: Comprehensive test suite for both sync and async clients.
• Examples: See the examples/ directory for CLI and bot scripts.

Links

• Akinator
• Documentation
• Examples
• PyPI

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for details.

License

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