Python modules

Generated from the backend’s own docstrings, so it cannot drift from the code.

The library

The game library: PGN files on disk plus a SQLite index over them.

Layout (DATA_DIR defaults to ./library, or /data on Railway with a volume):

library/
  library.db                  index + repertoires + settings
  collections/
    my-games/games.pgn        plain PGN, appended to; still valid PGN
    masters/games.pgn

Games stay in ordinary PGN files you can copy elsewhere or open in any other program; the database only remembers where each one starts and ends.

backend.store.slugify(name)

class backend.store.Library(data_dir)

Bases: object

static signature(text)

connect()

close()

collections()

collection(ident)

ensure_collection(name, kind='games')

collections_for(game_ids)

Every collection each of these games sits in, owner first then links.

link_game(game_id, collection)

Shelve an existing game in another collection. Returns False if it is already there.

unlink_game(game_id, collection)

Take a game off a shelf it was linked onto. The owning collection is not a link.

name_openings(collection=None)

Fill in opening names for games imported before, or without, an Opening tag.

delete_collection(ident, remove_files=False)

add_games(pgn_text, collection='My games', source='import', skip_duplicates=True, kind='games')

Append every game in pgn_text to a collection. Returns a summary dict.

kind only applies when the collection is being created: a collection that already exists keeps whatever kind it was given, so importing into it never moves somebody’s games out of the database behind their back.

game_pgn(game_id)

game(game_id)

SORTS = {'added': 'added_at DESC, id DESC', 'annotator': 'annotator COLLATE NOCASE ASC, id DESC', 'black': 'black COLLATE NOCASE ASC', 'date': 'date DESC, id DESC', 'date_asc': 'date ASC, id ASC', 'eco': 'eco ASC, date DESC', 'elo': 'MAX(COALESCE(white_elo,0), COALESCE(black_elo,0)) DESC', 'event': 'event COLLATE NOCASE ASC, date DESC', 'event_date': "COALESCE(NULLIF(event_date,''), date) DESC, event COLLATE NOCASE ASC, round ASC", 'length': 'ply_count DESC', 'opening': 'opening COLLATE NOCASE ASC, eco ASC', 'result': 'result ASC, date DESC', 'round': 'event COLLATE NOCASE ASC, LENGTH(round) ASC, round ASC', 'white': 'white COLLATE NOCASE ASC'}

search(query=None, collection=None, player=None, white=None, black=None, eco=None, result=None, opening=None, min_elo=None, year=None, sort='date', limit=100, offset=0, event=None, min_length=None, max_length=None, tag=None, added_from=None, added_to=None, position=None, eco_to=None, max_elo=None, outcome=None, annotator=None, site=None, round=None, termination=None, annotated=None, date_from=None, date_to=None, source=None, category=None, white_min_elo=None, white_max_elo=None, black_min_elo=None, black_max_elo=None, kind=None, team=None, title=None, fide_id=None, source_title=None, variation=None, event_type=None, event_date_from=None, event_date_to=None)

begin_import(label)

end_import(batch)

import_history()

undo_import(batch)

delete_game(game_id)

Drops the index entry. The PGN text stays in the file until compacted.

replace_game(game_id, pgn_text)

Save an edited/annotated game: appended fresh, index re-pointed at it.

stats()

setting(key, value=None)

repertoires()

repertoire(rep_id)

save_repertoire(name, color, data, rep_id=None)

delete_repertoire(rep_id)

cache_explorer(fen, db_name, body=None, max_age=604800)

PGN reading

PGN splitting and header extraction.

The server never needs to understand chess rules — the browser has a full engine for that. All it does here is cut a PGN stream into games, read the tag pairs, and pull out enough of the movetext to index and search on.

backend.pgnutil.split_games(text)

Cut a PGN stream into individual game texts.

backend.pgnutil.headers(game_text)

Tag pairs as a dict.

