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:

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:

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