Metadata-Version: 2.4
Name: hivelms-client
Version: 1.0.0
Summary: An SDK for the Hive LMS API
Project-URL: Homepage, https://github.com/jan-oko/HiveLMS-Client
Project-URL: Documentation, https://jan-oko.github.io/HiveLMS-Client/
Project-URL: Repository, https://github.com/jan-oko/HiveLMS-Client
Requires-Python: >=3.12
Requires-Dist: email-validator>=2.3.0
Requires-Dist: pydantic-extra-types>=2.11.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyrfc6266>=1.0.2
Requires-Dist: requests>=2.32.5
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: requests-mock>=1.11; extra == 'dev'
Description-Content-Type: text/markdown

# HiveLMS Python Client

A typed Python SDK for the Hive LMS REST API, built on Pydantic v2 and `requests`.

This package provides a clean, Pydantic-validated interface to every Hive REST endpoint.
Instead of crafting raw HTTP requests and parsing JSON by hand you work with:

- **Handler objects** — one per resource, accessed as attributes on the main client.
- **Pydantic models** — fully typed request bodies (`*Input` / `*Patch`) and response objects.
- **Automatic auth** — JWT tokens are fetched and refreshed transparently on every request.

Full documentation at **[jan-oko.github.io →](https://jan-oko.github.io/HiveLMS-Client/)** \
Repo and source code at **[GitHub →](https://github.com/jan-oko/HiveLMS-Client)**

## Installation

```bash
uv add hivelms-client
```

Python 3.12+ is required.

---

## Quick Start

```python
from hivelms_client import HiveClient
from hivelms_client.models.assignments.assignment import AssignmentInput
from hivelms_client.models.assignments.assignment import AssignmentPatch, AssignmentStatus

client = HiveClient(
    host="hive.example.com",
    username="admin0",
    password="secret",
    port=443,  # default
    use_https=True,  # default
    verify_certs=True,
)

# List all programs
programs = client.course_handler.programs.search()

# Create an assignment
assignment = client.assignments_handler.create(
    AssignmentInput(exercise=5, user=12)
)

# Partial update
client.assignments_handler.patch(
    assignment.id,
    AssignmentPatch(assignment_status=AssignmentStatus.DONE),
)
```

Authentication is lazy — a JWT is fetched on the first request and silently refreshed on 401 responses.

---

## Handler Map

All resources are accessed through handler namespaces on the client:

| Attribute                      | What it covers                                                     |
|--------------------------------|--------------------------------------------------------------------|
| `client.assignments_handler`   | Assignments and their responses                                    |
| `client.course_handler`        | Programs, subjects, modules, exercises, form fields                |
| `client.help_handler`          | Help threads and their responses                                   |
| `client.management_handler`    | Users, classes, seating, registration                              |
| `client.queues_handler`        | Queues and queue items                                             |
| `client.schedule_handler`      | Lessons, lesson rules, calendar events, event colors, daily review |
| `client.tags_handler`          | Tags                                                               |
| `client.notifications_handler` | Notifications                                                      |
| `client.token_handler`         | JWT token creation and refresh                                     |
| `client.time_handler`          | Server time                                                        |

Sub-resource handlers are nested attributes (e.g. `client.queues_handler.items`,
`client.course_handler.exercises.fields`).

---

## Discriminated Unions

Several models use Pydantic discriminated unions. Pass the concrete subtype:

```python
from hivelms_client.models.management.users.student import StudentUserInput

student = client.management_handler.users.create(
    StudentUserInput(username="alice", program=1, number=42, ...)
)
```

Key unions:

| Union                                | Discriminator           | Subtypes                                                                                            |
|--------------------------------------|-------------------------|-----------------------------------------------------------------------------------------------------|
| `User` / `UserInput`                 | `clearance`             | `StudentUser`, `CheckerUser`, `StaffUser`                                                           |
| `Queue` / `QueueInput`               | `module` / `user` field | `ModuleQueue`, `UserQueue`                                                                          |
| `FormField` / `FormFieldInput`       | `has_value` → `type`    | `UnfillableFormField`, `TextFormField`, `NumericFormField`, `RadioFormField`, `CheckboxesFormField` |
| `Notification` / `NotificationInput` | `assignment` vs `help`  | `ExerciseNotification`, `HelpNotification`                                                          |

---

## Testing

Integration tests spin a hive instance and thus require a hive repo:

```bash
cd tests/integration
HIVE_REPO=/path/to/a/local/repo uv run pytest tests/integration/ -m integration -v
```

---

## Documentation

Full API reference, guides, and a tutorial are available at:

**https://jan-oko.github.io/HiveLMS-Client/**

To build and serve the docs locally:

```bash
uv run mkdocs serve
```
