minerva-zermelo 0.1.0__tar.gz

minerva_zermelo-0.1.0/.example.env

@@ -0,0 +1,6 @@
+SCHOOL=
+SCHOOLYEAR=
+PASSWORD=
+EMAIL=
+USER=
+AUTHORIZATION=Bearer  

minerva_zermelo-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Bytecode & Caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Databases
+*.db
+*.sqlite3
+
+# Build & packaging artifacts
+dist/
+build/
+*.egg-info/
+
+
+# Environment
+.env
+.venv/
+env/
+
+*.json
+test
+__pycache__/
+logs/
+*.db
+*sqlite3

minerva_zermelo-0.1.0/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Project Change Log
+
+This file records the complete committed Git history of the project in chronological order. It does not include uncommitted working-tree changes.
+
+## 2026-10-14 - Initial project
+
+- Created the initial `main.py` file.
+- Commit: `098fa75` (`Init`)
+
+## 2026-10-16 - API base
+
+- Added the first Zermelo API client configuration.
+- Added environment variable loading with `python-dotenv`.
+- Added school, authorization, base URL, and request header configuration.
+- Added the first school-year and appointment request logic.
+- Commit: `06daec5` (`base`)
+
+## 2026-10-16 - Data folder setup
+
+- Added initial `.gitignore` configuration.
+- Added a data folder reference to the project.
+- Commit: `40a62b7` (`data folder`)
+
+## 2026-10-18 - Base features and fixes
+
+- Added more API functionality and fixed initial bugs.
+- Added school-year ID and user retrieval.
+- Expanded appointment retrieval and response handling.
+- Commit: `9407664` (`added more base features and bug fixes`)
+
+## 2026-10-18 - Helper module and README
+
+- Added `helper/helper.py` for shared API configuration and school-year helpers.
+- Refactored the main script to use helper functionality.
+- Added the first project README.
+- Updated `.gitignore`.
+- Commit: `f34721a` (`added a readme`)
+
+## 2026-10-18 - Endpoint expansion
+
+- Created the `ImportData` package and moved the main API workflow into it.
+- Added appointment import support.
+- Added endpoint functions for appointments, branches, users, departments, holidays, jobs, locations, school years, time slots, and students.
+- Added a shared endpoint request helper.
+- Added logging and automatic creation of the `logs/messages` directories.
+- Removed the old root `main.py` implementation.
+- Commit: `369ea9d` (`added more enpoints`)
+
+## 2026-10-19 - Parameterized requests
+
+- Updated endpoint functions to accept school-year IDs, school years, and user IDs.
+- Improved request construction and endpoint parameters.
+- Updated helper functionality for the expanded endpoint workflow.
+- Commit: `279b221` (`MOREEE ENDPONTS`)
+
+## 2026-10-20 - More API fields
+
+- Added more appointment fields, including teachers, subjects, locations, online details, capacity, and modification information.
+- Added student retrieval support.
+- Improved helper and endpoint data handling.
+- Commit: `b4ac960` (`more fields for endpoints and better helper script`)
+
+## 2026-10-23 - Database and API wrapper
+
+- Added SQLite-backed `Student` and `Appointment` blueprints.
+- Added student and appointment import scripts.
+- Added automatic Zermelo API token retrieval through Selenium and the login flow.
+- Added school-year and API message logging helpers.
+- Added Django project scaffolding with settings, URLs, WSGI, and ASGI entry points.
+- Added a student API endpoint.
+- Added `main.py` and `manage.py` for the database/API application.
+- Updated the README and `.gitignore`.
+- Commit: `ed3e3c5` (`added database for the students and a api wrapper`)
+
+## 2026-10-23 - Devlog update
+
+- Updated `DEVLOG.md` with the project history through the database and API wrapper work.
+- Commit: `a5fab31` (`updated dev log`)
+
+## 2026-10-25 - Mass appointment import
+
+- Added `ImportData/MassImportAppointments.py` for importing appointments across a range of student IDs.
+- Expanded appointment import and storage in `appointments.db`.
+- Added shared API and school-year helpers in `helper/api.py` and `helper/year.py`.
+- Removed duplicate older helper modules.
+- Added `.example.env` and `requirements.txt`.
+- Expanded the README with installation, environment, token, API, and mass-import instructions.
+- Updated the student API route to `/api/students/`.
+- Commit: `d641363` (`Implemented massImportAppointments`)
+
+## 2026-10-25 - Devlog update
+
+- Updated `.gitignore`.
+- Added the latest mass-import work to `DEVLOG.md`.
+- Commit: `017e0f5` (`Updated devlog`)
+
+## 2026-10-26 - Appointment API wrapper
+
+- Added appointments to the Django API wrapper.
+- Added `zermeloAPI/endpoints/Appointments.py`.
+- Expanded the students endpoint and improved student import behavior.
+- Made small bug fixes in the import and API code.
+- Updated URL routing for the appointment endpoint.
+- Commit: `e4a2a49` (`some small bugfixses and add the Apointments to the api wrapper`)
+
+## 2026-10-28 - API and authentication fixes
+
+- Fixed appointment import and mass-import behavior.
+- Improved school-year handling.
+- Corrected the appointments API endpoint implementation.
+- Added API authentication middleware.
+- Updated Django settings for the middleware.
+- Commit: `614557a` (`More small bugfixes`)
+
+## 2026-10-29 - Documentation updates
+
+- Expanded the README with more project documentation.
+- Added an additional documentation update describing project usage and behavior.
+- Commits: `d41e8df` (`More documentair`), `20d2381` (`More documentair`)
+
+## 2026-10-30 - First library packaging
+
+- Added the `pyproject.toml` package configuration.
+- Added the `LICENSE` file.
+- Added the first distributable package archive.
+- Moved the project into the `scr/Minerva` package layout.
+- Moved the API, helper, import, blueprint, and Django files into the package.
+- Added package documentation in `scr/Minerva/readme.md`.
+- Added and cleaned up ignored files and generated Python cache files.
+- Commit: `6a83d1d` (`Libary test`)
+
+## 2026-10-30 - Move to `src/minerva`
+
+- Moved the Minerva package from `scr/Minerva` to `src/minerva`.
+- Moved import scripts, blueprints, helpers, and Django wrapper files into the new source layout.
+- Preserved the package contents while changing the project structure.
+- Commit: `a7d6078` (`small fixes`)
+
+## 2026-10-30 - Cleanup and wrapper rename
+
+- Expanded `.gitignore` to exclude generated files and build artifacts.
+- Removed tracked Python cache files and the old package archive.
+- Renamed `zermeloAPI` to `ZermeloApiWrapper`.
+- Cleaned up the old root-level structure.
+- Commit: `b2a93b5` (`small fixes`)
+
+## 2026-10-30 - Library refactor
+
+- Refactored `ZermeloMain` into a reusable package API.
+- Reworked API helper functions and request handling.
+- Simplified the year helper.
+- Updated package initialization and environment configuration.
+- Removed obsolete import code.
+- Commit: `1f607e7` (`small fixes + big refactor`)
+
+## 2026-11-01 - Library packaging refactor
+
+- Completed the library refactor in the `src/minerva` layout.
+- Updated `pyproject.toml` package metadata and build configuration.
+- Updated the README with expanded installation, usage, API, import, and library documentation.
+- Updated import scripts and mass appointment importing for the refactored package.
+- Updated the `ZermeloApiWrapper` Django package, authentication middleware, settings, URLs, and WSGI/ASGI files.
+- Improved API token, API request, and school-year helper implementations.
+- Updated `.gitignore` for the final package structure.
+- Commit: `7de39cc` (`libary refactor`)

