Wilhelmina - Wilma API Client
A Python API client for the Wilma school platform. This client allows you to authenticate, fetch messages, and view message contents from the Wilma platform.
Why is this not called Wilma? The reason is simple, PyPi sees "Wilma" as a prohibited packages name. It is not taken on PyPi, it just is not allowed. Wilhelmina is the long/full version of the name Wilma which is the reason for the name.
Wilma API Features
The client is read-only: logging in is the only non-GET request it makes.
- Messages
- List all messages in a folder (inbox, archive, outbox, drafts, appointments)
- Unread status (from the list endpoint's
Statusfield) - Get a single message with content and replies
- Lesson marks ("Lektionsanteckningar" / "Tuntimerkinnät")
- Absences, lateness, positive feedback, missing homework, behaviour notes, etc.
- Mark types with code, description and Wilma's colour for each
- Predefined ranges (four weeks, autumn, spring, periods, school year) or any date range
- Schedule
- Lessons of any Monday-to-Sunday week (holidays and days off included), with subject, teachers, rooms and times
- School terms
- Bulletins (the school's bulletin board): current, pinned and older bulletins, and single bulletins with their content
- Exams of the current courses, upcoming and past: date, subject, what the exam covers, teachers, and the grade (and verbal assessment) once graded
- Current courses with their teachers, homework and lesson diary notes
- Multiple students:
get_students()lists the account's children; every data method takes auser_idto read that student's data - Roles of the account (e.g. one guardian role per child)
Things to know about Wilma
- Opening a message marks it as read.
get_message_content()andget_messages(with_content=True)mark every fetched message as read in Wilma, and Wilma has no way to mark a message unread again. Listing messages does not change read status. - One session per account. Logging in invalidates all other sessions for the same user (browser, mobile app, other clients). The client logs in again by itself if its own session gets invalidated.
- The list endpoints return every message in the folder in a single response; the pagination in the web UI is client-side only.
- Lesson marks have no JSON endpoint; they are parsed from the attendance view's HTML.
- Reading exams, homework and courses (the student's overview) does not mark grades as seen. The library does not read the grade book.
- Timestamps are naive Finnish local time. Timezone-aware
after=values are converted to the client'stimezone(defaultEurope/Helsinki).
Home Assistant compatibility
This library has support for passing in an existing aiohttp to allow for easier integration with
Home Assistant. The version of aiohttp has also been slightly restricted in order to be installable
in Home Assistant. mashumaro was chosen for type safe models instead of Pydantic to not need to
go through the v1 vs. v2 hassle.
Note about AI
Sonnet 3.7 has written a lot code in this repository. Far from one-shotted however and a lot of refactoring has been done in order to get things into this state. The main purpose for creating this library was to get quick access to the Wilma API through Python.
Installation
pip install wilhelmina
# Using Poetry
poetry add wilhelmina
API Client Usage
import asyncio
import datetime
from wilhelmina import AttendanceRange, MessageFolder, WilmaClient
async def main():
# Optionally pass in an existing aiohttp session; it will not be closed by the client
async with WilmaClient("https://turku.inschool.fi") as client:
await client.login("username", "password")
# All inbox messages, newest first. Does not change read status.
messages = await client.get_messages()
for msg in messages:
status = "UNREAD" if msg.unread else "read"
print(f"{msg.id}: {msg.subject} - {msg.timestamp} - {msg.sender} - {status}")
# Only unread messages
unread = await client.get_messages(only_unread=True)
# Other folders
sent = await client.get_messages(folder=MessageFolder.OUTBOX)
# Full content and replies. NOTE: this marks the message as read in Wilma.
if unread:
content = await client.get_message_content(unread[0].id)
print(content.content_markdown)
for reply in content.reply_list:
print(reply.sender, reply.content_markdown)
# Lesson marks for the school year (or AttendanceRange.FOUR_WEEKS, start=/end=, ...)
report = await client.get_attendance(AttendanceRange.SCHOOL_YEAR)
for mark in report.marks:
print(mark.date, mark.hour, mark.type.code, mark.type.color, mark.course, mark.comment)
# Mark types are configured per school; e.g. positive feedback uses the code "+"
positive = report.marks_with_code("+")
latest = report.latest # mark on the latest date and hour
# Each mark has a stable `key` (Wilma has no mark IDs), e.g. to detect new marks
seen: set[str] = set() # persist this between runs
new_marks = [m for m in report.marks if m.key not in seen]
# Schedule: the week containing a date (default today)
week = await client.get_schedule()
for lesson in week.lessons_on(client.today()):
print(lesson.start, lesson.end, lesson.subject, lesson.teachers, lesson.rooms)
next_week = await client.get_schedule(week.week_start + datetime.timedelta(days=7))
# Bulletins: current ones first (newest first), then pinned and older ones
bulletins = await client.get_bulletins()
if bulletins:
full = await client.get_bulletin(bulletins[0].id)
print(full.title, full.date, full.content_markdown)
# Exams, courses, homework and lesson diary (one request)
overview = await client.get_overview()
for exam in overview.upcoming_exams(client.today()):
print(exam.date, exam.subject, exam.info, exam.teacher_names)
for exam in overview.graded_exams():
print(exam.date, exam.subject, exam.grade, exam.verbal_grade)
for homework in overview.homework[:5]:
print(homework.date, homework.subject, homework.text)
for course in overview.courses:
print(course.code, course.name, course.teacher_names)
# Several children on one account: pass a student's user_id to any data method
for student in await client.get_students():
unread = await client.get_messages(only_unread=True, user_id=student.user_id)
print(student.name, len(unread))
# List first, then fetch content only for the messages you need (marks them read)
messages = await client.get_messages()
await client.fetch_content(messages[:3])
asyncio.run(main())
Development
Setup
# Clone the repository
git clone https://github.com/frwickst/pywilma.git
cd wilhelmina
# Install development dependencies
poetry install
Running Tests
# Run all tests
poetry run pytest
# Run specific tests
poetry run pytest wilhelmina/tests/test_client.py
# Run with coverage
poetry run pytest --cov=wilhelmina
Linting and Type Checking
# Format with ruff
poetry run ruff format wilhelmina
# Run ruff for linting
poetry run ruff check wilhelmina --fix
# Run mypy for type checking
poetry run mypy wilhelmina
License
MIT
Metadata
Release files for wilhelmina 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wilhelmina-0.4.0.tar.gz | 40.3 kB | Without provenance | Details for wilhelmina-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wilhelmina-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for wilhelmina-0.4.0-py3-none-any.whl |
Total release size: 88.1 kB
Release files / wilhelmina-0.4.0.tar.gz
| Download URL | wilhelmina-0.4.0.tar.gz |
|---|---|
| Size | 40.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f2b4e1ce56102c225d6254cd52102289f70a3b11782e7ce891fb474d2ef3dbca
|
|
BLAKE2b-256 checksum How to use checksums |
2e15abbf64c6006e85899e3902c3b914971eb54737f2d1b662f82ffcb6c21b22
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.12.14 Darwin/25.4.0
|
Release files / wilhelmina-0.4.0-py3-none-any.whl
| Download URL | wilhelmina-0.4.0-py3-none-any.whl |
|---|---|
| Size | 47.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0fd92a49e354dccdd2fe8119331924718506ce34eff5a5f75ff5a7e9a76a2b15
|
|
BLAKE2b-256 checksum How to use checksums |
107d91a97f6f4f32b1a0ca22691e44424e39241562c0284a5348ff1b66676052
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.12.14 Darwin/25.4.0
|
Security for wilhelmina 0.4.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.