backend.pgnutil.movetext(game_text)

Everything after the tag pairs.

backend.pgnutil.moves(game_text, limit=None)

Main-line SAN moves, variations skipped.

backend.pgnutil.to_int(value)

backend.pgnutil.normalize_date(value)

PGN dates are ‘YYYY.MM.DD’ with ‘??’ for unknown parts; make them sortable.

backend.pgnutil.speed_of(time_control)

Bucket a PGN TimeControl tag. Unknown or correspondence returns ‘’.

backend.pgnutil.describe(game_text)

Everything the index wants to know about one game.

Importing

Streaming imports of portable chess files. Archives are read, never extracted.

backend.importers.sniff_encoding(sample, more_follows=True)

Pick the encoding for a PGN file from its opening bytes.

backend.importers.decoded(binary, encoding=None)

Wrap a binary stream as text, sniffing the encoding when the stream allows it.

backend.importers.streams(path)

backend.importers.game_stream(stream)

backend.importers.epd_stream(stream)

backend.importers.puzzle_csv(stream)

backend.importers.import_local(library, path, collection)

backend.importers.import_source(library, source, collection)

backend.importers.chesscom(library, user, collection, maximum=100)

Chess rules

Standard chess rules, 0x88 board, legal SAN and canonical position keys.

No runtime dependencies; used only for library indexing, never for UI latency.

backend.chess.square(name)

backend.chess.name(sq)

backend.chess.color(piece)

class backend.chess.Chess(fen='rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1')

Bases: object

fen()

attacked(target, by)

check(side=None)

pseudo()

push(move)

snapshot()

restore(state)

legal()

san(move, legal=None)

move(text)

key()

perft(depth)

The engine

The bundled Stockfish, spoken to over UCI.

One long-lived process, guarded by a lock, plus a background worker that can annotate a whole game and store the result. The browser no longer needs its own engine when the app runs on the desktop.

backend.engine.default_binary()

Where the bundled engine lives, in the source tree or inside a build.

exception backend.engine.EngineError

Bases: Exception

class backend.engine.Engine(path=None, threads=None, hash_mb=256)

Bases: object

A single UCI process. All public methods are safe to call from threads.

available()

start()

stop()

set_option(name, value)

info()

analyze(fen, movetime=None, depth=None, multipv=1, on_update=None, skill=20)

Blocking analysis of one position. Returns the best lines, best first.

class backend.engine.LiveAnalysis

Bases: object

Dedicated UCI process so batch annotation cannot block live updates.

stop()

start(fen, multipv)

status()

class backend.engine.AnnotationJob(engine, library)

Bases: object

Walks a game’s positions and scores every one of them.

JUDGMENTS = [(300, 'blunder'), (150, 'mistake'), (75, 'inaccuracy')]

status()

start(game_id, positions, movetime=300, depth=None)

positions is [{ply, fen, san}] worked out by the browser’s rules engine.

stop()

classmethod judge(loss)

Machine telemetry

Best-effort machine telemetry to show beside the engine.

Nothing here is required and nothing here is estimated. Core counts come from the OS; heat and power draw are read from whatever the firmware chooses to publish, which on Windows is a coin toss — plenty of desktops expose no thermal zone at all, and a machine on mains power reports no discharge rate because it is not discharging. Anything the machine will not tell us is reported as None so the interface can say “not available” instead of inventing a number.

Probing costs a subprocess on Windows, so readings are cached and refreshed on a background thread: callers always get the last known values immediately.

backend.hardware.cores()

Logical and physical core counts, physical only when psutil can tell us.

class backend.hardware.CpuLoad

Bases: object

Whole-machine CPU load, measured from our own reading of the CPU time counters.

psutil.cpu_percent(interval=None) reports the load since the last call made anywhere in the process, and keeps that “last call” in module-level state. The live-analysis panel polls several times a second across many server threads, so that shared state gets reset out from under us and a poll lands on a zero-length interval — reporting 0% while the engine has every core pinned.

