wilhelmina 0.1.0__tar.gz

wilhelmina-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 {{cookiecutter.github_user}}
+
+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.

wilhelmina-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.1
+Name: wilhelmina
+Version: 0.1.0
+Summary: API client for Wilma school portal
+Home-page: https://github.com/frwickst/wilma
+License: MIT
+Author: Frank Wickström
+Author-email: frwickst@gmail.com
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Provides-Extra: playwright
+Requires-Dist: aiohttp (>=3.11.16,<4.0.0)
+Requires-Dist: beautifulsoup4 (>=4.13.4,<5.0.0)
+Requires-Dist: html2text (>=2025.4.15,<2026.0.0)
+Requires-Dist: mashumaro (>=3.15,<4.0)
+Requires-Dist: playwright (>=1.51.0,<2.0.0) ; extra == "playwright"
+Project-URL: Repository, https://github.com/frwickst/wilma
+Description-Content-Type: text/markdown
+
+# 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
+
+- [X] Messages
+  - [X] List (API)
+  - [X] Get single (API)
+  - [X] Get unread (Scraping w/ Playwright)\*
+
+
+\* There _is_ an API that returns the `status` of a message (0=read, 1=unread) but this is not enabled on all instances, specifically not on the Turku instance that I was interested in. 
+
+## 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.
+
+## Features
+
+- Asynchronous API using `aiohttp`
+- Type-safe models using `mashumaro`
+- Optional unread message detection using Playwright for JavaScript rendering
+- Graceful fallback when Playwright is not installed (messages won't be marked as unread)
+- Comprehensive test suite
+
+## 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
+
+```bash
+# Basic installation
+pip install wilma
+
+# (Optional) Installation with Playwright support (for unread message detection)
+pip install wilma[playwright]
+
+# Playwright browser will be installed automatically on import
+
+# Using Poetry
+poetry add wilma -E playwright
+```
+
+## API Client Usage
+
+```python
+import asyncio
+from wilma import WilmaClient
+
+async def main():
+    # Initialize client with an optional existing aiohttp session
+    # Use headless=False to see the browser
+    session = aiohttp.ClientSession()  # Optional - provide your own session
+    
+    async with WilmaClient("https://turku.inschool.fi", session=session, headless=True) as client:
+        # Login
+        await client.login("username", "password")
+        
+        # Get messages
+        messages = await client.get_messages()
+        
+        # Print messages
+        for msg in messages:
+            # Show unread status
+            unread_status = "UNREAD" if msg.unread else "read"
+            print(f"{msg.id}: {msg.subject} - {msg.timestamp} - {msg.sender} - {unread_status}")
+            
+            # Get message content
+            content = await client.get_message_content(msg.id)
+            print(f"Content: {content.content[:100]}...")
+
+# Run the main function
+asyncio.run(main())
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/wilma.git
+cd wilma
+
+# Install development dependencies
+poetry install
+
+# Install Playwright browser
+poetry run playwright install chromium
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+poetry run pytest
+
+# Run specific tests
+poetry run pytest wilma/tests/test_client.py
+
+# Run with coverage
+poetry run pytest --cov=wilma
+```
+
+### Linting and Type Checking
+
+```bash
+# Format with ruff
+poetry run ruff format wilma
+
+# Run ruff for linting
+poetry run ruff check wilma --fix
+
+# Run mypy for type checking
+poetry run mypy wilma
+```
+
+## License
+
+MIT
+

wilhelmina-0.1.0/README.md

@@ -0,0 +1,131 @@
+# 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
+
+- [X] Messages
+  - [X] List (API)
+  - [X] Get single (API)
+  - [X] Get unread (Scraping w/ Playwright)\*
+
+
+\* There _is_ an API that returns the `status` of a message (0=read, 1=unread) but this is not enabled on all instances, specifically not on the Turku instance that I was interested in. 
+
+## 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.
+
+## Features
+
+- Asynchronous API using `aiohttp`
+- Type-safe models using `mashumaro`
+- Optional unread message detection using Playwright for JavaScript rendering
+- Graceful fallback when Playwright is not installed (messages won't be marked as unread)
+- Comprehensive test suite
+
+## 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
+
+```bash
+# Basic installation
+pip install wilma
+
+# (Optional) Installation with Playwright support (for unread message detection)
+pip install wilma[playwright]
+
+# Playwright browser will be installed automatically on import
+
+# Using Poetry
+poetry add wilma -E playwright
+```
+
+## API Client Usage
+
+```python
+import asyncio
+from wilma import WilmaClient
+
+async def main():
+    # Initialize client with an optional existing aiohttp session
+    # Use headless=False to see the browser
+    session = aiohttp.ClientSession()  # Optional - provide your own session
+    
+    async with WilmaClient("https://turku.inschool.fi", session=session, headless=True) as client:
+        # Login
+        await client.login("username", "password")
+        
+        # Get messages
+        messages = await client.get_messages()
+        
+        # Print messages
+        for msg in messages:
+            # Show unread status
+            unread_status = "UNREAD" if msg.unread else "read"
+            print(f"{msg.id}: {msg.subject} - {msg.timestamp} - {msg.sender} - {unread_status}")
+            
+            # Get message content
+            content = await client.get_message_content(msg.id)
+            print(f"Content: {content.content[:100]}...")
+
+# Run the main function
+asyncio.run(main())
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/wilma.git
+cd wilma
+
+# Install development dependencies
+poetry install
+
+# Install Playwright browser
+poetry run playwright install chromium
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+poetry run pytest
+
+# Run specific tests
+poetry run pytest wilma/tests/test_client.py
+
+# Run with coverage
+poetry run pytest --cov=wilma
+```
+
+### Linting and Type Checking
+
+```bash
+# Format with ruff
+poetry run ruff format wilma
+
+# Run ruff for linting
+poetry run ruff check wilma --fix
+
+# Run mypy for type checking
+poetry run mypy wilma
+```
+
+## License
+
+MIT

wilhelmina-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[tool.poetry]
+name = "wilhelmina"
+version = "0.1.0"
+description = "API client for Wilma school portal"
+authors = ["Frank Wickström <frwickst@gmail.com>"]
+repository = "https://github.com/frwickst/wilma"
+readme = "README.md"
+license = "MIT"
+
+[tool.poetry.dependencies]
+python = "^3.13"
+aiohttp = "^3.11.16"
+mashumaro = "^3.15"
+html2text = "^2025.4.15"
+beautifulsoup4 = "^4.13.4"
+playwright = {version = "^1.51.0", optional = true}
+
+[tool.poetry.extras]
+playwright = ["playwright"]
+
+[tool.poetry.scripts]
+wilma-install-deps = "wilma:install_playwright_deps"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.5"
+pytest-asyncio = "^0.26.0"
+pytest-cov = "^6.1.1"
+mypy = "^1.15.0"
+ruff = "^0.11.6"
+types-beautifulsoup4 = "^4.12.0.20250204"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["wilma"]
+lint.select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_unused_ignores = true
+warn_return_any = true
+warn_unreachable = true
+disallow_any_generics = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "wilma.tests.*"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "playwright.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "function"

wilhelmina-0.1.0/wilhelmina/__init__.py

@@ -0,0 +1,65 @@
+"""Wilma API client."""
+
+import importlib.util
+import logging
+import subprocess
+import sys
+
+from wilma.client import AuthenticationError, WilmaClient, WilmaError
+from wilma.models import Message, MessagesList, Sender
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "WilmaClient",
+    "WilmaError",
+    "AuthenticationError",
+    "Message",
+    "MessagesList",
+    "Sender",
+    "install_playwright_deps",
+]
+
+
+def install_playwright_deps(force: bool = False, quiet: bool = False) -> bool:
+    """Install Playwright dependencies.
+
+    Args:
+        force: Force installation even if playwright is not installed
+        quiet: Don't log anything
+
+    Returns:
+        True if installed, False if skipped or failed
+    """
+    if not force:
+        # Check if playwright is installed
+        if importlib.util.find_spec("playwright") is None:
+            if not quiet:
+                logger.warning(
+                    "Playwright is not installed. Install with 'pip install wilma[playwright]'"
+                )
+            return False
+
+    log_level = logging.ERROR if quiet else logging.INFO
+    logger.setLevel(log_level)
+
+    try:
+        logger.info("Installing Playwright dependencies...")
+        subprocess.run(
+            [sys.executable, "-m", "playwright", "install", "chromium"],
+            check=True,
+            capture_output=quiet,
+        )
+        logger.info("Playwright dependencies installed successfully.")
+        return True
+    except (subprocess.SubprocessError, FileNotFoundError) as e:
+        logger.error(f"Failed to install Playwright dependencies: {e}")
+        return False
+
+
+# Auto-install Playwright browser when package is installed with the extra
+if importlib.util.find_spec("playwright") is not None:
+    # Only attempt installation during import if playwright is available
+    # This ensures the browser is installed automatically when the package
+    # is installed with the playwright extra
+    install_playwright_deps(quiet=True)