librus-python-api 1.0.0__py3-none-any.whl

librus_python_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.5
+Name: librus-python-api
+Version: 1.0.0
+Summary: Independent bounded async Librus Synergia client
+Project-URL: Repository, https://github.com/krzysztofbury/librus-python-api
+Project-URL: Issues, https://github.com/krzysztofbury/librus-python-api/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp<4,>=3.14.2
+Requires-Dist: lxml<7,>=6.1
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: pywin32<400,>=312; sys_platform == 'win32'
+Requires-Dist: tzdata>=2026.5; sys_platform == 'win32'
+Requires-Dist: yarl<2,>=1.20
+Description-Content-Type: text/markdown
+
+# librus-python-api
+
+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](contracts/persistence.md#windows-disk-boundary-25).
+
+**Status:** `1.0.0` freezes the documented native library API. It does not claim
+completed MCP cutover, production-state migration or universal live-school
+compatibility. Those consumer/live gates remain separate. School features depend
+on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
+See [limitations](#supported-features-and-limitations) below.
+
+## Install
+
+Install the exact release from PyPI after its gated publication completes:
+
+```sh
+python -m pip install librus-python-api==1.0.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:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+```
+
+To install a locally built wheel instead:
+
+```sh
+python -m pip install ./dist/librus_python_api-1.0.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:
+
+```sh
+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:
+
+```python
+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:
+
+```python
+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)
+```
+
+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][api].
+
+### 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
+
+```python
+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
+5 requests/second, a burst of 10 and two simultaneous requests across the service.
+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][api] 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][upgrade] 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, 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 and observation
+cards 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][verification] and [roadmap][roadmap].
+
+## Development and support
+
+Use a repository checkout for tests and development tools; they are deliberately
+excluded from published source archives. See [CONTRIBUTING.md][contributing] for
+setup and offline checks. Report bugs through [GitHub Issues][issues] and security
+concerns according to [SECURITY.md][security]. Do not attach credentials or raw
+school data to public reports.
+
+MIT licensed. See [LICENSE][license].
+
+[api]: https://github.com/krzysztofbury/librus-python-api/blob/main/API.md
+[upgrade]: https://github.com/krzysztofbury/librus-python-api/blob/main/contracts/account-context.md
+[verification]: https://github.com/krzysztofbury/librus-python-api/blob/main/VERIFICATION.md
+[roadmap]: https://github.com/krzysztofbury/librus-python-api/blob/main/TODO.md
+[contributing]: https://github.com/krzysztofbury/librus-python-api/blob/main/CONTRIBUTING.md
+[issues]: https://github.com/krzysztofbury/librus-python-api/issues
+[security]: https://github.com/krzysztofbury/librus-python-api/blob/main/SECURITY.md
+[license]: https://github.com/krzysztofbury/librus-python-api/blob/main/LICENSE

