PyHiveLMS 1.0.0__py3-none-any.whl

pyhive/src/types/notification_nested.py

@@ -0,0 +1,80 @@
+"""Model definition for a nested notification in the Hive system.
+
+Represents a lightweight notification object, optionally referencing a user and comment.
+"""
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+
+from attrs import define
+from attrs import field
+from .common import UNSET, Unset
+from .core_item import HiveCoreItem
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .user import User
+
+T = TypeVar("T", bound="NotificationNested")
+
+
+@define
+class NotificationNested(HiveCoreItem):
+    """A lightweight notification model.
+
+    Attributes:
+        id: Unique identifier of the notification.
+        from_user_id: Optional user ID that sent the notification.
+        comment: Optional comment text.
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    from_user_id: None | Unset | int = UNSET
+    comment: Unset | str = UNSET
+
+    _from_user: "User | None" = field(init=False, default=None)
+
+    @property
+    def from_user(self) -> "User | None":
+        """Lazily loads and returns the `User` who sent the notification.
+
+        Returns:
+            A `User` instance or `None` if not available.
+
+        """
+        if self._from_user is None and not isinstance(self.from_user_id, Unset) and self.from_user_id is not None:
+            self._from_user = self.hive_client.get_user(self.from_user_id)
+        return self._from_user
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the notification to a dictionary."""
+        field_dict: dict[str, Any] = {
+            "id": self.id,
+        }
+
+        if not isinstance(self.from_user_id, Unset):
+            field_dict["from_user"] = self.from_user_id
+
+        if not isinstance(self.comment, Unset):
+            field_dict["comment"] = self.comment
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        """Deserialize the notification from a dictionary."""
+        d = dict(src_dict)
+
+        def _parse_from_user(data: object) -> None | Unset | int:
+            if data is None or isinstance(data, Unset):
+                return data
+            return cast("None | Unset | int", data)
+
+        return cls(
+            hive_client=hive_client,
+            id=d.pop("id"),
+            from_user_id=_parse_from_user(d.pop("from_user", UNSET)),
+            comment=d.pop("comment", UNSET),
+        )

pyhive/src/types/program.py

