Skip to main content

librus-python-api

Weekly live check

Read grades, attendance, homework, timetables and messages from Librus Synergia in Python. This independent, asynchronous client handles login, session recovery, pagination and request limits, returning typed Python objects rather than HTML.

Use it in personal scripts, notification services or application backends. One service can manage multiple logins while keeping their sessions and data separate. It is not an official Librus product.

Requirements: Python 3.13 or newer. Disk workflows require a trusted local POSIX filesystem on Linux/macOS, or a fixed local NTFS volume on Windows with private ACLs. Windows installations include pywin32 and tzdata automatically. Network paths, reparse-point paths and unsafe storage permissions fail closed. See platform requirements.

Status: 1.10.3 reads pages with the libxml2 that lxml's Windows wheels bundle, reads a grade detail table without period headings and types the archive's loading notice as maintenance. 1.10.2 rejects a date whose weekday label names another day and a completed-lesson cell with more than one comma, and fixes two cache bugs. 1.10.1 reads descriptive grades that the new-schema table shows as grade boxes. 1.10.0 returns behaviour points as a typed value (GradeRecords.behaviour_points), reads the e-Justifications list on parent logins (AccountClient.justifications()) and checks the gateway grade pagination member recorded live. 1.9.0 gives every ordinary grade its stable Librus ID (grade_id) and links a corrected grade to its corrections, as the all view brackets them (GradeRecords.corrections, grade corrections). 1.8.4 reads multi-line formative assessment text and repeated correction lines in grade tooltips, checks the new-schema grade table in every grade view and reports missing calendar-consumption consent as ConsentRequiredError. 1.8.3 reads behaviour grade symbols, filled descriptive grade tables, the "Aktualnie brak ogłoszeń" page and absences excused through e-Usprawiedliwienia. 1.8.2 keeps the modern mailbox session across a cancelled read or a reached limit and sends its own version in the User-Agent. 1.8.1 recovers a session Synergia no longer knows (it answers with a "Brak dostępu" page, not a login redirect), reads the lucky number from the page header and summarizes a page that fails as a whole in diagnostics. 1.8.0 reports where a failure happened (code locations and a redacted page structure, see failure diagnostics), reads gateway descriptive grades for schools on the new descriptive schema (source-informed, first populated read live on one school) and keeps the 1.7.1 point grades and multi-line grade comments. It keeps the 1.6.4 linear-time message body rendering and the 1.6.2 completed-lesson and grade layouts, including behaviour points, which are validated and not reported as grades. Class free days, typed capability outcomes and the live-check freshness watchdog remain available. See verification. The stable 1.x API does not guarantee every school layout. School features depend on what each account can access. See the compatibility policy. See limitations below.

Install

Install the exact release from PyPI after its gated publication completes:

python -m pip install librus-python-api==1.10.3

Pin the exact version qualified by your application. Before publication, use a checkout or locally built wheel instead. From a checkout, install into a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install .

To install a locally built wheel instead:

python -m pip install ./dist/librus_python_api-1.10.3-py3-none-any.whl

No console script or background process is installed: import the library in your own program. python -m librus_python_api.inspect_page only parses a saved page offline for a bug report.

First request

Provide your login and password through your application's secret management. The example reads environment variables; the library itself does not discover environment variables or credential files.

You also need an application context key. Generate it once, store it alongside your other application secrets, and reuse it across runs:

python -c 'import secrets; print(secrets.token_hex(32))'

Set LIBRUS_LOGIN, LIBRUS_PASSWORD and LIBRUS_CONTEXT_KEY in your environment. The last variable is the 64-character hex output from that command. Do not use your password as this key. Then run:

import asyncio
import os
from datetime import date

from librus_python_api import AccountCredentials, HomeworkRangeRequest, LibrusService