Taking the cpu_times() snapshot ourselves removes the shared state: the window is the one between our own two samples, whoever else is asking. Readings are cached between samples so rapid polling is cheap as well as correct.

MIN_INTERVAL = 0.5

read()

class backend.hardware.Telemetry

Bases: object

Cached sensor readings, refreshed off the request thread.

snapshot()

backend.hardware.system()

Whole-machine load, heat and power, as far as this machine will say.

Repertoire lines from PGN

Turn an opening PGN — a lichess study export, or anything with variations — into repertoire lines.

A lichess repertoire study is a tree: one main line with alternatives branching off it, often many levels deep. The repertoire trainer stores flat lines instead, so this walks the tree and writes down every root-to-leaf path through it.

Two decisions are worth stating plainly. A line is trimmed so it ends on a move by the side the repertoire is for: finishing a drill on the opponent’s reply teaches nothing. And a line that is only the opening part of a longer line is dropped, because drilling it would be drilling the same moves twice.

backend.repertoire.from_pgn(pgn_text, color='w', max_plies=40)

Repertoire lines for one side, plus a report on what was read and skipped.

backend.repertoire.merge(existing, incoming)

Add only the lines a repertoire does not already hold, keeping review history.

Position index and study folders

Position knowledge and portable study folders layered on the PGN library.

class backend.study.Study(library)

Bases: object

index(collection)

position(fen)

pin(body)

folders()

create_folder(body)

delete_folder(folder_id)

Remove a folder and everything nested inside it.

Collections are only unassigned: their PGN files live in the library’s collections directory, not in the study folder. On disk we take back the manifest we wrote and the directories we created, but a directory the user has put their own files in is left alone and reported back.

assign(body)

write_manifest(folder_id)

categorize_folder(ident, category)

The opening tree

One player’s openings, judged by how they actually went.

A reference database answers “what is played here”. This answers a different and often more useful question: when this player played it, what happened to them. That player may be the reader, and may just as easily be Fischer or whoever a collection was imported for. Every number is from the named player’s side of the board, so a 38% score is 38% for them, not for White.

It reads the position index, so a collection has to be indexed before it has anything to say. Two things fall out of that design:

• Transpositions come for free. Positions are stored under a transposition key, so a line reached by a different move order is the same node.

• Depth costs nothing at query time. The index already holds every position of every game, so walking twenty moves deep is the same query as walking one.

The weakest-line scan is the part worth explaining. Ranking by score alone surfaces a 0% line played twice; ranking by volume surfaces the main line, which is no news. What a reader wants is where the points actually went, so lines are ranked by points dropped — games multiplied by the shortfall against an even score — and a line has to clear a minimum number of games before it is listed at all.

class backend.openingtree.Filters(player=None, color=None, collection=None, speed=None, since=None, until=None, min_opponent_elo=None, max_opponent_elo=None, rated=None, kind=None)

Bases: object

The set of games a report is about, and the SQL to select them.

property perspective

side_sql()

An expression naming the side the report is written from, and its params.

opponent_elo_sql()

where()

Clauses and params common to every query in this module.

backend.openingtree.position(library, fen, filters)

What happened from this position, move by move, from the named player’s side.

backend.openingtree.trend(rows, buckets=None)

Score by year over rows already read. Kept for callers working in memory.

backend.openingtree.weakest(library, filters, min_games=3, limit=15, max_ply=24)

The lines that cost the most points, ranked by points dropped rather than by score.

A single 0% game is noise; twelve games at 25% is a hole in the repertoire. Each entry names the line by replaying the game that reached it, so the answer reads as moves rather than as a hash.

backend.openingtree.players(library, collection=None, limit=40)

Who appears most often in a collection, so the report can be pointed at someone.

Automatic imports

Keep a lichess account’s games flowing into the library as they are played.

