Tutorial¶
This tutorial walks through a realistic workflow: listing course content, managing a student's assignment lifecycle, working with help threads, and subscribing to notifications.
Setup¶
from hivelms_client import HiveClient
client = HiveClient(
host="hive.example.com",
username="admin0",
password="secret",
verify_certs=False, # for local dev with self-signed certs
)
1. Browsing course content¶
List programs¶
programs = client.course_handler.programs.search()
program = programs[0]
print(program.id, program.name)
Subjects in a program¶
subjects.search() returns lightweight dicts (name, id, color). Use subjects.get(id) for the
full Subject model.
subjects = client.course_handler.subjects.search(parent_program_id_in=[program.id])
for s in subjects:
print(s["id"], s["name"])
Modules in a subject¶
subject = client.course_handler.subjects.get(subjects[0]["id"])
modules = client.course_handler.modules.search(parent_subject=subject.id)
module = modules[0]
print(module.name, module.segel_path)
Exercises in a module¶
exercises = client.course_handler.exercises.search(parent_module_id=module.id)
for ex in exercises:
print(ex.id, ex.name, ex.preview, ex.patbas_preview)
Download an exercise preview¶
If an exercise has preview != "Disabled", you can fetch the PDF:
from hivelms_client.models.course.exercise.exercise_options import ExercisePreviewMode
exercise = next(e for e in exercises if e.preview != ExercisePreviewMode.DISABLED)
file_resp = client.course_handler.exercises.get_preview(exercise.id)
with open(f"{exercise.name}_preview.pdf", "wb") as f:
f.write(file_resp.content)
print("saved", file_resp.filename, file_resp.mimetype)
2. Managing assignments¶
Create an assignment¶
from hivelms_client.models.assignments.assignment import AssignmentInput
users = client.management_handler.users.search()
student = next(u for u in users if hasattr(u, "number"))
assignment = client.assignments_handler.create(
AssignmentInput(exercise=exercise.id, user=student.id)
)
print(assignment.id, assignment.assignment_status)
Add a submission response¶
from hivelms_client.models.assignments.assignment_response import (
AssignmentResponseInput,
AssignmentResponseType,
)
response = client.assignments_handler.responses.create(
assignment.id,
AssignmentResponseInput(
response_type=AssignmentResponseType.Submission,
user=student.id,
),
)
print(response.id)
Update assignment status¶
from hivelms_client.models.assignments.assignment import AssignmentPatch, AssignmentStatus
patched = client.assignments_handler.patch(
assignment.id,
AssignmentPatch(assignment_status=AssignmentStatus.Done),
)
print(patched.assignment_status)
Lock / unlock (checker workflow)¶
client.assignments_handler.lock(assignment.id)
# ... checker reviews ...
client.assignments_handler.unlock(assignment.id)
Subscribe to updates¶
client.assignments_handler.subscribe(assignment.id)
assert client.assignments_handler.get(assignment.id).is_subscribed is True
client.assignments_handler.unsubscribe(assignment.id)
3. Working with queues¶
List queues for a module¶
Add an exercise to a queue¶
from hivelms_client.models.queues.queue_items import ModuleQueueItemInput, QueueRule
item = client.queues_handler.items.create(
queue.id,
ModuleQueueItemInput(
module_id=module.id,
order=10,
enabled=True,
queue_rule=QueueRule.CHOOSE,
filter_for_tags=[],
),
)
print(item.id)
Reorder an item¶
from hivelms_client.models.queues.queue_items import QueueItemMoveRequest
client.queues_handler.items.move(
queue.id,
item.id,
QueueItemMoveRequest(order=1),
)
4. Help threads¶
Open a help thread¶
from hivelms_client.models.help.help import HelpInput, HelpType
help_thread = client.help_handler.create(
HelpInput(user=student.id, help_type=HelpType.Chat, exercise_id=exercise.id)
)
print(help_thread.id, help_thread.help_status)
Add a checker comment¶
from hivelms_client.models.help.help_response import HelpResponseInput, HelpResponseType
checker_response = client.help_handler.responses.create(
help_thread.id,
HelpResponseInput(
response_type=HelpResponseType.Comment,
contents="Have you checked the man page?",
),
)
Lock / unlock and subscribe¶
client.help_handler.lock(help_thread.id)
locked = client.help_handler.get(help_thread.id)
assert locked.checker is not None
client.help_handler.unlock(help_thread.id)
client.help_handler.subscribe(help_thread.id)
assert client.help_handler.get(help_thread.id).is_subscribed is True
client.help_handler.unsubscribe(help_thread.id)
Download an attached file¶
response_with_file = client.help_handler.responses.search(help_thread.id)[0]
if response_with_file.file_name:
file_resp = client.help_handler.responses.get_files(
help_thread.id, response_with_file.id
)
open(file_resp.filename, "wb").write(file_resp.content)
5. Notifications¶
Create and read a notification¶
from hivelms_client.models.notification.notification import (
ExerciseNotificationInput,
NotificationPatch,
)
notif = client.notification_handler.create(
ExerciseNotificationInput(user=student.id, assignment=assignment.id)
)
fetched = client.notification_handler.get(notif.id)
print(fetched.was_read)
# Mark as read
client.notification_handler.patch(notif.id, NotificationPatch(was_read=True))
6. User management¶
List and inspect users¶
users = client.management_handler.users.search()
for u in users:
print(u.id, u.username, u.clearance)
Get the current user¶
Download an avatar¶
avatar = client.management_handler.users.get_avatar(student.id)
open("avatar.png", "wb").write(avatar.content)
Work with classes¶
from hivelms_client.models.management.class_ import ClassInput
cls = client.management_handler.classes.create(
ClassInput(name="Group A", program=program.id, users=[student.id])
)
client.management_handler.classes.auto_seat(cls.id)
client.management_handler.classes.delete(cls.id)