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

        # 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.3.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.3.0
File Size Uploaded Provenance Actions
wilhelmina-0.3.0.tar.gz 35.3 kB Without provenance Details for wilhelmina-0.3.0.tar.gz

Built distribution (wheel)

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

Total release size: 77.0 kB

Release files / wilhelmina-0.3.0.tar.gz

Download URL wilhelmina-0.3.0.tar.gz
Size 35.3 kB
Tags Source
SHA-256 checksum
How to use checksums
52b72fbe21319e8fc10405cf1222dff7c9bb21e421668cde2236d337bae8d7b6
BLAKE2b-256 checksum
How to use checksums
d3b55dd1ef11bb439572495782f9a244458d77c36c2f253df1612fb669cd4cf8
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.3.0-py3-none-any.whl

Download URL wilhelmina-0.3.0-py3-none-any.whl
Size 41.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c168d3045e4249838b1ccba267fb1fe6afe3f0bd11dea761c928b2b4ee9371e3
BLAKE2b-256 checksum
How to use checksums
ec80ecad796ddb793aa4c94c60435c09f2fbd38126396f9d542c7ed0ca0a872e
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.3.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