hivelms-client 1.0.1

An SDK for the Hive LMS API

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 →
Repo and source code at GitHub →

Installation

uv add hivelms-client

Python 3.12+ is required.

---

Quick Start

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:

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:

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:

uv run mkdocs serve