play-lichess 1.1.1

Description:

playlichess 1.1.1

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



Argument
Type
Default
Description




rated
bool
False
Whether the match is rated or not.


clock_limit
int
300
The time limit in seconds.


clock_increment
int
0
The time increment in seconds.


variant
Variant
STANDARD
The variant of the match (STANDARD, CHESS960, etc.)


fen
str
Start position
The FEN string of the starting position.


name
str
None
The name of the match displayed when joining.



Correspondence



Argument
Type
Default
Description




rated
bool
False
Whether the match is rated or not.


days
int
1
The number of days for each player.


variant
Variant
STANDARD
The variant of the match (STANDARD, CHESS960, etc.)


fen
str
Start position
The FEN string of the starting position.


name
str
None
The name of the match displayed when joining.



Unlimited



Argument
Type
Default
Description




variant
Variant
STANDARD
The variant of the match (STANDARD, CHESS960, etc.)


fen
str
Start position
The FEN string of the starting position.


name
str
None
The name of the match displayed when joining.



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