@@ -0,0 +1,180 @@
+"""Model definition for the Hive Program entity.
+
+Represents an educational program, including checker configuration,
+sync status, and automatic handling flags.
+"""
+
+from collections.abc import Generator, Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar
+
+from attrs import define
+from attrs import field
+from .common import UNSET, Unset
+from .core_item import HiveCoreItem
+from .enums.sync_status_enum import SyncStatusEnum
+from .subject import Subject
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .class_ import Class
+    from .user import User
+
+T = TypeVar("T", bound="Program")
+
+
+@define
+class Program(HiveCoreItem):
+    """Course Program entity.
+
+    Attributes:
+        id: Unique identifier.
+        name: Display name of the program.
+        checker_id: User ID of the assigned checker.
+        sync_status: Sync status (e.g., Normal, Creating).
+        sync_message: Optional sync diagnostic message.
+        default_class_id: Optional class ID used as default.
+        auto_toilet: Auto-toilet generation enabled.
+        hanich_raise_hand: Whether hanich can raise hand.
+        auto_schedule: Enable auto-scheduling.
+        auto_room: Enable automatic room assignments.
+        hanich_day_only: Restrict hanich to day-only usage.
+        hanich_work_name: Enable work name customization.
+        auto_toilet_count: Number of auto toilets to assign.
+        hanich_classes_only: Restrict hanich to classes only.
+        hanich_schedule: Whether hanich gets scheduled.
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    name: str
+    checker_id: int
+    sync_status: SyncStatusEnum
+    sync_message: None | str
+    default_class_id: None | Unset | int
+
+    auto_toilet: Unset | bool = UNSET
+    hanich_raise_hand: Unset | bool = UNSET
+    auto_schedule: Unset | bool = UNSET
+    auto_room: Unset | bool = UNSET
+    hanich_day_only: Unset | bool = UNSET
+    hanich_work_name: Unset | bool = UNSET
+    auto_toilet_count: Unset | int = UNSET
+    hanich_classes_only: Unset | bool = UNSET
+    hanich_schedule: Unset | bool = UNSET
+
+    _checker: "User | None" = field(init=False, default=None)
+    _default_class: "Class | None" = field(init=False, default=None)
+
+    def __str__(self) -> str:
+        return f"<Program[{self.id}] {self.name}>"
+
+    @property
+    def checker(self) -> "User":
+        """Lazily loads and returns the checker (staff member)."""
+        if self._checker is None:
+            self._checker = self.hive_client.get_user(self.checker_id)
+        return self._checker
+
+    @property
+    def default_class(self) -> "Class | None":
+        """Lazily loads the default class, if set."""
+        if (
+            self._default_class is None
+            and not isinstance(self.default_class_id, Unset)
+            and self.default_class_id is not None
+        ):
+            self._default_class = self.hive_client.get_class(self.default_class_id)
+        return self._default_class
+
+    def get_subjects(self) -> Generator[Subject]:
+        """Returns all subjects belonging to this program."""
+        return self.hive_client.get_subjects(parent_program__id__in=[self.id])
+
+    def to_dict(self) -> dict[str, Any]:
+        field_dict: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "checker": self.checker_id,
+            "sync_status": self.sync_status.value,
+            "sync_message": self.sync_message,
+        }
+
+        if not isinstance(self.default_class_id, Unset):
+            field_dict["default_class"] = self.default_class_id
+        if not isinstance(self.auto_toilet, Unset):
+            field_dict["auto_toilet"] = self.auto_toilet
+        if not isinstance(self.hanich_raise_hand, Unset):
+            field_dict["hanich_raise_hand"] = self.hanich_raise_hand
+        if not isinstance(self.auto_schedule, Unset):
+            field_dict["auto_schedule"] = self.auto_schedule
+        if not isinstance(self.auto_room, Unset):
+            field_dict["auto_room"] = self.auto_room
+        if not isinstance(self.hanich_day_only, Unset):
+            field_dict["hanich_day_only"] = self.hanich_day_only
+        if not isinstance(self.hanich_work_name, Unset):
+            field_dict["hanich_work_name"] = self.hanich_work_name
+        if not isinstance(self.auto_toilet_count, Unset):
+            field_dict["auto_toilet_count"] = self.auto_toilet_count
+        if not isinstance(self.hanich_classes_only, Unset):
+            field_dict["hanich_classes_only"] = self.hanich_classes_only
+        if not isinstance(self.hanich_schedule, Unset):
+            field_dict["hanich_schedule"] = self.hanich_schedule
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        """Create an instance of the class from a dictionary representation.
+
+        Args:
+            src_dict (Mapping[str, Any]): The source dictionary containing the data to populate the instance.
+            hive_client (HiveClient): An instance of HiveClient to associate with the created object.
+
+        Returns:
+            Self: An instance of the class populated with data from src_dict.
+
+        Notes:
+            - Handles optional and unset fields using the _parse_optional helper.
+            - Converts the 'sync_status' field to a SyncStatusEnum.
+            - Pops fields from the dictionary to avoid duplication.
+
+        """
+        d = dict(src_dict)
+
+        def _parse_optional(data: object) -> Any:
+            if data is None or isinstance(data, Unset):
+                return data
+            return data
+
+        return cls(
+            id=d.pop("id"),
+            name=d.pop("name"),
+            checker_id=d.pop("checker"),
+            sync_status=SyncStatusEnum(d.pop("sync_status")),
+            sync_message=_parse_optional(d.pop("sync_message")),
+            default_class_id=_parse_optional(d.pop("default_class", UNSET)),
+            auto_toilet=d.pop("auto_toilet", UNSET),
+            hanich_raise_hand=d.pop("hanich_raise_hand", UNSET),
+            auto_schedule=d.pop("auto_schedule", UNSET),
+            auto_room=d.pop("auto_room", UNSET),
+            hanich_day_only=d.pop("hanich_day_only", UNSET),
+            hanich_work_name=d.pop("hanich_work_name", UNSET),
+            auto_toilet_count=d.pop("auto_toilet_count", UNSET),
+            hanich_classes_only=d.pop("hanich_classes_only", UNSET),
+            hanich_schedule=d.pop("hanich_schedule", UNSET),
+            hive_client=hive_client,
+        )
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, Program):
+            return False
+        return (
+            self.id == value.id
+            and self.checker_id == value.checker_id
+            and self.name == value.name
+        )
+
+    def __iter__(self) -> Generator["Subject", None, None]:
+        """Allow iteration over this Program to yield its subjects."""
+        yield from self.get_subjects()

pyhive/src/types/queue.py

@@ -0,0 +1,150 @@
+"""Queue model for the Hive API (auto-generated).
+
+This module contains the :class:`Queue` dataclass which represents a
+queue entry returned by the Hive API. The class provides simple
+serialization helpers and lazily-resolved relationship properties.
+"""
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+
+from attrs import define
+from attrs import field
+from .common import UNSET, Unset
+from .core_item import HiveCoreItem
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .module import Module
+    from .program import Program
+    from .subject import Subject
+    from .user import User
+
+T = TypeVar("T", bound="Queue")
+
+
+@define
+class Queue(HiveCoreItem):
+    """Queue model representing a student/program/module queue entry.
+
+    Attributes mirror the API JSON keys; relationship properties (``user``,
+    ``module``, ``subject``, ``program``) lazily load the referenced
+    objects using the supplied ``hive_client``.
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    name: str
+    user_name: None | str
+    subject_id: None | int
+    subject_name: None | str
+    subject_color: None | str
+    subject_symbol: None | str
+    module_name: None | str
+    module_order: None | str
+    program_id: int
+    program_name: str
+    description: None | Unset | str = UNSET
+
+    module_id: None | Unset | int = UNSET
+    user_id: None | Unset | int = UNSET
+
+    _user: "User | None" = field(init=False, default=None)
+    _module: "Module | None" = field(init=False, default=None)
+    _subject: "Subject | None" = field(init=False, default=None)
+    _program: "Program | None" = field(init=False, default=None)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable dictionary of this Queue.
+
+        The returned mapping only includes optional keys when they are not
+        :data:`UNSET`.
+        """
+        return {
+            "id": self.id,
+            "name": self.name,
+            "user_id": self.user_id,
+            "user_name": self.user_name,
+            "subject_id": self.subject_id,
+            "subject_name": self.subject_name,
+            "subject_color": self.subject_color,
+            "subject_symbol": self.subject_symbol,
+            "module_id": self.module_id,
+            "module_name": self.module_name,
+            "module_order": self.module_order,
+            "program_id": self.program_id,
+            "program_name": self.program_name,
+            **(
+                {"description": self.description}
+                if self.description is not UNSET
+                else {}
+            ),
+            **({"module": self.module} if self.module is not UNSET else {}),
+            **({"user": self.user} if self.user_id is not UNSET else {}),
+        }
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        """Create a :class:`Queue` instance from a mapping (typically parsed JSON).
+
+        Args:
+            src_dict: Mapping with keys matching the API response.
+            hive_client: Hive client used to lazily resolve relationships.
+
+        Returns:
+            A populated :class:`Queue` instance.
+        """
+        d = dict(src_dict)
+
+        def _optional(data: object) -> Any:
+            return data if not isinstance(data, Unset) else UNSET
+
+        return cls(
+            hive_client=hive_client,
+            id=d.pop("id"),
+            name=d.pop("name"),
+            user_id=cast("None | int", d.pop("user_id")),
+            user_name=cast("None | str", d.pop("user_name")),
+            subject_id=cast("None | int", d.pop("subject_id")),
+            subject_name=cast("None | str", d.pop("subject_name")),
+            subject_color=cast("None | str", d.pop("subject_color")),
+            subject_symbol=cast("None | str", d.pop("subject_symbol")),
+            module_id=cast("None | int", d.pop("module_id")),
+            module_name=cast("None | str", d.pop("module_name")),
+            module_order=cast("None | str", d.pop("module_order")),
+            program_id=d.pop("program_id"),
+            program_name=d.pop("program_name"),
+            description=_optional(d.pop("description", UNSET)),
+        )
+
+    @property
+    def user(self) -> "User | None":
+        """Lazily return the :class:`User` associated with this queue entry.
+
+        Returns None when no user_id is set.
+        """
+        if self._user is None and isinstance(self.user_id, int):
+            self._user = self.hive_client.get_user(self.user_id)
+        return self._user
+
+    @property
+    def module(self) -> "Module | None":
+        """Lazily return the :class:`Module` referenced by this queue entry.
+
+        Returns None when no module_id is present.
+        """
+        if self._module is None and isinstance(self.module_id, int):
+            self._module = self.hive_client.get_module(self.module_id)
+        return self._module
+
+    @property
+    def subject(self) -> "Subject | None":
+        """Return the resolved :class:`Subject` or None if not available."""
+        if isinstance(self.subject_id, int):
+            return self.hive_client.get_subject(self.subject_id)
+        return None
+
+    @property
+    def program(self) -> "Program":
+        """Return the resolved :class:`Program` for this queue entry."""
+        return self.hive_client.get_program(self.program_id)

pyhive/src/types/queue_item.py

@@ -0,0 +1,88 @@
+"""A single item in a learning queue, either referencing an exercise or another queue."""
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, Union
+
+from attrs import define
+from .common import UNSET, Unset
+from .enums.queue_rule_enum import QueueRuleEnum
+from .core_item import HiveCoreItem
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .exercise import Exercise
+    from .queue import Queue
+
+T = TypeVar("T", bound="QueueItem")
+
+
+@define
+class QueueItem(HiveCoreItem):
+    """A single item in a learning queue, either referencing an exercise or another queue."""
+
+    hive_client: "HiveClient"
+    id: int
+    order: int
+    exercise: Union["Exercise", None]
+    nested_queue: Union["Queue", None]
+    queue_rule: QueueRuleEnum
+    enabled: bool
+    continue_on_redo: Unset | bool = UNSET
+
+    def to_dict(self) -> dict[str, Any]:
+        from .exercise import (  # pylint: disable=import-outside-toplevel
+            Exercise,
+        )
+        from .queue import Queue  # pylint: disable=import-outside-toplevel
+
+        return {
+            "id": self.id,
+            "order": self.order,
+            "exercise": (
+                self.exercise.to_dict()
+                if isinstance(self.exercise, Exercise)
+                else self.exercise
+            ),
+            "nested_queue": (
+                self.nested_queue.to_dict()
+                if isinstance(self.nested_queue, Queue)
+                else self.nested_queue
+            ),
+            "queue_rule": self.queue_rule.value,
+            "enabled": self.enabled,
+            **(
+                {"continue_on_redo": self.continue_on_redo}
+                if self.continue_on_redo is not UNSET
+                else {}
+            ),
+        }
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        from .exercise import (  # pylint: disable=import-outside-toplevel
+            Exercise,
+        )
+        from .queue import Queue  # pylint: disable=import-outside-toplevel
+
+        d = dict(src_dict)
+
+        def _parse_exercise(data: dict[str, Any] | None) -> Union["Exercise", None]:
+            if data is None:
+                return data
+            return Exercise.from_dict(data, hive_client=hive_client)
+
+        def _parse_nested_queue(data: dict[str, Any] | None) -> Union["Queue", None]:
+            if data is None:
+                return data
+            return Queue.from_dict(data, hive_client=hive_client)
+
+        return cls(
+            hive_client=hive_client,
+            id=d.pop("id"),
+            order=d.pop("order"),
+            exercise=_parse_exercise(d.pop("exercise")),
+            nested_queue=_parse_nested_queue(d.pop("nested_queue")),
+            queue_rule=QueueRuleEnum(d.pop("queue_rule")),
+            enabled=d.pop("enabled"),
+            continue_on_redo=d.pop("continue_on_redo", UNSET),
+        )

pyhive/src/types/subject.py

@@ -0,0 +1,156 @@
+"""Defines the Subject type and related functionality for the Hive API Python bindings."""
+
+from collections.abc import Generator, Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+
+from attrs import define, field
+from .core_item import HiveCoreItem
+from .enums.sync_status_enum import SyncStatusEnum
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .module import Module
+    from .program import Program
+
+T = TypeVar("T", bound="Subject")
+
+
+@define
+class Subject(HiveCoreItem):
+    """Represents a Subject in the Hive system.
+
+    Attributes:
+        hive_client (HiveClient): Reference to the Hive API client.
+        id (int): Subject ID.
+        symbol (str): Subject symbol.
+        parent_program_id (int): ID of the parent Program.
+        color (str): Subject color (hex code or name).
+        name (str): Display name.
+        parent_program_name (str): Name of the parent Program.
+        sync_status (SyncStatusEnum): Status of subject synchronization.
+        sync_message (str | None): Optional sync error or status message.
+        segel_path (str): Staff-accessible path on shared drive.
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    symbol: str
+    parent_program_id: int
+    color: str
+    name: str
+    parent_program_name: str
+    sync_status: SyncStatusEnum
+    sync_message: str | None
+    segel_path: str
+    _parent_program: "Program | None" = field(init=False, default=None)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the Subject to a dictionary."""
+        return {
+            "id": self.id,
+            "symbol": self.symbol,
+            "parent_program": self.parent_program_id,
+            "color": self.color,
+            "name": self.name,
+            "parent_program_name": self.parent_program_name,
+            "sync_status": self.sync_status.value,
+            "sync_message": self.sync_message,
+            "segel_path": self.segel_path,
+        }
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        """Deserialize a Subject from a dictionary.
+
+        Args:
+            src_dict: A dictionary containing Subject data.
+            hive_client: An instance of HiveClient.
+
+        Returns:
+            A Subject instance.
+
+        """
+        return cls(
+            hive_client=hive_client,
+            id=src_dict["id"],
+            symbol=src_dict["symbol"],
+            parent_program_id=src_dict["parent_program"],
+            color=src_dict["color"],
+            name=src_dict["name"],
+            parent_program_name=src_dict["parent_program_name"],
+            sync_status=SyncStatusEnum(src_dict["sync_status"]),
+            sync_message=cast("str | None", src_dict.get("sync_message")),
+            segel_path=src_dict["segel_path"],
+        )
+
+    @property
+    def parent_program(self) -> "Program":
+        """Lazily load and return the parent Program.
+
+        Returns:
+            Program: The parent program instance.
+
+        """
+        if self._parent_program is None:
+            self._parent_program = self.hive_client.get_program(self.parent_program_id)
+        return self._parent_program
+
+    def get_modules(self) -> Generator["Module"]:
+        """Retrieve all modules associated with this subject.
+
+        Returns:
+            Generator[Module]: Generator of Module instances.
+
+        """
+        return self.hive_client.get_modules(parent_subject__id=self.id)
+
+    def get_module(self, module_name: str) -> "Module":
+        """Retrieve a specific module by name within this subject.
+
+        Args:
+            module_name (str): The name of the module to retrieve.
+
+        Returns:
+            Module: The Module instance if found.
+
+        """
+        modules = list(
+            self.hive_client.get_modules(
+                parent_subject__id=self.id, module_name=module_name
+            )
+        )
+        if len(modules) == 0:
+            raise ValueError(
+                f"Module '{module_name}' not found in subject '{self.name}'"
+            )
+        if len(modules) > 1:
+            raise ValueError(
+                f"Multiple modules named '{module_name}' found in subject '{self.name}'"
+            )
+        return modules[0]
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, Subject):
+            return False
+        return self.id == value.id and self.parent_program == value.parent_program
+
+    def __lt__(self, value: object) -> bool:
+        if not isinstance(value, Subject):
+            return NotImplemented
+        return self.symbol < value.symbol
+
+    def __iter__(self) -> Generator["Module", None, None]:
+        """Allow iteration over this Subject to yield its modules."""
+        yield from self.get_modules()
+
+    def __hash__(self) -> int:
+        return hash(
+            (
+                self.id,
+                self.parent_program_id,
+            )
+        )
+
+
+SubjectLike = TypeVar("SubjectLike", Subject, int)