Skip to main content

skolaonline

CI PyPI Python License

A modern, fully typed Python SDK for the Škola OnLine API (SOL API 1.0), generated from and verified against the official OpenAPI specification.

This is an unofficial library and is not affiliated with BAKALÁŘI software s.r.o.

Features

  • Sync and async clients built on httpx
  • All 119 API operations across 18 resource groups
  • 270+ dataclass models and enums with automatic serialization
  • OAuth2 password and refresh token flows with automatic token refresh
  • API key and HTTP Basic authentication for system integrations
  • File downloads and multipart uploads
  • Typed exception hierarchy for API errors
  • Full type annotations and py.typed support
  • English docstrings for every endpoint, parameter, model field and enum member, shown by IDE autocompletion

Installation

pip install skolaonline

Quick Start

from datetime import date

from skolaonline import SkolaOnline

with SkolaOnline(username="your_username", password="your_password") as client:
    user = client.user.retrieve()
    print(user.full_name, user.user_type)

    timetable = client.timetable.retrieve(
        student_id=user.person_id,
        date_from=date(2026, 10, 19),
        date_to=date(2026, 10, 23),
    )
    for day in timetable.days:
        for hour in day.schedules:
            subject = hour.subject.name if hour.subject else hour.title
            print(day.date.date(), hour.begin_time.time(), subject)

    marks = client.marks.list_marks(user.person_id)
    for mark in marks.marks:
        print(mark.mark_date.date(), mark.mark_text, mark.theme)

For parent accounts, use the IDs from user.children as student_id.

Async

from skolaonline import AsyncSkolaOnline

async with AsyncSkolaOnline(
    username="your_username", password="your_password"
) as client:
    user = await client.user.retrieve()
    messages = await client.messages.list_received(page_size=20)
    for message in messages.messages:
        print(message.sent_date, message.title)

Every method of SkolaOnline has an async counterpart with the same name and signature on AsyncSkolaOnline.

Authentication

Username and password

The client requests an access token from the OAuth2 token endpoint (/api/connect/token) on the first API call. Tokens are refreshed automatically with the refresh token when they expire or when the API answers with 401 Unauthorized. If the refresh token is rejected, the client signs in again with the stored credentials.

client = SkolaOnline(username="your_username", password="your_password")
token = client.login()
print(token.access_token, token.refresh_token, token.expires_at)

login() is optional and forces an immediate sign in, which is useful to validate credentials early.

Reusing tokens

Persist tokens to avoid storing passwords. The on_token_refresh callback is called with a Token every time a new token is obtained.

from skolaonline import SkolaOnline, Token


def save_token(token: Token) -> None:
    store(token.access_token, token.refresh_token, token.expires_at)


client = SkolaOnline(
    access_token="stored_access_token",
    refresh_token="stored_refresh_token",
    expires_at=1792400000.0,
    on_token_refresh=save_token,
)

Passing only refresh_token is also supported. A client created with only access_token uses it as is and never refreshes it.

Standalone token helpers

from skolaonline import get_token, refresh_access_token

token = get_token("your_username", "your_password")
token = refresh_access_token(token.refresh_token)

async_get_token() and async_refresh_access_token() are the async variants.

API key and Basic authentication

Data interface endpoints used by system integrations accept an API key sent in the X-Api-Key header, or HTTP Basic credentials.

client = SkolaOnline(api_key="your_api_key")
students = client.data_interface.list_students()

client = SkolaOnline(basic_auth=("integration_user", "secret"))

Only one authentication method can be configured per client. Clients without any credentials can call anonymous endpoints such as client.configuration.min_app_version().

Configuration

Argument Default Description
base_url https://aplikace.skolaonline.cz/solapi API root, also used for the token endpoint
language None Response language sent in the app-lang header, cs or en
timeout 30.0 Timeout in seconds for API and token requests
headers None Extra headers sent with every request
client_id test_client OAuth2 client ID
scope openid offline_access profile sol_api OAuth2 scope for the password grant
http_client None Custom httpx.Client or httpx.AsyncClient

Supplying an HTTPX client

Pass your own httpx.Client to reuse a connection pool, proxies, transports or event hooks. The SDK applies its base URL, authentication, timeout and headers per request. A supplied client is not closed by the SDK.

import httpx

from skolaonline import SkolaOnline

with httpx.Client(proxy="http://localhost:8080") as http:
    client = SkolaOnline(username="user", password="secret", http_client=http)
    client.user.retrieve()

API Coverage

