bakalari 1.0.0__tar.gz

bakalari-1.0.0/CHANGELOG.md

@@ -0,0 +1,227 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-10-26
+
+Initial release of the `bakalari` distribution: an unofficial Python client, CLI and MCP server for
+Bakaláři REST API v3, using only the standard library and supporting Python 3.9 through 3.14.
+
+### Added
+
+- MCP server mode through `bakalari mcp`, `bakalari-mcp` and `python -m bakalari.mcp`, with no new runtime
+  dependencies and Python 3.9 support. The stdio server provides 50 read tools across the API modules and school
+  directory, plus 11 opt-in write tools with `--allow-writes`.
+- Explicit tool schemas and validation, protocol/version negotiation, structured results, redacted errors,
+  bounded stdio frames, base64 attachment transfers, and automatic CLI session renewal/persistence.
+- MCP setup and tool reference in `docs/mcp.md`, including macOS/Linux and Windows setup, multiple accounts,
+  read/write workflows, attachment examples, troubleshooting, an offline connection check and Python integration.
+  README, CLI and library guides link to the full usage guide.
+- Offline MCP protocol/integration tests and a CI interoperability check using the official MCP Python client.
+
+#### Client
+
+- `BakalariClient` logs in like the official mobile app (the OAuth2 password grant on `POST /api/login`, client id
+  `ANDR`) on the first request that needs a token, renews the access token with the refresh token `renew_margin`
+  seconds (60) before it expires, renews and retries once after HTTP 401, and logs in again with the password when
+  the refresh token is rejected. `login()`, `refresh()`, `ensure_token()`, `logout()`, `token_info` (`TokenInfo`:
+  user id, scope, API version, expiry; never a token) and `is_authenticated` give explicit control, and a `with`
+  block logs out at its end.
+- `BakalariClient.from_env()` reads the address from `BAKALARI_URL` and the login from `BAKALARI_USERNAME` and
+  `BAKALARI_PASSWORD`, or from other variables with `username_env=` and `password_env=` (e.g. another child's login).
+- Sessions: `export_session()` and `import_session()` with `SessionState` (`to_dict()` and `from_dict()`), a client
+  started from a `refresh_token` alone, and the `on_session_update` callback after every login and renewal, so that
+  an application can keep the newest refresh token and continue without the password.
+- Retries: `retries` (0 by default) repeats `GET`, `PUT` and `DELETE` requests after a connection error or HTTP 502,
+  503 or 504, waiting `retry_backoff` (0.5 s) and twice as long before each further retry; `POST` requests, logins
+  included, are never repeated. `timeout` (30 s) applies to every request.
+- Transports: the default `urllib_transport()` (no cookie jar, the usual proxy variables, an optional `ssl_context`)
+  or any function with the `Transport` signature that returns an `HttpResponse`, e.g. canned answers in tests.
+- `normalize_base_url()` accepts an address copied from the browser: it adds `https://` and drops a page path, a
+  query and a trailing slash. Every request sends `Accept-Language: cs`, without which some installations answer
+  HTTP 500.
+- Raw access with the same token handling: `request()` (any method, query parameters, a form, JSON or raw body,
+  extra headers, an expected status or a set of them), `get_json()`, `post_json()`, `api_version()` and
+  `available_api_versions()`.
+- One client can be shared between threads: a lock guards the tokens.
+- Logging through the `bakalari.client` and `bakalari.schools` loggers: the method, path and status of every
+  request, the logins, renewals and retries.
+
+#### Typed models and contract checks
+
+- The responses become dataclasses based on `Model` (frozen, except `Timetable`), with `to_dict()` (JSON-ready data)
+  and `raw` (the server's object, for the keys a model does not map). Ids are kept exactly as sent, space padding included, and
+  percent-encoded in paths; display strings are trimmed; timestamps are timezone-aware `datetime` objects and
+  calendar days `date` objects; decimal commas are understood; missing and `null` fields get defaults.
+- `Item` for the `{Id, Abbrev, Name}` objects, `AttachmentInfo`, `format()` methods for readable one-line output, and
+  `from_json()` class methods and `parse_...()` functions for offline parsing.
+- Contract checks: the methods with a `validate` parameter (true by default) check the essential shape of each
+  payload and raise `BakalariContractError` listing every problem (`TimetableContractError` for timetables). A body
+  that is not JSON, such as an HTML error page with HTTP 200, is a contract error too, and counters must be numbers.
+  `validate=False` parses leniently.
+- Errors: `BakalariError` and its subclasses `BakalariConfigError`, `BakalariConnectionError`, `BakalariContractError`
+  and `BakalariHTTPError`, which has `method`, `path`, `status`, `expected`, `body` and the server's `message`, and
+  the subclasses `BakalariAuthError`, `BakalariPermissionError` (HTTP 403: a module or right is missing, or the
+  endpoint is for teachers) and `BakalariNotFoundError` (HTTP 404). Wrong arguments raise `ValueError` or `TypeError`
+  before any request.
+
+#### Endpoints
+
+Typed methods for 71 endpoints, one module per area. docs/endpoints.md lists every known endpoint with its
+verification status: 41 of the 71 were verified against a live installation and 23 more by route and method.
+
+- Account (`bakalari.user`): `user_profile()`, which returns a `UserProfile` (user type, names, class, school, school
+  year and semester, the students of a parent account, the modules and rights with `has_module()` and
+  `has_right()`), `enabled_modules()`, `student_at_school()`, `web_modules()`, `login_token()`, `web_login_url()` (a
+  one-time link that opens the Bakaláři web logged in) and `register_notification()`.
+- Timetable (`bakalari.timetable`): `actual_timetable()`, `permanent_timetable()`, `class_timetable()` (a whole
+  class with all its groups) and `timetable_json()`, with the lessons' homeworks, notices, week themes and times.
+- Substitutions (`bakalari.substitutions`): `substitutions()`, the changes of 14 days grouped by day.
+- Marks (`bakalari.marks`): `marks()` (optionally only `since` a date), `new_marks_count()`, `final_marks()`,
+  `pedagogical_measures()`, the what-if prediction of an average with `predict_marks()` and `what_if()`, and
+  `confirm_marks()` for parents.
+- Absence (`bakalari.absence`): `absence()` per day and per subject with the school's percentage threshold.
+- Subjects (`bakalari.subjects`): `subjects()` with the teachers and their contacts, `subject_themes()` (with the
+  alternative route for ids a URL path cannot carry) and `find_subject()`.
+- Homeworks (`bakalari.homeworks`): `homeworks()`, `active_homeworks_count()` and `set_homework_done()`.
+- Komens messages (`bakalari.komens`): `messages()` of the received, sent, noticeboard, apology and rating folders
+  (optionally only `since` a date), `message()`, `unread_messages_count()`, `mark_message_read()`,
+  `confirm_message()`, `hide_message()`, `unhide_message()`, `delete_message()`, `message_types()` (also for a
+  reply), `send_message()`, `reply_to_message()`, `upload_attachment()`, `download_attachment()` with
+  `AttachmentFile.save()`, and `rating_templates()`. `Message.plain_text` turns the HTML body into readable text.
+- Events (`bakalari.events`): `events()` of the whole school, the user's own or the public ones.
+- GDPR (`bakalari.gdpr`): `consents()`, `child_consents()`, `new_consents_count()` and `gdpr_commissioners()`.
+- Payments (`bakalari.payments`): `class_fund_summary()`, `class_fund_payments()`, `class_fund_payment_info()` with
+  the IBAN and the Czech QR payment (SPAYD) string, `regular_payments_summary()`, `account_to_iban()` and
+  `format_iban()`.
+- Teacher accounts (`bakalari.teacher`): `classbook()`, `save_classbook_record()`, `lesson_tags()`,
+  `lesson_absence()`, `lesson_past()`, `lesson_students_timetable()`, `marking_atoms()`, `marking_marks()` and
+  `emergency_configuration()`.
+- Public timetables (`bakalari.public_timetable`, no login): `public_timetable_targets()`, `public_timetable()` and
+  `public_timetable_url()` for classes, teachers and rooms, from the newer and the older page layouts, and
+  `parse_public_targets()` and `parse_public_timetable()` for saved pages.
+- School directory (`bakalari.schools`, no login): `SchoolDirectory` with `municipalities()`, `schools()` and
+  `find()`, which ignores case and diacritics, to find a school's Bakaláři address.
+
+#### Command line
+
+- The `bakalari` command (also `python -m bakalari`) with 38 commands, grouped by area in `bakalari --help`: public
+  data (`version`, `schools`, `public-timetable`), the account and the session (`login`, `logout`, `profile` with the
+  alias `whoami`, `modules`, `web-login`, `web-modules`, `at-school`), `timetable`, `substitutions` and `events`,
+  marks (`marks`, `final-marks`, `measures`, `predict`, `confirm-marks`), `absence`, `subjects`, `homeworks` and
+  `homework-done`, Komens messages (`messages`, `message`, `message-types`, `send-message`, `reply`,
+  `confirm-message`, `hide-message`, `delete-message`, `attachment`), `consents`, `commissioners` and `class-fund`,
+  teacher accounts (`classbook`, `lesson-tags`, `marking`), and raw requests to any endpoint (`api`).
+- Global options `--base-url`, `--username-env`, `--password-env`, `--session-file` (or `BAKALARI_SESSION_FILE`),
+  `--timeout` (30 s), `--retries` (2), `-v` and `--version`. Most commands accept `--json` and then print JSON
+  instead of text, and dates are `YYYY-MM-DD`, `today`, `yesterday` or `tomorrow`.
+- The session file keeps the session between commands, so the password is needed only after the refresh token has
+  expired. It works without the login variables, which then serve as the fallback for a rejected refresh token.
+- The commands that change data are marked in the help, do exactly what the command line says and print what they
+  did. `send-message` checks the command line against the account's message types before it uploads or sends
+  anything.
+- Exit status 0 on success, 1 for an API, connection or contract error, with a hint where the cause is likely (e.g.
+  a module that is not enabled, or an endpoint for teacher accounts), 2 for a usage or configuration error and 130
+  when interrupted. docs/cli.md is the complete reference.
+
+#### Package and documentation
+
+- The package exports the client, the errors, every model class and the main helpers from `bakalari`, ships
+  `py.typed` and has no runtime dependencies.
+- Documentation: the README, the library guide (docs/library.md, every method and model), the command line reference
+  (docs/cli.md), the endpoint coverage (docs/endpoints.md) and runnable examples: the weekly timetable, new marks,
+  unread messages with their attachments, homeworks as an iCalendar file, a persistent session, the class fund QR
+  payment and the school search.
+- An offline test suite with a scripted transport and synthetic fixtures, which CI runs on Python 3.9 to 3.14 on
+  Linux and on Python 3.13 on macOS and Windows with at least 90 % coverage, and read-only live tests that run only
+  when `BAKALARI_URL`, `BAKALARI_USERNAME` and `BAKALARI_PASSWORD` are set.
+
+### Changed
+
+- Rename the repository and Python distribution from `bakalari-api` to `bakalari`. Install with
+  `python -m pip install bakalari`; the Python import and the `bakalari` and `bakalari-mcp` commands stay the same.
+- Use `bakalari` in CLI version output, MCP server identity, release metadata, documentation and calendar exports,
+  and `bakalari-python/<version>` in the default HTTP User-Agent.
+
+- The login variables are `BAKALARI_USERNAME` and `BAKALARI_PASSWORD` instead of `BAK_PTRK_USERNAME` and
+  `BAK_PTRK_PASSWORD`.
+- The school's address is required: set `BAKALARI_URL` or pass `base_url` (`--base-url` on the command line). There
+  is no default school any more.
+- `user_profile()` returns a typed `UserProfile` instead of the raw dict; the server's object is its `raw` field.
+- The timetable models `Timetable`, `Day`, `Lesson`, `Hour` and `Change` are `Model` dataclasses with new fields;
+  the existing fields keep their meaning, and `Lesson.to_dict()` keeps its keys and adds `notice`, `week_theme` and
+  `homeworks`.
+- `request()` also sends `PUT`, `DELETE` and `PATCH` requests, JSON and raw bodies and extra headers, and accepts a
+  set of expected statuses or `None` for any. HTTP 403 and 404 raise `BakalariPermissionError` and
+  `BakalariNotFoundError`, which are `BakalariHTTPError` subclasses, so existing handlers keep working.
+- The command line was rewritten; `timetable` keeps its options and output. `bakalari.cli.main()` returns the exit
+  status 2 for a usage error instead of letting `SystemExit` escape, and `-v` configures only the package's loggers
+  instead of the root logger.
+- Split automation into **Python Package CI** (`python-package.yml`) and **Python Package Publish**
+  (`python-publish.yml`), replacing the previous CI and tag-push publishing workflows. Publishing a GitHub
+  release, or manually running the publish workflow from its matching tag, validates the release, runs reusable
+  CI and publishes its checked distributions through the `pypi` environment using PyPI trusted publishing.
+- Validate that the release tag matches the package version, the changelog has a dated, non-empty release
+  section, and no changes remain under "Unreleased" before publishing.
+- Collect both `unittests/` and `tests/` in CI with live tests explicitly disabled, including official MCP SDK
+  interoperability and release-validation regression tests. Retain test and coverage reports for 30 days.
+- Check wheel and source-distribution contents, typed-package metadata and installed command entry points;
+  keep repository tooling, local state, caches and generated reports out of distributions.
+- Update contributor documentation for the workflow migration, required checks, PyPI trusted-publisher setup
+  and release validation.
+
+### Fixed
+
+- Fall back to the ordinary attachment filename when the server sends a malformed extended filename header.
+- Remove duplicate legacy tests whose missing helper imports broke full test discovery.
+- Pass the coverage configuration explicitly in CI so subprocesses running outside the checkout use the same
+  branch-coverage settings and their results can be combined successfully.
+
+### Security
+
+- Block redirects to another origin for requests carrying an Authorization header or body, including login
+  requests, and reject HTTPS downgrades. Public HTTP(S) redirects remain supported.
+- Remove query strings and fragments from request paths in logs, HTTP errors and JSON contract errors, so raw
+  request paths cannot expose query tokens in diagnostics.
+- Reject malformed installation URLs and embedded URL credentials before they can appear in diagnostics.
+- Redact known passwords and access/refresh tokens echoed in upstream HTTP error bodies, including nested values.
+- Keep stored passwords and tokens in private attributes and exclude token payloads from `repr()`. Request logs
+  omit query strings and bodies, and connection error messages omit query strings that can carry push tokens.
+- TLS certificates are verified by default, and there is no cookie jar, because the API is stateless.
+- The command line writes the session file atomically with mode 0600, restricts a session file that other users
+  can read when it loads it (on POSIX systems), refuses a file that is not a Bakaláři session, and `logout`
+  deletes nothing but a Bakaláři session file.
+- Text output removes the C0 and C1 control characters from server strings (titles, names, message bodies, file
+  names) and JSON output escapes them, so a server cannot send escape sequences to the terminal.
+- `AttachmentFile.save()` and the `attachment` command sanitize the server's file name (no directory parts, control
+  characters, Windows device names or hidden files) and never overwrite a file unless asked to.
+- `web-login` warns that its one-time link is a credential. Reading a message never marks it as read. The live tests
+  call no endpoint that changes data and never log in with a wrong password for a real user, because Bakaláři shows
+  failed logins to the account owner.
+
+### Known limitations
+
+- The REST API is not officially documented and may change without notice.
+- Not verified against a live server: the teacher endpoints (no teacher account was available), the payments
+  payloads (the module was disabled at the test school), the timetable pages of a school that publishes them, and
+  the write endpoints (sending, replying, confirming, hiding and deleting messages, uploading attachments,
+  confirming marks, ticking homeworks, saving class-book records, registering a push token), which were checked by
+  route and method only. Their models follow the community documentation, other clients and captured traffic, and
+  keep the server's objects in `raw`.
+- 17 known endpoints have no typed method, mostly because their requests are undocumented (Komens drafts, consent
+  answers, emergency alarms, teacher payment prescriptions, class-book attendance writes, the student timetable);
+  `request()` and `bakalari api` reach them. Consents can be answered and homeworks handed in electronically on the
+  Bakaláři web only.
+- `register_notification()` needs the official app's push token, so a third-party token receives no notifications;
+  poll the counters instead. `new_marks_count()` is often 0 even when marks are flagged new.
+- `predict_marks()` takes classic marks only; hypothetical point marks need `what_if()`.
+- `send-message` and `reply` turn plain text into HTML (escaped, line breaks as `<br>`), assuming that the server
+  stores messages as HTML like the web editor does; `--html` sends the text unchanged.
+- `class_timetable()` was verified for the account's own class only; the timetable of another class may be refused.
+- Two commands that renew the same session file at the same moment can race, because the file is not locked.
+
+[Unreleased]: https://github.com/robco/bakalari/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/robco/bakalari/releases/tag/v1.0.0

bakalari-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Code of conduct
+
+This project adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
+as its code of conduct. It applies to everyone who takes part in the project, in issues, pull requests, reviews
+and every other project space, and to anyone who represents the project in public.
+
+## In short
+
+We want taking part in this project to be a harassment-free experience for everyone. We expect you to:
+
+- be respectful and kind, and welcome people of every background and level of experience;
+- give and accept constructive feedback gracefully, and focus on what is best for the project and its users;
+- respect privacy. This project works with the school records of children: never publish anyone's personal data,
+  and keep data from a Bakaláři account (names, marks, absences, messages) out of issues, pull requests and
+  fixtures.
+
+Not acceptable:
+
+- harassment, insults, and derogatory or discriminatory comments;
+- personal or political attacks, trolling;
+- sexualized language or imagery, and unwelcome sexual attention;
+- publishing other people's private information without their explicit permission;
+- other conduct that could reasonably be considered inappropriate in a professional setting.
+
+## Reporting and enforcement
+
+Report unacceptable behaviour privately to the project maintainer, Róbert Malovec, through the repository's
+private reporting form ([Report a vulnerability](https://github.com/robco/bakalari/security/advisories/new))
+with a title that starts with "Code of conduct". Every report is reviewed promptly and fairly, and the reporter's
+privacy is respected.
+
+The maintainer enforces this code of conduct following the Contributor Covenant's
+[enforcement guidelines](https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines):
+a correction, a warning, a temporary ban or a permanent ban, depending on the impact. Content that breaks GitHub's
+terms can also be
+[reported to GitHub](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam).

bakalari-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,197 @@
+# Contributing to bakalari
+
+Thank you for helping. This guide covers the development setup, the tests, the code conventions and the release
+process. By taking part you agree to follow the [code of conduct](CODE_OF_CONDUCT.md). Report security problems
+privately as described in [SECURITY.md](SECURITY.md), never in a public issue.
+
+## Development setup
+
+You need Python 3.9 or newer. The package has no runtime dependencies. Test your changes on the oldest supported
+Python (3.9) and on the newest.
+
+```bash
+git clone https://github.com/robco/bakalari.git
+cd bakalari
+python3 -m venv .venv
+source .venv/bin/activate              # Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]"
+```
+
+mypy stays below version 2 because mypy 2 can no longer check code against Python 3.9 (`python_version` in
+`pyproject.toml`).
+
+## Tests
+
+### Offline tests
+
+The offline suite needs no network and no account. It drives the client through a scripted transport
+(`FakeTransport` in `unittests/support.py`) and uses the synthetic fixtures in `unittests/fixtures/`.
+
+```bash
+python -m pytest                                      # the whole offline suite
+python -m unittest unittests.test_marks -v             # one test module, no test dependencies
+python -m pytest --cov=bakalari --cov-fail-under=90    # CI coverage threshold
+```
+
+The default pytest discovery path is `unittests/`, so it never selects live tests even when credentials are
+present. Without third-party test tools, run `python -m unittest discover -s unittests -t . -v`.
+
+### MCP SDK interoperability
+
+On Python 3.10 or newer, install the optional reference client and run the offline interoperability test:
+
+```bash
+python -m pip install -e ".[dev,mcp-test]"
+python -m pytest tests/test_mcp_sdk.py
+```
+
+CI runs this test alongside the unit tests under coverage. It uses synthetic school responses and requires no
+account. The installed library and MCP server still have no runtime dependencies.
+
+### Live tests (read-only)
+
+`tests/test_live.py` runs against a real Bakaláři installation when all three variables are set and
+`BAKALARI_SKIP_LIVE` is not:
+
+```bash
+export BAKALARI_URL=https://...        # the address of your school's Bakaláři web
+export BAKALARI_USERNAME=...
+export BAKALARI_PASSWORD=...
+python -m unittest tests.test_live -v
+```
+
+Set `BAKALARI_SKIP_LIVE=1` to skip them even when the credentials are set. CI never runs them. The rules for
+live tests:
+
+- **They never change data.** No marking messages as read, no sending messages, no confirming marks, no marking
+  homework as done, no consent changes, no notification registration: only read endpoints.
+- **They never use a wrong password with a real username.** Bakaláři counts failed logins and shows them to the
+  account owner at the next login. The negative login test uses a random, unknown username.
+- They assert structure only (types, non-negative counters, parsing with validation on), never concrete personal
+  values, and they skip (`skipTest`) when the school or account has a module disabled (`BakalariPermissionError`).
+- Their output can contain personal data. Don't paste it into issues or pull requests unless it's redacted.
+
+## Fixture privacy rule
+
+Fixtures are synthetic. Copy the **shape** of a real response (keys, nesting, value types, enum values,
+space-padded ids, empty and null fields) but never its values. Invent the names, ids, texts, marks and dates, and
+use `https://school.example/bakaweb` as the address. Never commit a real name, id, school, message text or token,
+not even from your own account, and never commit a captured response with the plan to anonymize it later.
+
+## Code conventions
+
+The package uses only the standard library and runs on Python 3.9. Keep `from __future__ import annotations` and
+the `typing` style (`Optional`, `Dict`, `List`, `Tuple`, `Mapping`). Don't use `match`, `X | Y` at runtime,
+`dataclass(slots=..., kw_only=...)`, `zip(strict=...)` or `datetime.UTC`.
+
+1. **One module per Bakaláři area** (`marks.py`, `komens.py`, ...) holds the area's response models and its
+   `XxxEndpoints(ClientCore)` mixin, which `BakalariClient` combines. Endpoint methods are thin: they build the
+   path (ids go through `quote_segment`), call `get_json`, `post_json` or `request`, and parse the result with the
+   model's `from_json`.
+2. **Models** are `@dataclass(frozen=True)` subclasses of `Model` with a `from_json` classmethod. Entity models end
+   with a `raw` field holding the original object, which is hidden from `repr()` and `to_dict()`. Field names are
+   the snake_case API names (`school_class` for `Class`), and collections are tuples.
+3. **Values** go through the `bakalari._parse` helpers: ids exact (`ident`), display strings trimmed (`text`),
+   timestamps as aware `datetime` (`parse_datetime`) or `date` (`parse_date`), numbers and booleans via
+   `to_int`, `to_float` and `to_bool`, `{Id, Abbrev, Name}` objects as `Item`, and attachments as
+   `AttachmentInfo`. Parsing is lenient: a missing optional field gets a default.
+4. **Contract checks**: a top-level `from_json(data, *, validate=True)` checks the essential shape with
+   `check_shape` when it validates, and with `require_mapping` or `require_list` always. Endpoint methods take
+   `validate: bool = True` and pass it on. Counter endpoints use `require_int`.
+5. **Dates in requests** are formatted with `format_date`. Date parameters are named `since` and `until` and
+   accept a `date`, a `datetime` or an ISO string.
+6. **Docstrings** in English on every public class and method: one or two sentences naming the HTTP method and
+   path (``GET /api/3/marks``) and notable server behaviour. Comments only explain non-obvious server quirks.
+7. **Errors** are never swallowed. Endpoints that need a module or a right let `BakalariPermissionError`
+   propagate. Tokens and passwords never appear in messages, log records or `repr()`.
+8. **Tests** are offline and deterministic (`unittest`), one test module per area module (`unittests/test_marks.py`),
+   with synthetic fixtures `unittests/fixtures/<area>*.json`. They cover model parsing (padded ids, nulls, missing
+   fields), `to_dict()` JSON round trips, the HTTP method, path (including percent-encoded ids), query and body of
+   every endpoint method, status handling, contract errors and lenient parsing.
+
+## Lint and type check
+
+```bash
+ruff check .        # pycodestyle, pyflakes, isort, bugbear and comprehensions; line length 120
+mypy bakalari       # the settings in pyproject.toml, checked against Python 3.9 (needs mypy < 2)
+```
+
+Ruff's pyupgrade (`UP`) rules are off on purpose, so that the `Optional[...]` typing style stays.
+
+To check the packaging the way CI does:
+
+```bash
+python -m build
+twine check --strict dist/*
+```
+
+## Pull requests
+
+Keep a pull request focused on one change, add tests, update the documentation and add an entry to
+`CHANGELOG.md` under "Unreleased". CI runs the offline tests on Python 3.9 to 3.14 on Linux and on Python 3.13 on
+macOS and Windows, checks coverage (at least 90 %), runs ruff and mypy, and builds the package, checking the wheel
+by installing it into a fresh virtual environment. Python 3.12 runs the combined test/build job, which also
+checks the MCP SDK and uploads JUnit, HTML and coverage reports. The remaining matrix jobs use only the standard
+library to check compatibility.
+
+## Release process
+
+Versions follow [Semantic Versioning](https://semver.org/). The version is set in one place,
+`bakalari/_version.py`. Setuptools reads that value for the distribution, and the library, CLI and MCP server
+use it at runtime. The filename is a project convention, not a GitHub Actions or PyPI requirement
+
+1. Set `__version__ = "X.Y.Z"` in `bakalari/_version.py`.
+2. In `CHANGELOG.md`, rename "Unreleased" to `## [X.Y.Z] - YYYY-MM-DD`, add a new empty "Unreleased"
+   section above it, and update the link references at the bottom.
+3. Commit the changes, push to `main`, and wait for **Python Package CI** to pass.
+4. Create and push the release tag:
+
+   ```bash
+   git tag -a vX.Y.Z -m "bakalari X.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+5. On GitHub, publish a release for that tag and use the changelog section as its release notes. The
+   [Python Package Publish workflow](.github/workflows/python-publish.yml) starts on `release: published`.
+   It builds the wheel and source distribution, uploads them as `release-dists`, then publishes them to PyPI.
+   A tag push alone does not publish a package.
+
+Publishing does not rerun CI or enforce tag naming or changelog formatting. The package version comes from
+`bakalari/_version.py` in the selected checkout, regardless of the branch, tag or release name.
+CI runs tests, lint, type and distribution checks separately; its `python-package` artifact and test and
+coverage reports are retained for 30 days. The publish job uses the `pypi` environment and OpenID Connect
+trusted publishing to upload the distributions from its own build job.
+
+To publish manually, select a branch or tag in GitHub's **Run workflow** dialog, or use:
+
+```bash
+gh workflow run python-publish.yml --ref main
+# Or publish a specific tag:
+gh workflow run python-publish.yml --ref vX.Y.Z
+```
+
+A manual run also publishes to **PyPI**. PyPI accepts each distribution filename only once; bump the package
+version before a new release and check a partially completed upload before retrying. For a local build
+check without publishing, use `python -m build`, `python -m twine check --strict dist/*` and
+`python .github/scripts/check_distribution.py`.
+
+### First-time setup and migration
+
+1. On GitHub, create the `pypi` environment (Settings, Environments). Allow the branches and tags you intend
+   to publish from; remove any tag-only restriction if you want manual publishing from `main`.
+2. Configure a [PyPI trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/):
+   - PyPI project: `bakalari`
+   - Owner: `robco`
+   - Repository: `bakalari`
+   - Workflow filename: `python-publish.yml`
+   - Environment: `pypi`
+
+   If the project does not exist, add a pending publisher in the account's Publishing settings. No API token
+   is needed. If migrating from the previous workflow, replace the publisher for `release.yml` with the one
+   above; PyPI matches the workflow filename exactly.
+3. If branch protection requires the old CI job names, update those required checks to the checks reported by
+   **Python Package CI**, including the compatibility matrix and **Test & Build (Python 3.12)**.
+4. The old tag-push publisher and manual TestPyPI rehearsal are replaced by this release-based workflow.
+   The `testpypi` environment and its publisher are no longer used.
+5. Enable private vulnerability reporting (Settings, Advanced Security, Private vulnerability reporting), which
+   SECURITY.md and the issue forms link to.

bakalari-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Róbert Malovec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bakalari-1.0.0/MANIFEST.in

@@ -0,0 +1,19 @@
+# Source distribution contents in addition to what setuptools adds by itself
+# (the bakalari package with py.typed, README.md, LICENSE and pyproject.toml).
+include CHANGELOG.md CONTRIBUTING.md SECURITY.md CODE_OF_CONDUCT.md
+graft unittests
+graft tests
+graft docs
+graft examples
+
+# Never ship repository tooling, local agent state, build output, caches or secrets.
+prune .github
+prune .claude
+prune build
+prune dist
+prune htmlcov
+prune .mypy_cache
+prune .ruff_cache
+prune .pytest_cache
+prune reports
+global-exclude *.py[cod] .DS_Store .env *.session.json