minerva_zermelo-0.1.0/DEVLOG.md

@@ -0,0 +1,77 @@
+# Development Log
+
+This log is based on the committed Git history of the project.
+
+## 2026-10-14 - Initial setup
+
+- Created the initial `main.py` file as the starting point for the project.
+- Commit: `098fa75` (`Init`)
+
+## 2026-10-16 - Zermelo API base
+
+- Added the first Zermelo API client setup.
+- Added environment variable loading with `python-dotenv`.
+- Added configuration for the school, API authorization, base URL, and request headers.
+- Added the first school-year lookup and appointment retrieval logic.
+- Added `.gitignore` entries and a data directory reference.
+- Commits: `06daec5`, `40a62b7`
+
+## 2026-10-18 - Base features and documentation
+
+- Added more API functionality and fixed initial bugs.
+- Added retrieval of users and school-year IDs.
+- Created `helper/helper.py` for shared API configuration and school-year helpers.
+- Added the first `readme.md` with project information and setup requirements.
+- Commit: `9407664`, `f34721a`
+
+## 2026-10-18 - ImportData structure and endpoint expansion
+
+- Reorganized the application into the `ImportData` package.
+- Added `ImportData/ZermeloMain.py` as the main API module.
+- Added `ImportData/ImportAppointments.py` as the appointment import entry point.
+- Added package initialization files for `ImportData` and `helper`.
+- Replaced the original root `main.py` implementation with the new package structure.
+- Added logging and automatic creation of `logs/messages` directories.
+- Added endpoint functions for appointments, branches, users, departments, holidays, jobs, locations, school years, time slots, and students.
+- Added a shared endpoint request helper.
+- Commit: `369ea9d` (`added more enpoints`)
+
+## 2026-10-19 - Parameterized endpoint requests
+
+- Updated endpoint functions to accept school-year IDs, school years, and user IDs where needed.
+- Improved request construction through the shared endpoint helper.
+- Updated helper code to support the expanded endpoint workflow.
+- Commit: `279b221` (`MOREEE ENDPONTS`)
+
+## 2026-10-20 - More fields and student retrieval
+
+- Added more appointment response fields, including teachers, subjects, locations, online details, capacity, and modification information.
+- Added a student retrieval function.
+- Improved the helper script and endpoint data handling.
+- Commit: `b4ac960` (`more fields for endpoints and better helper script`)
+
+## 2026-10-21 - Added dev log
+- Added a dev log file
+
+## 2026-10-23 - Database and API wrapper
+
+- Added SQLite-backed student and appointment data models through the `Blueprints` modules.
+- Added student and appointment import scripts that fetch API data and store it in the local database.
+- Added a Selenium-based helper for obtaining the Zermelo API authorization token through the login flow.
+- Added a helper for retrieving school-year IDs and a helper for logging API messages.
+- Refactored the API helper functions and expanded the import workflow.
+- Added Django project scaffolding, including settings, URL configuration, WSGI/ASGI entry points, and a student API endpoint.
+- Added a root `main.py` and `manage.py` for the database/API application.
+- Updated the README and `.gitignore` for the new project structure.
+- Commit: `ed3e3c5` (`added database for the students and a api wrapper`)
+
+## 2026-10-25 - Mass appointment import
+
+- Added `ImportData/MassImportAppointments.py` to import appointments for a range of student IDs.
+- Expanded the appointment importer to fetch, convert, and store appointment data in `appointments.db`.
+- Added shared API and school-year helpers in `helper/api.py` and `helper/year.py`.
+- Removed the older duplicate helper modules and moved their functionality into the new helpers.
+- Added an `.example.env` file and a `requirements.txt` file for setup and dependencies.
+- Expanded the README with installation instructions, environment configuration, token setup, and mass-import usage.
+- Updated the student API route to `/api/students/`.
+- Commit: `d641363` (`Implemented massImportAppointments`)

