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.7.0 reads point grades ("Oceny punktowe"), which made both grade reads fail at point-grade schools. 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.7.0

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.7.0-py3-none-any.whl

No CLI or background process is installed: import the library in your own program.

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.

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.7.0

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.7.0
File Size Uploaded Provenance Actions
librus_python_api-1.7.0.tar.gz 326.7 kB With provenance Details for librus_python_api-1.7.0.tar.gz

Built distribution (wheel)

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

Total release size: 490.7 kB

Release files / librus_python_api-1.7.0.tar.gz

Download URL librus_python_api-1.7.0.tar.gz
Size 326.7 kB
Tags Source
SHA-256 checksum
How to use checksums
3f0f4a320c76b3f8b49f546364d7ee9bbca38c2c13c7b5dcfd87fe509af6011b
BLAKE2b-256 checksum
How to use checksums
1f99ee4a81fce6a3311ab1d095620eb39a8facfe5e068a53288374c3464470a0
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 Oct 27, 2026.

Transparency log

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

Download URL librus_python_api-1.7.0-py3-none-any.whl
Size 164.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ee9d738877830ad60e170a3bdaf3b86052487f0a358b2a68dd5637f89e6a7806
BLAKE2b-256 checksum
How to use checksums
c3fc27adfb9bbdb9d27836d6490a1edde822d7192d1cec553ee76c2d27ae65c3
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 Oct 27, 2026.

Transparency log

Security for librus-python-api 1.7.0

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.7.0.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 Oct 27, 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.7.0 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