Skip to main content

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 Status field)
    • 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 a user_id to 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() and get_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's timezone (default Europe/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)

Source distribution for wilhelmina 0.4.0
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)

Table of built distributions (wheels) for wilhelmina 0.4.0
File Interpreter ABI Platform Actions
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.

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