minerva_zermelo-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+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.

minerva_zermelo-0.1.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.5
+Name: minerva-zermelo
+Version: 0.1.0
+Summary: Python client for the Zermelo API
+Project-URL: Homepage, https://github.com/DaniNotFound702/Minerva
+Project-URL: Repository, https://github.com/DaniNotFound702/Minerva
+Project-URL: Issues, https://github.com/DaniNotFound702/Minerva/issues
+License: Copyright (c) 2018 The Python Packaging Authority
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: requests<3,>=2.31
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django<7,>=6.1; extra == 'django'
+Provides-Extra: token
+Requires-Dist: selenium<5,>=4.25; extra == 'token'
+Description-Content-Type: text/markdown
+
+# Minerva
+
+Minerva is an importable Python library for interacting with the Zermelo API.
+It provides an authenticated API client, convenience methods for common
+Zermelo resources, appointment import utilities, and an optional Django API
+wrapper.
+
+You need access to the correct Zermelo school environment and a valid API token
+to make requests.
+
+## Installation
+
+Minerva requires Python 3.10 or newer. Install it from the repository with:
+
+Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+On Windows, activate it with:
+
+```powershell
+\.venv\Scripts\Activate.ps1
+```
+
+On Linux, activate it with:
+
+```bash
+source .venv/bin/activate
+```
+
+Install the library:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e .
+```
+
+For development, install the optional dependencies as needed:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pip install -e ".[django]"
+python -m pip install -e ".[token]"
+```
+
+The editable install makes the `minerva` package available to applications
+running in the environment.
+
+## Configuration
+
+The library client can be configured directly in your application. This is the
+recommended approach when credentials come from a settings page, secrets
+manager, or command-line arguments:
+
+```python
+from minerva import ZermeloAPIClient
+
+client = ZermeloAPIClient(
+	school="your-school",
+	authorization="Bearer your-api-token",
+)
+
+branches = client.get_endpoint(
+	"branches",
+	"fields=name,code,somCode,somUuid",
+)
+print(branches)
+```
+
+The values can come from a settings page, a secrets manager, command-line
+arguments, or any other configuration source. A `.env` file is not required.
+
+### Optional environment configuration
+
+If your application uses environment variables, the client accepts these
+values as a fallback:
+
+Create a `.env` file in the root of the repository by copying
+`.example.env`, then load it in your application with `python-dotenv` or your
+preferred configuration library:
+
+```bash
+cp .example.env .env
+```
+
+```env
+SCHOOL=your-school
+SCHOOLYEAR=your-school-year-id
+AUTHORIZATION=Bearer your-api-token
+EMAIL=your-email-address
+PASSWORD=your-password
+USER=your-user-id
+```
+
+`SCHOOL` is the school name used in the Zermelo URL, for example
+`https://your-school.zportal.nl`. `AUTHORIZATION` must contain the full header
+value, including `Bearer `. `SCHOOLYEAR` and `USER` are used by some parts of
+the optional import helpers. `EMAIL` and `PASSWORD` are only needed when using
+the automatic token helper.
+
+Do not commit or share `.env`. It contains credentials and API access data.
+The repository already ignores this file through `.gitignore`.
+
+## Library usage
+
+`ZermeloAPIClient` exposes `get_endpoint(endpoint, parameters)` for direct
+requests. The endpoint name is appended to the school API URL and parameters
+are supplied as a query string:
+
+```python
+from minerva import ZermeloAPIClient
+
+client = ZermeloAPIClient(
+    school="your-school",
+    authorization="Bearer your-api-token",
+)
+
+branches = client.get_endpoint(
+	"branches",
+	"fields=name,code,somCode,somUuid",
+)
+```
+
+For common requests, use `ZermeloMain` convenience methods. It accepts an
+already configured `ZermeloAPIClient`:
+
+```python
+from minerva import ZermeloAPIClient, ZermeloMain
+
+client = ZermeloAPIClient(
+    school="your-school",
+    authorization="Bearer your-api-token",
+)
+zermelo = ZermeloMain(client)
+
+branches = zermelo.branches()
+holidays = zermelo.holidays()
+students = zermelo.studentsindepartments(schoolYear=1234)
+appointments = zermelo.appointments(
+	schoolYear_id=1234,
+	schoolYear=2026,
+	user_id=5678,
+)
+```
+
+The convenience layer also provides `branchesofschools()`,
+`departmentsofbranches()`, `choosableindepartments()`, `groupindepartments()`,
+`locationofbranches()`, `schoolsinschoolyears()`, `timeslotnames()`, and
+`subjectselectionsubjects()`.
+
+Successful calls return the API `data` value, usually a list of dictionaries.
+Unauthorized or other API errors raise `ZermeloAPIError`; network errors from
+`requests` are re-raised. A forbidden request returns `None`.
+
+The main public exports are available directly from `minerva`:
+
+```python
+from minerva import (
+	ZermeloAPIClient,
+	ZermeloAPIError,
+	ZermeloMain,
+	Appointment,
+	Student,
+	saveAll,
+	configure_api_wrapper,
+)
+```
+
+### Optional token helper
+
+The library requires a valid Zermelo API token to make requests. You can
+provide one directly to `ZermeloAPIClient` or through the `AUTHORIZATION`
+environment variable.
+
+The optional helper in `src/minerva/helper/get_api_token.py` can retrieve a
+token through the Zermelo login flow. It requires the `token` extra, `EMAIL`,
+`PASSWORD`, Google Chrome, and a compatible ChromeDriver. The helper currently
+expects ChromeDriver at `/usr/bin/chromedriver` on Linux.
+
+## Optional appointment imports
+
+`src/minerva/ImportData/MassImportAppointments.py` contains utilities for
+importing appointments for a range of student IDs. Before using them, make sure
+that:
+
+- `.env` contains a valid `SCHOOL` and `AUTHORIZATION` value;
+- `database.db` exists and contains the required `STUDENTS` table;
+- you run the command from the repository root.
+
+The import functions use a configured `ZermeloAPIClient` and store imported
+appointments in SQLite. They are additional utilities and are not required to
+use the API client.
+
+## Optional Django API wrapper
+
+The package also includes a Django wrapper for exposing selected Zermelo data
+through HTTP. It currently provides:
+
+- `GET /api/students/`
+- `GET /api/appointments/`
+
+Start the development server from the repository root:
+
+```bash
+python src/minerva/manage.py runserver
+```
+
+The wrapper is available at `http://127.0.0.1:8000/`. The endpoint
+implementation reads its data from the local SQLite databases and supports
+field selection where implemented by the endpoint.
+
+### API-key authentication
+
+Every request whose path starts with `/api/` must include an `X-Api-Key`
+header. The key must match the value configured by the host application with
+`configure_api_wrapper()`:
+
+```python
+from minerva import configure_api_wrapper
+
+configure_api_wrapper("your-wrapper-key")
+```
+
+For deployment, generate a strong key and store it securely:
+
+```bash
+openssl rand -hex 32
+```
+
+Send the generated value directly as the header value. Do not add a
+`Bearer` or `Api-Key` prefix:
+
+```bash
+curl \
+	-H "X-Api-Key: your-wrapper-key" \
+	http://127.0.0.1:8000/api/students/
+```
+
+Requests with a missing or incorrect key receive HTTP `401`. If no wrapper
+key is configured, API requests receive HTTP `500`. Non-API paths do not
+require the key.
+
+### Students fields
+
+The students endpoint supports these fields:
+
+| Field | Type |
+| --- | --- |
+| `id` | Integer |
+| `student` | Integer |
+| `departmentOfBranch` | Integer |
+| `mentorGroup` | Integer |
+| `mainGroup` | Integer |
+| `groupInDepartments` | String |
+| `fullName` | String |
+| `schoolInSchoolYear` | Integer |
+| `firstName` | String |
+| `lastName` | String |
+| `departmentOfBranchCode` | String |
+| `mainGroupName` | String |
+| `prefix` | String |
+
+## Testing
+
+Run the test suite from the repository root:
+
+```bash
+python -m pytest
+```
+
+The middleware tests verify accepted and rejected API keys, missing keys, and
+that non-API paths remain accessible.
+
+## Current functionality
+
+Available API data includes:
+
+- Appointments
+- Choosable departments
+- School branches
+- Users
+- Departments of branches
+- Branches
+- Holidays and school years
+- Students and subjects
+
+## Credits
+
+Parts of this project are inspired by
+[ZermeloUtils](https://github.com/electricsteve/ZermeloUtils) by electricsteve.
+
+AI was used to help explain code, complete parts of `get_api_token.py`, and
+write documentation.

minerva_zermelo-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "minerva-zermelo"
+version = "0.1.0"
+description = "Python client for the Zermelo API"
+readme = "readme.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = [
+  "requests>=2.31,<3",
+]
+
+[project.optional-dependencies]
+django = ["Django>=6.1,<7"]
+token = ["selenium>=4.25,<5"]
+dev = ["pytest", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/DaniNotFound702/Minerva"
+Repository = "https://github.com/DaniNotFound702/Minerva"
+Issues = "https://github.com/DaniNotFound702/Minerva/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/minerva"]