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
  • 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.
  • 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))

        # 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.2.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.2.0
File Size Uploaded Provenance Actions
wilhelmina-0.2.0.tar.gz 30.5 kB Without provenance Details for wilhelmina-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 65.9 kB

Release files / wilhelmina-0.2.0.tar.gz

Download URL wilhelmina-0.2.0.tar.gz
Size 30.5 kB
Tags Source
SHA-256 checksum
How to use checksums
97044c1c311d7b4df642226d97994df683bddfb8241a11833a9868b030bb3425
BLAKE2b-256 checksum
How to use checksums
2a34cbd1df6cf16e9f178fdd6eb6eb6eea7889bc3423319af004e8ed6f3c4ff3
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.2.0-py3-none-any.whl

Download URL wilhelmina-0.2.0-py3-none-any.whl
Size 35.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62fabcf687b01388a9ac4b21d90ffaba58f8273c9eb9d481b14e8fd5665a7c5f
BLAKE2b-256 checksum
How to use checksums
faf93ae747b5598866e061aba7a34ee55f34b932e45e8ae5d901c3e1f2bccb21
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.2.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