play-lichess

Python module for creating match links on Lichess that two players can join

Note: Until version 0.1.3, the requests were done synchronously using requests. Starting with version 1.0.0, all requests are done asynchronously using aiohttp.

📥 Installation

pip install play-lichess

🧑‍💻 Usage

Start a real-time match

from play_lichess import RealTimeMatch

async def create_match():
    match = await RealTimeMatch.create()

    print(match.challenge_id)       # e.g. 'f1S4BBYW'
    print(match.challenge_url)      # e.g. 'https://lichess.org/f1S4BBYW'
    print(match.status)             # 'created'
    print(match.variant)            # Variant.STANDARD
    print(match.rated)              # False
    print(match.speed)              # TimeMode.BLITZ
    print(match.time_control.show)  # '5+0'
    print(match.color)              # Color.RANDOM
    print(match.url_white)          # e.g. 'https://lichess.org/f1S4BBYW?color=white'
    print(match.url_black)          # e.g. 'https://lichess.org/f1S4BBYW?color=black'
    print(match.name)               # None

asyncio.run(create_match())  # import asyncio to call async functions outside event loop

Start a correspondence match

from play_lichess import CorrespondenceMatch

async def correspondence_match():
    match = await CorrespondenceMatch.create()

    print(match.challenge_id)               # e.g. 'KGO4ICDn'
    print(match.challenge_url)              # e.g. 'https://lichess.org/KGO4ICDn'
    print(match.status)                     # 'created'
    print(match.variant)                    # Variant.STANDARD
    print(match.rated)                      # False
    print(match.speed)                      # TimeMode.CORRESPONDENCE
    print(match.time_control.type)          # TimeControlType.CORRESPONDENCE
    print(match.time_control.days_per_turn) # 1
    print(match.color)                      # Color.RANDOM
    print(match.url_white)                  # e.g. 'https://lichess.org/KGO4ICDn?color=white'
    print(match.url_black)                  # e.g. 'https://lichess.org/KGO4ICDn?color=black'
    print(match.name)                       # None

Start an unlimited time match

from play_lichess import UnlimitedMatch

async def unlimited_correspondence_match():
    match = await UnlimitedMatch.create()

    print(match.challenge_id)       # e.g. 'JLA868mV'
    print(match.challenge_url)      # e.g. 'https://lichess.org/JLA868mV'
    print(match.status)             # 'created'
    print(match.variant)            # Variant.STANDARD
    print(match.rated)              # False
    print(match.speed)              # TimeMode.CORRESPONDENCE
    print(match.time_control.type)  # TimeControlType.UNLIMITED
    print(match.color)              # Color.RANDOM
    print(match.url_white)          # e.g. 'https://lichess.org/JLA868mV?color=white'
    print(match.url_black)          # e.g. 'https://lichess.org/JLA868mV?color=black'
    print(match.name)               # None

Specify game options

from play_lichess import RealTimeMatch, Variant

async def create_match_options():
    match: RealTimeMatch = await RealTimeMatch.create(
        rated=False,
        clock_limit=180,
        clock_increment=0,
        variant=Variant.ANTICHESS,
        name="Test match",
    )

    print(match.challenge_id)       # e.g. 'cuZGwbcO'
    print(match.challenge_url)      # e.g. 'https://lichess.org/cuZGwbcO'
    print(match.status)             # 'created'
    print(match.variant)            # Variant.ANTICHESS
    print(match.rated)              # False
    print(match.speed)              # TimeMode.BLITZ
    print(match.time_control.show)  # '3+0'
    print(match.color)              # Color.RANDOM
    print(match.url_white)          # e.g. 'https://lichess.org/cuZGwbcO?color=white'
    print(match.url_black)          # e.g. 'https://lichess.org/cuZGwbcO?color=black'
    print(match.name)               # 'Test match'

Alternate syntax

from play_lichess import Match

async def create_any_match():
    # real-time
    match1 = await Match.create(clock_limit=180, clock_increment=0)
    # unlimited time
    match2 = await Match.create(clock_limit=None, clock_increment=None)
    # correspondence
    match3 = await Match.create(days=1, clock_limit=None, clock_increment=None)

🔧 Options

Real-time

Correspondence

Unlimited

Variants

Variants are defined in the Variant enum and include:

• Variant.STANDARD (default)
• Variant.CRAZYHOUSE
• Variant.CHESS960
• Variant.KING_OF_THE_HILL
• Variant.THREE_CHECK
• Variant.ANTICHESS
• Variant.ATOMIC
• Variant.HORDE
• Variant.RACING_KINGS

🧰 Development

To run tests (pytest/tox)

# Install tox
pip install -U tox

# Run tests
tox

To lint (pyright)

# Install pyright
pip install -U pyright

# Run pyright
pyright