async def main() -> None:
    accounts = {
        "school": AccountCredentials(
            login=os.environ["LIBRUS_LOGIN"],
            password=os.environ["LIBRUS_PASSWORD"],
        )
    }
    context_key = bytes.fromhex(os.environ["LIBRUS_CONTEXT_KEY"])
    async with LibrusService(accounts, context_key=context_key) as service:
        client = service.account("school")
        profile = await client.student_information()
        print(profile)

        today = date.today()
        homework = await client.homework_range(
            HomeworkRangeRequest(today.replace(day=1), today)
        )
        for item in homework.items:
            print(item.subject, item.topic, item.due_on)


asyncio.run(main())

"school" is your local account alias, not a student ID. Login occurs on the first request. The async context manager closes sessions and outstanding work when it exits. Results are immutable dataclasses; personal fields are omitted from their repr, so access named attributes when displaying data intentionally.

Common tasks

Inside the service context above:

from datetime import timedelta

# School-provided final grades, grouped into typed subject records.
grades = await client.final_grades()
for subject in grades.items:
    print(subject.subject, subject.annual.raw)

# A week always starts on Monday.
today = date.today()
monday = today - timedelta(days=today.weekday())
timetable = await client.timetable(monday)

# Inclusive date window. Neither attendance nor grades computes a GPA.
attendance = await client.attendance_window(today.replace(day=1), today)

# Permit reuse of this account's cached result for up to 60 seconds.
announcements = await client.announcements(max_age_seconds=60)

# Earlier school years, separate from the message archive (1.3.0).
archive = await client.school_year_archive()
for year in archive.years:
    print(year.school_year, year.subjects)

Collections expose named record tuples, for example homework.items, rather than name-keyed dictionaries. Dates are Python date values where established by the upstream contract. Displayed detail values remain strings; missing or unknown values are not replaced with guessed zeros. Full signatures, result fields and examples are in the API reference.

Multiple accounts

Add more aliases to accounts, then use service.account(alias) for each login. Reuse one service so concurrent calls share its request budget and connection limits. A parent login and a student login are separate contexts even when they refer to the same student. Separate processes need application-level coordination if they share an upstream traffic allowance.

Bounded pagination and errors

from librus_python_api import RequestBudget
from librus_python_api.exceptions import LibrusError, ViewDisabledError

budget = RequestBudget(max_requests=20, timeout_seconds=60)
try:
    batch = await client.messages(limit=25, max_pages=2, budget=budget)
    for message in batch.items:
        print(message.subject)
    # Request another batch with cursor=batch.next_cursor when it is not None.
except ViewDisabledError:
    print("This school has disabled the requested view.")
except LibrusError as error:
    print(f"Request failed: {error.kind.value}")

A budget covers login, queueing and all pages of an operation. Defaults allow 10 requests/second, a burst of 20 and four simultaneous requests across the service, with one at a time per login. Fresh reads are the default. Unsupported layouts raise typed errors rather than silently returning incomplete data. Cursors detect changes; they are not snapshots.

Messages, files and notifications

  • Message content: opening received content can mark it read. Pass allow_mark_read=True only when your application permits that effect.
  • Sending: prepare a single-use send attempt and obtain approval in your application. An UNKNOWN result must not trigger an automatic resend.
  • Attachments: stream bytes with explicit limits, or use the optional files.publish_attachment() helper to save atomically into an existing directory.
  • Notifications: optional NotificationStore and NotificationWorkflow provide durable checkpoints, pending delivery and explicit acknowledgement.
  • Persistent sends: optional PersistenceStore records confirmations, claims and uncertain outcomes across restarts. Stores create or validate private caller-selected directories; core reads do not create files. Use explicit files.prepare_attachment_directory(path) to provision a private download directory without writing platform-specific ACL code.

The legacy and modern messaging backends have distinct references and permissions; select one explicitly. See the API reference for complete workflows.

Context keys and upgrading from 0.6

LibrusService now requires context_key, exactly 32 secret random bytes. client.context.identifier is an HMAC-SHA256 pseudonym bound to that key, the alias, login and configured origins. Password changes preserve it. Different application keys produce different identifiers; the identifier is not a login credential or permission token. The separate context.alias is still plain text.