A background thread asks lichess, every so often, for the games played since it last looked. That is deliberately a poll rather than a live stream: streaming an account’s games needs board scopes this app has no business holding, and a game is worth analysing a few minutes after it ends just as much as a few seconds after.

Three decisions worth stating, because each one is a trap avoided:

• Windows overlap. Each poll asks for games since a little before the last one finished, not since exactly then. A game that ended during the gap is caught, and the repeat is free because duplicates are detected by lichess game id.

• Enabling does not backfill. Switching this on starts from now. Pulling in a decade of blitz because somebody ticked a box is not a welcome surprise; the manual importer is still there for history, and “Import now” fetches a window on request.

• Every run is an undoable batch, exactly like an import you started by hand, so a run that brings in something unwanted can be taken back.

class backend.autoimport.AutoImport(library, token, study=None)

Bases: object

Polls lichess for new games and files them in the library.

settings()

save(changes)

Validate and store the watcher’s settings, then start or stop it to match.

apply(values=None)

start()

stop(timeout=2.0)

trigger()

Ask for a check now, whether or not the watcher is running.

run_once(values=None)

Fetch and file whatever has been played since the last look.

save_cursor(values, stamp)

status()

lichess client

Server-side lichess client.

Doing the network work here rather than in the browser fixes the rate limiting: one process, one queue, one request at a time, with a shared cooldown. The browser can click “load” as often as it likes.

exception backend.lichess.RateLimited(retry_after)

Bases: Exception

class backend.lichess.Throttle(min_gap=1.0)

Bases: object

One request at a time, with a minimum gap and a cooldown after a 429.

wait()

penalize(seconds)

cooldown_left()

backend.lichess.user_games(user, max_games=100, color=None, rated=None, perf=None, since=None, token=None)

backend.lichess.import_all_user_games(library, user, collection, token=None, batch_size=200, progress=None, **selection)

Stream a whole lichess account into the library, however many games that is.

Asking for every game means not knowing how many are coming, which rules out holding the answer in memory: an active account is hundreds of megabytes of PGN. So the response is read as it arrives and written in batches, and the caller is told the running count rather than made to wait in silence.

selection takes the same narrowing arguments as user_games — color, rated, perf, since, until — so “every rated blitz game since 2023” is one call.

backend.lichess.explorer(db='masters', play=None, fen=None, moves=12, top_games=8, extra=None, token=None)

backend.lichess.masters_pgn(game_id, token=None)

class backend.lichess.MastersCrawler(library)

Bases: object

Walks the masters opening explorer and files away the games it names.

Breadth-first from the start position: every position it visits contributes its top games, and every move played often enough becomes a new position to visit. Slow by design (the explorer is a free service) but it can be left running, and it picks up where it left off.

status()

start(max_depth=8, max_positions=400, min_games=200, top_games=8, collection='Masters', opening_moves=None)

stop()

backend.lichess.import_dump(library, path, collection='Masters', limit=None, batch_size=500, progress=None)

Import a downloaded lichess PGN dump (plain .pgn, or .pgn.zst with zstandard).

Streamed in batches so a multi-gigabyte file never has to fit in memory.

backend.lichess.token_scopes(token)

What a personal access token is allowed to do, straight from lichess.

backend.lichess.account(token)

The signed-in account, plus the scopes the token carries.

backend.lichess.studies(username, token=None)

Every study lichess will show this token, newest first. Private ones need study:read.

backend.lichess.study_pgn(study_id, token=None, comments=True, variations=True)

One study exported as PGN, every chapter in one file.

The API surface

JSON API over the library.

Every handler returns (status, payload). Payloads are dicts (sent as JSON) or a (bytes, content_type) tuple for raw downloads.

exception backend.api.ApiError(message, status=400)

Bases: Exception

class backend.api.Api(data_dir)

Bases: object

handle(method, path, query, body)

SECRET_SETTINGS = ('lichess_token',)