API Structure¶

This page explains how the library is organized: the client, handler tree, and model naming conventions.

The client¶

HiveClient is the single entry point. It creates one shared HiveHttpClient session and exposes every resource as a handler attribute:

from hivelms_client import HiveClient

client = HiveClient(host="...", username="...", password="...")

client.course_handler          # CourseHandler
client.assignments_handler     # AssignmentsHandler
client.help_handler            # HelpHandler
client.management_handler      # ManagementHandler
client.queues_handler          # QueuesHandler
client.schedule_handler        # ScheduleHandler
client.tags_handler            # TagsHandler
client.notification_handler    # NotificationHandler
client.time_handler            # TimeHandler

Handlers¶

Each handler wraps one API resource area and exposes CRUD methods plus any resource-specific actions.

Common CRUD methods¶

Every handler that owns a top-level resource implements the same set of methods:

Method	HTTP	Description
`search(**filters)`	`GET /resource/`	List, optionally filtered
`get(id_)`	`GET /resource/{id}/`	Fetch one by ID
`create(input)`	`POST /resource/`	Create a new item
`update(id_, input)`	`PUT /resource/{id}/`	Full replace
`patch(id_, patch)`	`PATCH /resource/{id}/`	Partial update
`delete(id_)`	`DELETE /resource/{id}/`	Delete

Sub-handlers¶

Nested resources are exposed as attributes on their parent handler and follow the same CRUD pattern, with the parent resource ID as the first positional argument:

# Queue items live under a queue
items = client.queues_handler.items
items.search(queue_id=1)
items.create(queue_id=1, item=ModuleQueueItemInput(...))
items.get(queue_id=1, item_id=5)
items.update(queue_id=1, item_id=5, updated_item=ModuleQueueItemInput(...))
items.delete(queue_id=1, item_id=5)

# Help responses
responses = client.help_handler.responses
responses.search(help_id=10)
responses.create(help_id=10, response_request=HelpResponseInput(...))

# Lesson rules
rules = client.schedule_handler.lessons.rules
rules.search(lesson_id=2)
rules.create(lesson_id=2, request=LessonRuleInput(...))

# Current user
me = client.management_handler.users.me
me.get()
me.patch(StaffCurrentUserPatch(hostname="my-machine"))

Models¶

All request bodies and response objects are Pydantic v2 models. The naming convention is:

Suffix	Role	Example
(none)	API response / fetched resource	`Assignment`, `Module`
`Core`	Shared base fields for input + response	`ModuleCore`, `ExerciseCore`
`Input`	Full create / replace request body	`AssignmentInput`, `TagInput`
`Patch`	Partial update body (only sent fields are changed)	`AssignmentPatch`, `TagPatch`

Patch semantics¶

*Patch models default every field to the MISSING sentinel. Only fields that you explicitly set are included in the PATCH request body:

from hivelms_client.models.assignments.assignment import AssignmentPatch, AssignmentStatus

# Only updates assignment_status — all other fields are left unchanged on the server
patch = AssignmentPatch(assignment_status=AssignmentStatus.Done)
client.assignments_handler.patch(42, patch)

Discriminated unions¶

Some resources have multiple concrete types distinguished by a single field. Both User and Queue use Pydantic discriminated unions:

# User: discriminated by `clearance`
from hivelms_client.models.management.users.user import User, UserInput
from hivelms_client.models.management.users.student import StudentUserInput
from hivelms_client.models.management.users.user_options import Clearance

new_user: UserInput = StudentUserInput(
    username="hanich99",
    first_name="Test",
    last_name="Student",
    clearance=Clearance.Hanich,
    program=1,
    number=99,
)

# Queue: UserQueue or ModuleQueue, discriminated automatically
queue = client.queues_handler.get(1)
if hasattr(queue, "module_id"):
    print("module queue, module:", queue.module_id)

File responses¶

Endpoints that stream binary data return a FileResponse:

from hivelms_client.models.file_response import FileResponse

result: FileResponse = client.course_handler.exercises.get_preview(exercise_id=4)
result.filename   # str  — from Content-Disposition header
result.mimetype   # str  — from Content-Type header
result.content    # bytes

HTTP layer¶

HiveHttpClient handles the low-level plumbing:

Wraps a requests.Session.
Serializes Pydantic bodies via model_dump(mode="json", by_alias=True).
Validates response JSON with a Pydantic TypeAdapter.
Raises typed exceptions from hivelms_client.exceptions (see below).

Exceptions¶

from hivelms_client.exceptions.hive_exceptions import (
    ResourceNotFoundException,
    PermissionDeniedException,
    InputValidationException,
)

try:
    client.assignments_handler.get(99999)
except ResourceNotFoundException:
    print("not found")

Exception	When raised
`ResourceNotFoundException`	404
`PermissionDeniedException`	403
`InputValidationException`	400 validation error
`UnauthenticatedException`	401 (after retry)
`ServerErrorException`	5xx
`SystemException`	Network / connection failure