Back up and reuse the key with persistent state. Losing or rotating it changes all context identifiers. Do not treat an empty history under a different key as permission to resend a message. Version 0.7 uses storage and notification archive format 3 and refuses older formats without modifying them. Keep 0.6 stores and their pending/UNKNOWN records for reconciliation; there is no automatic migration. See the upgrade guide before reusing a persistent application.

Loguru is no longer a dependency. For optional diagnostics, pass diagnostic_sink=librus_python_api.diagnostics.logging_sink after importing that function. Configure handlers with Python's standard logging module. You can also pass your own callable; events contain allowlisted timing/outcome fields, not credentials, account aliases or response bodies. The old loguru_sink was removed in 0.7.

Supported features and limitations

Area Available
School data Profile, grades, school-year archive, attendance, timetable, announcements, agenda, homework and completed lessons
Communication Legacy/modern message lists and content, recipient discovery, bounded attachment streams and explicit sending
Application workflows Shared multi-account limits, caching, notification checkpoints, optional durable send/notification stores

Completed lessons may be disabled by the school. Behaviour notes are not implemented. Some recipient, archive and receipt layouts remain unqualified; backend acceptance is not proof of delivery. Tests cover supported contracts, not every school or role. Detailed coverage is in the verification log; open work is tracked in issues.

Diagnosing failures

Errors carry only their kind. To see where a failure happened without any page data, use the helpers in librus_python_api.diagnostics (see API.md):

from librus_python_api.diagnostics import describe_failure, failure_frames
from librus_python_api.exceptions import LibrusError

try:
    await client.grades()
except LibrusError as error:
    print(
        error.kind, failure_frames(error)
    )  # ('grade_records:_numeric:100', 'markup:tooltip_fields:113')
    print(describe_failure(error))  # masked HTML structure around the failure

To check a saved page offline (a page source saved with Ctrl+U, or a copied table), run python -m librus_python_api.inspect_page grades page.html (or final-grades, or profile for the information page /informacja). Save the page source itself: in Safari use File > Save As with format Page Source; in Chrome on macOS open it with Option+Cmd+U, then Cmd+S. A source view copied into TextEdit is a text document, which inspect_page rejects. It prints counts, or the failure's code locations and masked structure, and makes no request. Pass a diagnostic_sink to LibrusService to receive one DiagnosticEvent per operation, with frames on failure. None of these print page text, values, logins or exception messages.

Development and support

Use a repository checkout for tests and development tools; they are deliberately excluded from published source archives. See CONTRIBUTING.md for setup and offline checks. Report bugs through GitHub Issues and security concerns according to SECURITY.md. Do not attach credentials or raw school data to public reports.

MIT licensed. See LICENSE.

Metadata

Release files for librus-python-api 1.10.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for librus-python-api 1.10.3
File Size Uploaded Provenance Actions
librus_python_api-1.10.3.tar.gz 368.3 kB With provenance Details for librus_python_api-1.10.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for librus-python-api 1.10.3
File Interpreter ABI Platform Actions
librus_python_api-1.10.3-py3-none-any.whl Python 3 none any Details for librus_python_api-1.10.3-py3-none-any.whl

Total release size: 564.8 kB

Release files / librus_python_api-1.10.3.tar.gz

Download URL librus_python_api-1.10.3.tar.gz
Size 368.3 kB
Tags Source
SHA-256 checksum
How to use checksums
814df03fc029adc1bf64896bdc8d703fc9fb70a84989ef81acdb194296658316
BLAKE2b-256 checksum
How to use checksums
ea84c99f54b4c5dc75aaea992d21a841dadce7b98de37ca29667588ec93b2464
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / librus_python_api-1.10.3-py3-none-any.whl

Download URL librus_python_api-1.10.3-py3-none-any.whl
Size 196.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce3d953af6bc049e0c7236f08e7042fb29d0404e0582a96b34000ba1d6283355
BLAKE2b-256 checksum
How to use checksums
4e9e7b1a5ad2f74fbb345feee1904645e8f76766108ce85ec7cfcfc8101dfa64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for librus-python-api 1.10.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for librus_python_api-1.10.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.10.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page