Resource Methods
absences code_lists, list_by_subject, list_in_day, list_in_period
apologies accept, cancel_rejection, code_lists, create, delete, list_absence_reasons, list_for_student, list_for_teacher, list_teacher_classes, list_times_from, list_times_to, reject, retrieve_for_student, retrieve_for_teacher, retrieve_rejection_reason, update, update_rejection_reason
b2c authenticate, synchronize
behaviors code_lists, create, delete, list_educational_measure_kinds, list_educational_measure_reasons, list_evaluation_kinds, list_for_student, list_for_teacher, list_note_kinds, list_students_of_class, list_teacher_classes, list_types, retrieve, sign, sign_many, update
class_books calculate_lesson_number, delete, list_entries, save, save_attendance
configuration min_app_version
data_interface list_additional_data_definitions, list_classes, list_student_records, list_students, list_students_with_consent
emergency list_participants, list_scenarios, start
files download, upload
homeworks code_lists, delete_elaboration_attachment, download_assignment_attachment, download_elaboration_attachment, list_for_student, list_for_teacher, mark_done, retrieve, save_elaboration, upload_elaboration_attachment
marks code_lists, create_for_teacher, delete_for_teacher, list_by_subject, list_final, list_marking_students, list_marks, retrieve, retrieve_for_teacher, sign, sign_many, update_for_teacher
messages count_recipients, create_draft, delete, download_attachment, list_drafts, list_received, list_recipients, list_recipients_without_contacts, list_sent, mark_as_read, retrieve_received, retrieve_sent, retrieve_settings, send, send_draft, update_draft, upload_attachment, vote
notifications retrieve_preferences, save_preferences, send, send_emergency, send_two_factor
payments list_regular, retrieve, retrieve_summary, update_parents_note
student_status list_students
test ping
timetable code_lists, retrieve, retrieve_detail
user change_password, disable_notifications, enable_notifications, list_notifications, logout, notifications_exist, retrieve, retrieve_dashboard, retrieve_password_requirements, send_feedback

Path parameters are positional, query and header parameters are keyword-only and use snake_case names. Pagination parameters Pagination.PageNumber and Pagination.PageSize are exposed as page_number and page_size. Dates accept datetime.date or datetime.datetime.

Operations that the specification documents without a response schema return the decoded JSON value, the response text, or None for empty responses.

The test suite checks every method against the bundled OpenAPI specification: each operation is implemented exactly once, with the documented HTTP method, path, query parameters, headers and request body type.

Models

Models live in skolaonline.models. Field names are snake_case versions of the API names, and to_dict() converts a model back to the API representation.

from datetime import datetime

from skolaonline.models import ApologyPostData

apology = ApologyPostData(
    excused_person_id="student_id",
    reason_absence_id="reason_id",
    date_from=datetime(2026, 10, 20),
    date_to=datetime(2026, 10, 21),
    specification="Doctor appointment",
)
client.apologies.create(apology)
  • Model fields are keyword-only. Required fields of request models have no default.
  • Enum fields use StrEnum members. Unknown values returned by the API are kept as plain strings.
  • Date and time fields are parsed into datetime objects.
  • Names that collide across API modules are prefixed with their module, for example MarkCodeListsResponse and TimetableCodeListsResponse.

Files

Downloads return a DownloadedFile with the content, the file name from the Content-Disposition header and the content type.

file = client.messages.download_attachment(message_id, attachment_id)
file.save(file.filename or "attachment")

Uploads accept bytes, a binary file object, or a (filename, content) or (filename, content, content_type) tuple.

with open("homework.pdf", "rb") as handle:
    client.homeworks.upload_elaboration_attachment(homework_id, handle, submit=True)

result = client.files.upload([("notes.txt", b"Notes", "text/plain")])

Error Handling

from skolaonline import (
    APIError,
    AuthenticationError,
    NotFoundError,
    PermissionDeniedError,
    SkolaOnlineError,
)

try:
    client.marks.retrieve("mark_id")
except AuthenticationError as error:
    print("Sign in failed", error.error_code)
except PermissionDeniedError:
    print("The module is not enabled for this user")
except NotFoundError:
    print("Mark not found")
except APIError as error:
    print(error.status_code, error.message, error.body)
except SkolaOnlineError as error:
    print("Client error", error)
HTTP status Exception
400 BadRequestError
401 AuthenticationError
403 PermissionDeniedError
404 NotFoundError
409 ConflictError
422 UnprocessableEntityError
429 RateLimitError
5xx ServerError
Other 4xx APIError

Every APIError exposes status_code, message, the decoded body and the original httpx.Response. The message is taken from userMessage, message, detail, title or error_description when the API returns JSON, otherwise from the response text. Token endpoint failures always raise AuthenticationError. SkolaOnlineError is the base class of all exceptions raised by the library.

Development

uv sync
make test
make coverage
make typecheck
make lint
make format

Python Version

Supports Python 3.11 through 3.14.

Contributing

Contributions are welcome. Please read the Contributing Guide before opening a pull request.

License

MIT

Metadata

Release files for skolaonline 0.1.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 skolaonline 0.1.0
File Size Uploaded Provenance Actions
skolaonline-0.1.0.tar.gz 57.1 kB Without provenance Details for skolaonline-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for skolaonline 0.1.0
File Interpreter ABI Platform Actions
skolaonline-0.1.0-py3-none-any.whl Python 3 none any Details for skolaonline-0.1.0-py3-none-any.whl

Total release size: 139.1 kB

Release files / skolaonline-0.1.0.tar.gz

Download URL skolaonline-0.1.0.tar.gz
Size 57.1 kB
Tags Source
SHA-256 checksum
How to use checksums
71fde4460d2954b30dd382c029530e38430b04c3d8c7d9de15a3b8b98f8a964d
BLAKE2b-256 checksum
How to use checksums
7e9cf45ad9b70519d1cf6517699d8d890af35dde8362657fe3d5b9a1e0e2a5a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / skolaonline-0.1.0-py3-none-any.whl

Download URL skolaonline-0.1.0-py3-none-any.whl
Size 82.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f980b0aabf02a9eebdcd8d88ffefce16f70d3f4eb6c88d229cc375f4b3ad8c0b
BLAKE2b-256 checksum
How to use checksums
b220d8ea6195b5e56890f704cb33dc99c16de460d70eb7d659114c2821e4a6ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for skolaonline 0.1.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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

0.1.0 This release

2 release files No 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