Enhancing README documentation

README.md

@@ -1,7 +1,98 @@
-Hey 👋 
-this project provides python functions which allow you to interact with the school portal Hessen which is used by most schools in Hessen.
+# Unofficial LANiS (Schulportal Hessen) API
 
-Additionaly you can run these functions as a API.
-(I host one publicly at lanis-backend.joancode.dev)
+This repository provides:
 
-This is the backend to https://lanis.arg-server.de
+- a Python client (`sph-client`) for Schulportal Hessen
+- a FastAPI server wrapper around the client
+- optional tooling for TUI usage and DSB/substitution-plan workflows
+
+> This project is unofficial and not affiliated with Schulportal Hessen.
+
+## Features
+
+- Login/session handling for Schulportal Hessen
+- Access to core portal areas (apps, profile, calendar, messages, classes, timetable, file storage, school list)
+- DSBmobile substitution plan helpers
+- FastAPI endpoints for browser/app integrations
+- Generated API docs:
+  - `/docs/API.md` (main generated package documentation)
+  - `/api-documentation.md` (extended generated reference output in repo root)
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For development (includes `pytest` and `ruff`):
+
+```bash
+pip install -e .[dev]
+```
+
+## Python client quick start
+
+```python
+from sph_client import SchulportalHessenAPI
+
+api = SchulportalHessenAPI()
+login_result = api.login("<school_id>", "<username>", "<password>")
+
+if login_result.get("success"):
+    modules = api.get_available_modules()
+    print(modules)
+
+api.logout()
+api.close()
+```
+
+## Run the FastAPI server
+
+From the repository root (after installing dependencies):
+
+```bash
+uvicorn api.api:app --reload
+```
+
+Default URL: `http://localhost:8000`
+
+Useful endpoints:
+
+- `GET /health`
+- `POST /login`
+- `POST /logout`
+- `GET /apps`
+- `GET /modules`
+- `GET /benutzer`
+- `GET /kalender`, `GET /kalender/events`
+- `GET /nachrichten/headers`
+- `GET /meinunterricht`
+- `GET /school-list`
+- `POST /dsb/login`, `POST /dsb/plan`
+
+## API testing
+
+Integration tests are in `/api-tests.py` and follow the project convention for API endpoint checks. They require a running API server and credentials via environment variables:
+
+- `LANIS_API_URL`
+- `LANIS_API_SCHOOL_ID`
+- `LANIS_API_USERNAME`
+- `LANIS_API_PASSWORD`
+
+Run:
+
+```bash
+pytest api-tests.py
+```
+
+## Repository structure
+
+- `/schulportal_hessen` – core client implementation
+- `/api` – FastAPI server and related utilities
+- `/docs` – generated package docs
+- `/tui` – terminal UI client
+- `/scripts` – helper scripts (including DSB tracking)
+
+## License
+
+MIT

sph_client.egg-info/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: sph-client
+Version: 0.1.10
+Summary: Python API client for Schulportal Hessen (SPH)
+Author: Schulportal Hessen API Contributors
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pycryptodome>=3.19.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+Hey 👋 
+this project provides python functions which allow you to interact with the school portal Hessen which is used by most schools in Hessen.
+
+Additionaly you can run these functions as a API.
+(I host one publicly at lanis-backend.joancode.dev)
+
+This is the backend to https://lanis.arg-server.de

sph_client.egg-info/SOURCES.txt

@@ -0,0 +1,49 @@
+README.md
+pyproject.toml
+api/__init__.py
+api/api.py
+api/documentation.py
+api/dsb_snapshot.py
+api/file_cache.py
+api/metrics/__init__.py
+api/metrics/user_metrics_db.py
+api/queue/__init__.py
+api/queue/task_queue.py
+schulportal_hessen/__init__.py
+schulportal_hessen/base.py
+schulportal_hessen/applets/benutzer/__init__.py
+schulportal_hessen/applets/benutzer/api.py
+schulportal_hessen/applets/dateispeicher/__init__.py
+schulportal_hessen/applets/dateispeicher/api.py
+schulportal_hessen/applets/kalender/__init__.py
+schulportal_hessen/applets/kalender/api.py
+schulportal_hessen/applets/lerngruppen/__init__.py
+schulportal_hessen/applets/lerngruppen/api.py
+schulportal_hessen/applets/login/__init__.py
+schulportal_hessen/applets/login/api.py
+schulportal_hessen/applets/mein_unterricht/__init__.py
+schulportal_hessen/applets/mein_unterricht/api.py
+schulportal_hessen/applets/mein_unterricht_detailed/__init__.py
+schulportal_hessen/applets/nachrichten/__init__.py
+schulportal_hessen/applets/nachrichten/api.py
+schulportal_hessen/applets/school_list/__init__.py
+schulportal_hessen/applets/school_list/api.py
+schulportal_hessen/applets/stundenplan/__init__.py
+schulportal_hessen/applets/stundenplan/api.py
+schulportal_hessen/applets/vertretungsplan/__init__.py
+schulportal_hessen/applets/vertretungsplan/api.py
+schulportal_hessen/external/dsb/__init__.py
+schulportal_hessen/external/dsb/api.py
+schulportal_hessen/tools/cryptor.py
+schulportal_hessen/tools/find_available_apps.py
+schulportal_hessen/tools/search.py
+scripts/dsb_tracking/__init__.py
+scripts/dsb_tracking/fetch_substitution_plan.py
+scripts/dsb_tracking/query_substitution.py
+scripts/dsb_tracking/substitution_db.py
+sph_client/__init__.py
+sph_client.egg-info/PKG-INFO
+sph_client.egg-info/SOURCES.txt
+sph_client.egg-info/dependency_links.txt
+sph_client.egg-info/requires.txt
+sph_client.egg-info/top_level.txt

sph_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sph_client.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests>=2.31.0
+python-dotenv>=1.0.0
+pycryptodome>=3.19.0
+
+[dev]
+pytest>=7.0.0
+ruff>=0.1.0

sph_client.egg-info/top_level.txt

@@ -0,0 +1,6 @@
+api
+docs
+schulportal_hessen
+scripts
+sph_client
+tui