librus_python_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+librus_python_api/__init__.py,sha256=ErEyS0CIPgmEIHzURu8MnaZ-rwFiRexLujZnv5cyY_8,5657
+librus_python_api/_notification_bootstrap.py,sha256=18nzH0doXBNaZXCz-_ckIvRrlHTWV5Mm1t5m2-5eYGI,4669
+librus_python_api/_notification_codec.py,sha256=hU6G3zGJ5fR8wfPC6fV2OqBKs-7XpT9eRnKO3FGsTzY,13451
+librus_python_api/_storage.py,sha256=vh6O3X7e5ZNJf2GKU3Cz5PxhHn4D_nv7U7YvcoQV57s,15661
+librus_python_api/_windows_filesystem.py,sha256=pQANIGkYrb4Q75gz5mdr5mqYhM_PFblWwTxPGM0bQ78,14063
+librus_python_api/announcements.py,sha256=13FoOR1sq7tt9w6aLf0vclcFKDqLUiIYaO5iYD2QVLA,5928
+librus_python_api/attachment_routes.py,sha256=uSg5wCQqHJiphF0KdI0GatQxZr5SLUx6xWQRsl_U4_U,4123
+librus_python_api/attachments.py,sha256=kyIBpFxeK34Al5_jCkxYKpZnsSLa5DYaGS6vHADpy_g,10921
+librus_python_api/attendance.py,sha256=HeFAfnIUn4N__yp1zr635Dve55S2jmwtkeIy_6mV5B4,6924
+librus_python_api/attendance_frequency.py,sha256=VAXZksSbE_o3fhP9vnN3_y0CCFQATFf6EOYhLQn-Fk8,3426
+librus_python_api/budget.py,sha256=8fvqT7eIxyVX2P2OBG27XsYHk_HbtSS4lzuecYpHtgs,2878
+librus_python_api/checkpoint.py,sha256=QBmG9GtpyaGRaFq-FXuGA3yR1BjuMFN9V3RTvvi_FNQ,1930
+librus_python_api/completed_lessons.py,sha256=sR2oLSGb2q1580l-2upCBv9sQfIcHi7CQfWr1K0EFXI,7635
+librus_python_api/config.py,sha256=uXadjaj_CONEt3RJkk6a8ErZAohGVoZRsR9lfMaUtrU,48422
+librus_python_api/detail_fields.py,sha256=K10Stx_ehDTttkUI7-G7a2Ko9exYEu5NJpR-3sBnQ60,1789
+librus_python_api/diagnostics.py,sha256=2l7wq6RA3it-Gwj-JRLcw5qbI37fl3xII6GZA2mZj0o,856
+librus_python_api/exceptions.py,sha256=yWWoo0xyrQAk1d13HOJZnQBsq4ulh_P0hRSI6ZiNQOE,4622
+librus_python_api/files.py,sha256=yVa1wvw2PwAWPix_ZDLokZ-_NTMuG8nStW7I3K6jAo4,8895
+librus_python_api/grade_parsers.py,sha256=91Kr1-TArzqO-b94ipeIR0a98OV7tRCZQdBWsd9QLZ0,6141
+librus_python_api/grade_records.py,sha256=HvGHQ8Fyx_1Ne5k6N8cBeTqrDCzM5P6saj8eijDbRA4,16793
+librus_python_api/homework_range.py,sha256=erYfvS6PhHU5XhnR6LkiLNy677hGVflY3UAuHOs-YUw,1663
+librus_python_api/lifecycle.py,sha256=XzA5CEdZFo7iL5IMUrawnRvf2m9BFe0OseP-fpQFaAE,856
+librus_python_api/markup.py,sha256=GZk7MmBBGB5SIVY_VngmQxQErI3eGHOpJs3mFVlMR3M,5298
+librus_python_api/message_content.py,sha256=sUPuqpjuavqDyn6QGM5aPH4mpoQV62bDLepSSQ2AsUE,8686
+librus_python_api/messages.py,sha256=K9F8XVs1SojfFpdxxLV8gx9E0g81YxEHjigDzLHmDCg,10230
+librus_python_api/models.py,sha256=DGbxwDymPjJsqRMtqIe2W9KCBXzNiVPhzeXVjPSC9iQ,33106
+librus_python_api/modern_body.py,sha256=3L4P_cIrHdIxZqiinFSQrDMhG6iklT1GoA-VEWMJUiI,2682
+librus_python_api/modern_mailbox.py,sha256=nRrmIHb7RfV49xjUTBlDcgtxOdmXEpp4F1L0IvcGQxw,16118
+librus_python_api/modern_messages.py,sha256=9gysqjUkQGtMKmnCL7boRzNDnAhtL5ibAJ2rkNZWCec,9694
+librus_python_api/notification_models.py,sha256=4eLTAE9JzHhveoaWtZQwGBolmb87QUP5kOSW7Jjt7J0,4199
+librus_python_api/notification_persistence.py,sha256=hXKmzAh0yNYG_n5CLlZOcoYOZdQnlrSeNtjjXiDmLm4,49532
+librus_python_api/notification_workflow.py,sha256=MsBJdwn6J1UUGlz3Ldzi7WEBz5Qsama7eGmZvUQj25g,12924
+librus_python_api/notifications.py,sha256=VbA8pqNG_19yYo9y7IqpGRmfEb4qDcvA5gBb1syGJKs,7806
+librus_python_api/parsers.py,sha256=OFztbUMDzCywq17BgfFT485bVjyOqLksFHQJthZCx5Q,8120
+librus_python_api/parsing.py,sha256=H71srw5yx-RFrAKZFgj-QFX-DIXZmhnGrDTmJhazCB8,1838
+librus_python_api/persistence.py,sha256=C5oDHQg1Xzy9Jb9obVsRNndCiXps-QQQtQ_M7_l5BBI,15546
+librus_python_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librus_python_api/recipients.py,sha256=6GQCKo-Zjg3VFSg1J8YXcDsy_U3r6-MUS4VCvz0xdaQ,10033
+librus_python_api/scheduler.py,sha256=3JplYxqvQdFz3aKXcoQUJHE9s3FPw_xRhQ2CPNLuQmA,10729
+librus_python_api/school_reads.py,sha256=PCnZ4lv44j-68FgJpQiMteaPSyfhbX8_3CUyE6zhFcQ,14760
+librus_python_api/sending.py,sha256=Nvvk2r-6D6Us53a2fH5GW9PcA6bWEfuOvy6c3M5QVcE,4549
+librus_python_api/service.py,sha256=a8EYBZBihVFe8moY_5SYjCtQSbcDrPwLA7vtcIopsqk,84209
+librus_python_api/timetable.py,sha256=tX1QK9fQABxzfLaHHqTe8e6rAgdOkCoTOfAHdPwNmLE,9836
+librus_python_api/transport.py,sha256=6S5wwBiRkUfKmi6w2t8msxlTSzCo-IbIBE13FeBc7Jw,35357
+librus_python_api-1.0.0.dist-info/METADATA,sha256=_7MctXX2lgQROYs4N-In7q7ZT5vAbKNU3BfQchDQ8Rg,11514
+librus_python_api-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+librus_python_api-1.0.0.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
+librus_python_api-1.0.0.dist-info/RECORD,,

librus_python_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

librus_python_api-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krzysztof Bury
+
+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.