PyHiveLMS 1.0.0__py3-none-any.whl

pyhive/src/types/help_.py

@@ -0,0 +1,275 @@
+"""Model for student help requests (auto-generated).
+
+This module defines the :class:`Help` model used to represent student
+help requests and provides serialization helpers.
+"""
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, Union, cast
+
+from attr import field
+from attrs import define
+from .common import UNSET, Unset
+from .enums.help_status_enum import HelpStatusEnum
+from .enums.help_type_enum import HelpTypeEnum
+from .enums.visibility_enum import VisibilityEnum
+from .core_item import HiveCoreItem
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .user import User
+    from .exercise import Exercise
+    from .help_response_segel_nested import HelpResponseSegelNested
+    from .notification_nested import NotificationNested
+
+
+T = TypeVar("T", bound="Help")
+
+
+@define
+class Help(HiveCoreItem):
+    """A student's help request.
+
+    Attributes:
+    id (int):
+    user (int):
+    checker (Union[None, int]):
+    checker_first_name (str):
+    checker_last_name (str):
+    is_subscribed (bool):
+    help_type (HelpTypeEnum):
+        * `Exercise` - Exercise
+        * `Medical` - Medical
+        * `Error` - Error
+        * `Music` - Music
+        * `Request` - Request
+        * `Other` - Other
+        * `Chat` - Chat
+    help_status (HelpStatusEnum):
+        * `Resolved` - Resolved
+        * `Open` - Open
+    for_exercise (Union['Exercise', None]):
+    responses (list['HelpResponseSegelNested']):
+    notifications (list['NotificationNested']):
+    title (Union[Unset, str]):
+    visibility (Union[Unset, VisibilityEnum]):
+        * `All Staff` - Allstaff
+        * `All Staff And Checkers` - Allstaffandcheckers
+        * `Author Only` - Authoronly
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    user_id: int
+    _user: Union["User", None] = field(init=False, default=None)
+    checker_id: None | int
+    _checker: Union["User", None] = field(init=False, default=None)
+    checker_first_name: str
+    checker_last_name: str
+    is_subscribed: bool
+    help_type: HelpTypeEnum
+    help_status: HelpStatusEnum
+    for_exercise_id: int | None
+    _for_exercise: Union["Exercise", None] = field(init=False, default=None)
+    responses: list["HelpResponseSegelNested"]
+    notifications: list["NotificationNested"]
+    title: Unset | str = UNSET
+    visibility: Unset | VisibilityEnum = UNSET
+
+    def to_dict(self) -> dict[str, Any]:  # pylint: disable=too-many-locals
+        """Serialize this Help instance to a plain dictionary.
+
+        Returns:
+            A JSON-serializable mapping representing this help request.
+        """
+
+        # Import locally to avoid circular imports at module import time.
+        # Keep the import local but silence pylint's import-outside-toplevel.
+        from .exercise import (  # pylint: disable=import-outside-toplevel
+            Exercise,
+        )
+
+        # Keep the attribute name `id` as generated; silence redefined-builtin warning.
+        id = self.id  # pylint: disable=redefined-builtin
+
+        user = self.user
+
+        checker_id = self.checker_id
+
+        checker_first_name = self.checker_first_name
+
+        checker_last_name = self.checker_last_name
+
+        is_subscribed = self.is_subscribed
+
+        help_type = self.help_type.value
+
+        help_status = self.help_status.value
+
+        for_exercise: None | dict[str, Any]
+        for_exercise = (
+            self.for_exercise.to_dict()
+            if isinstance(self.for_exercise, Exercise)
+            else self.for_exercise
+        )
+
+        responses: list[dict[str, Any]] = []
+        for responses_item_data in self.responses:
+            responses_item = responses_item_data.to_dict()
+            responses.append(responses_item)
+
+        notifications: list[dict[str, Any]] = []
+        for notifications_item_data in self.notifications:
+            notifications_item = notifications_item_data.to_dict()
+            notifications.append(notifications_item)
+
+        title = self.title
+
+        visibility: Unset | str = UNSET
+        if not isinstance(self.visibility, Unset):
+            visibility = self.visibility.value
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(
+            {
+                "id": id,
+                "user": user,
+                "checker": checker_id,
+                "checker_first_name": checker_first_name,
+                "checker_last_name": checker_last_name,
+                "is_subscribed": is_subscribed,
+                "help_type": help_type,
+                "help_status": help_status,
+                "for_exercise": for_exercise,
+                "responses": responses,
+                "notifications": notifications,
+            },
+        )
+        if title is not UNSET:
+            field_dict["title"] = title
+        if visibility is not UNSET:
+            field_dict["visibility"] = visibility
+
+        return field_dict
+
+    @classmethod
+    def from_dict(  # pylint: disable=too-many-locals
+        cls, src_dict: Mapping[str, Any], hive_client: "HiveClient"
+    ) -> Self:
+        """Deserialize a Help instance from a mapping.
+
+        Args:
+            src_dict: The source mapping (typically parsed JSON).
+            hive_client: The HiveClient used for lazy-loading related objects.
+
+        Returns:
+            A populated :class:`Help` instance.
+        """
+
+        # Local imports to avoid runtime import cycles; keep but silence pylint.
+        from .help_response_segel_nested import (  # pylint: disable=import-outside-toplevel
+            HelpResponseSegelNested,
+        )
+        from .notification_nested import (  # pylint: disable=import-outside-toplevel
+            NotificationNested,
+        )
+
+        d = dict(src_dict)
+        id = d.pop("id")
+
+        user_id = d.pop("user")
+
+        def _parse_checker(data: object) -> None | int:
+            if data is None:
+                return data
+            return cast("None | int", data)
+
+        checker_id = _parse_checker(d.pop("checker"))
+
+        checker_first_name = d.pop("checker_first_name")
+
+        checker_last_name = d.pop("checker_last_name")
+
+        is_subscribed = d.pop("is_subscribed")
+
+        help_type = HelpTypeEnum(d.pop("help_type"))
+
+        help_status = HelpStatusEnum(d.pop("help_status"))
+
+        def _parse_for_exercise(data: object) -> int | None:
+            if data is None:
+                return data
+            try:
+                if not isinstance(data, dict):
+                    raise TypeError
+                return cast("int", data["id"])
+            except Exception:  # pylint: disable=broad-except
+                # When the structure is unexpected, treat as missing.
+                return None
+
+        for_exercise_id = _parse_for_exercise(d.pop("for_exercise"))
+
+        responses = [
+            HelpResponseSegelNested.from_dict(
+                responses_item_data, hive_client=hive_client
+            )
+            for responses_item_data in d.pop("responses")
+        ]
+
+        notifications: list[NotificationNested] = [
+            NotificationNested.from_dict(
+                notifications_item_data, hive_client=hive_client
+            )
+            for notifications_item_data in d.pop("notifications")
+        ]
+
+        title = d.pop("title", UNSET)
+
+        _visibility = d.pop("visibility", UNSET)
+        visibility: Unset | VisibilityEnum
+        visibility = (
+            UNSET if isinstance(_visibility, Unset) else VisibilityEnum(_visibility)
+        )
+
+        return cls(
+            id=id,
+            user_id=user_id,
+            checker_id=checker_id,
+            checker_first_name=checker_first_name,
+            checker_last_name=checker_last_name,
+            is_subscribed=is_subscribed,
+            help_type=help_type,
+            help_status=help_status,
+            for_exercise_id=for_exercise_id,
+            responses=responses,
+            notifications=notifications,
+            title=title,
+            visibility=visibility,
+            hive_client=hive_client,
+        )
+
+    @property
+    def for_exercise(self) -> Union["Exercise", None]:
+        """Lazily load and return the related Exercise, if any.
+
+        Returns:
+            The resolved :class:`Exercise` instance or None when not set.
+        """
+        if self.for_exercise_id is None:
+            return None
+        if self._for_exercise is None:
+            self._for_exercise = self.hive_client.get_exercise(self.for_exercise_id)
+        return self._for_exercise
+
+    @property
+    def user(self) -> "User":
+        """User which opened this help request.
+
+        Returns:
+            User: The user instance.
+
+        """
+        if self._user is None:
+            self._user = self.hive_client.get_user(self.user_id)
+        return self._user

pyhive/src/types/help_response.py

@@ -0,0 +1,113 @@
+"""Model definition for help responses in the Hive system.
+
+Represents a reply to a help request, which may include resolution,
+comments, attachments, and display preferences.
+"""
+
+import datetime
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+
+from attrs import define
+from attrs import field
+from dateutil.parser import isoparse
+from .common import UNSET, Unset
+from .core_item import HiveCoreItem
+from .enums.help_response_type_enum import HelpResponseTypeEnum
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .user import User
+
+T = TypeVar("T", bound="HelpResponse")
+
+
+@define
+class HelpResponse(HiveCoreItem):
+    """A response to a help request.
+
+    Attributes:
+        id: Unique identifier for the response.
+        user: ID of the responding user.
+        date: Timestamp of the response.
+        response_type: Type of the response (e.g., Resolve, Open, Comment).
+        contents: Optional text content of the response.
+        file_name: Optional name of an attached file.
+        dear_student: Whether to include a "Dear student" greeting. Default is True.
+        hide_checker_name: If True, the name of the checker is hidden.
+        segel_only: If True, the response is visible only to staff.
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    user_id: int
+    date: datetime.datetime
+    response_type: HelpResponseTypeEnum
+    contents: None | Unset | str = UNSET
+    file_name: Unset | str = UNSET
+    dear_student: Unset | bool = True
+    hide_checker_name: Unset | bool = UNSET
+    segel_only: Unset | bool = UNSET
+
+    # Lazy-loaded objects
+    _user: "User | None" = field(init=False, default=None)
+
+    @property
+    def user(self) -> "User":
+        """Returns the User object associated with this instance.
+
+        If the User object has not been retrieved yet,
+         it fetches the user using the hive_client and caches it for future calls.
+
+        Returns:
+            User: The user associated with this instance.
+
+        """
+        if self._user is None:
+            self._user = self.hive_client.get_user(self.user_id)
+        return self._user
+
+    def to_dict(self) -> dict[str, Any]:
+        contents = UNSET if isinstance(self.contents, Unset) else self.contents
+
+        field_dict: dict[str, Any] = {
+            "id": self.id,
+            "user": self.user_id,
+            "date": self.date.isoformat(),
+            "response_type": self.response_type.value,
+        }
+        if contents is not UNSET:
+            field_dict["contents"] = contents
+        if self.file_name is not UNSET:
+            field_dict["file_name"] = self.file_name
+        if self.dear_student is not UNSET:
+            field_dict["dear_student"] = self.dear_student
+        if self.hide_checker_name is not UNSET:
+            field_dict["hide_checker_name"] = self.hide_checker_name
+        if self.segel_only is not UNSET:
+            field_dict["segel_only"] = self.segel_only
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        d = dict(src_dict)
+
+        def _parse_optional_str(data: object) -> None | Unset | str:
+            if data is None or isinstance(data, Unset):
+                return data
+            return cast("str", data)
+
+        return cls(
+            hive_client=hive_client,
+            id=d.pop("id"),
+            user_id=d.pop("user"),
+            date=isoparse(d.pop("date")),
+            response_type=HelpResponseTypeEnum(d.pop("response_type")),
+            contents=_parse_optional_str(d.pop("contents", UNSET)),
+            file_name=d.pop("file_name", UNSET),
+            dear_student=d.pop("dear_student", UNSET),
+            hide_checker_name=d.pop("hide_checker_name", UNSET),
+            segel_only=d.pop("segel_only", UNSET),
+        )

pyhive/src/types/help_response_segel_nested.py

@@ -0,0 +1,129 @@
+""" "This module contains the HelpResponseSegelNested class."""
+
+import datetime
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+
+from attrs import define
+from dateutil.parser import isoparse
+from .common import UNSET, Unset
+from .enums.help_response_type_enum import HelpResponseTypeEnum
+from .core_item import HiveCoreItem
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+
+T = TypeVar("T", bound="HelpResponseSegelNested")
+
+
+@define
+class HelpResponseSegelNested(HiveCoreItem):
+    """Attributes:
+    id (int):
+    user (int):
+    date (datetime.datetime):
+    response_type (HelpResponseTypeEnum):
+        * `Resolve` - Resolve
+        * `Open` - Open
+        * `Comment` - Comment
+    contents (Union[None, Unset, str]):
+    file_name (Union[Unset, str]):
+    dear_student (Union[Unset, bool]):  Default: True.
+    hide_checker_name (Union[Unset, bool]):
+    segel_only (Union[Unset, bool]):
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    user: int
+    date: datetime.datetime
+    response_type: HelpResponseTypeEnum
+    contents: None | Unset | str = UNSET
+    file_name: Unset | str = UNSET
+    dear_student: Unset | bool = True
+    hide_checker_name: Unset | bool = UNSET
+    segel_only: Unset | bool = UNSET
+
+    def to_dict(self) -> dict[str, Any]:
+        id = self.id
+
+        user = self.user
+
+        date = self.date.isoformat()
+
+        response_type = self.response_type.value
+
+        contents: None | Unset | str
+        contents = UNSET if isinstance(self.contents, Unset) else self.contents
+
+        file_name = self.file_name
+
+        dear_student = self.dear_student
+
+        hide_checker_name = self.hide_checker_name
+
+        segel_only = self.segel_only
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(
+            {
+                "id": id,
+                "user": user,
+                "date": date,
+                "response_type": response_type,
+            },
+        )
+        if contents is not UNSET:
+            field_dict["contents"] = contents
+        if file_name is not UNSET:
+            field_dict["file_name"] = file_name
+        if dear_student is not UNSET:
+            field_dict["dear_student"] = dear_student
+        if hide_checker_name is not UNSET:
+            field_dict["hide_checker_name"] = hide_checker_name
+        if segel_only is not UNSET:
+            field_dict["segel_only"] = segel_only
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        d = dict(src_dict)
+        id = d.pop("id")
+
+        user = d.pop("user")
+
+        date = isoparse(d.pop("date"))
+
+        response_type = HelpResponseTypeEnum(d.pop("response_type"))
+
+        def _parse_contents(data: object) -> None | Unset | str:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast("None | Unset | str", data)
+
+        contents = _parse_contents(d.pop("contents", UNSET))
+
+        file_name = d.pop("file_name", UNSET)
+
+        dear_student = d.pop("dear_student", UNSET)
+
+        hide_checker_name = d.pop("hide_checker_name", UNSET)
+
+        segel_only = d.pop("segel_only", UNSET)
+
+        return cls(
+            id=id,
+            user=user,
+            date=date,
+            response_type=response_type,
+            contents=contents,
+            file_name=file_name,
+            dear_student=dear_student,
+            hide_checker_name=hide_checker_name,
+            segel_only=segel_only,
+            hive_client=hive_client,
+        )

pyhive/src/types/module.py

@@ -0,0 +1,141 @@
+"""Module model definition for the Hive system.
+
+Represents a logical course module within a subject, supporting serialization,
+lazy loading of parent subject, and retrieval of exercises.
+"""
+
+from collections.abc import Generator, Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+
+from attrs import define
+from attrs import field
+from .enums.sync_status_enum import SyncStatusEnum
+from .exercise import Exercise
+from .program import HiveCoreItem
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .subject import Subject
+
+T = TypeVar("T", bound="Module")
+
+
+@define
+class Module(HiveCoreItem):
+    """Course Subject Module.
+
+    Attributes:
+        id: Unique identifier.
+        name: Name of the module.
+        parent_subject_id: ID of the parent subject.
+        order: Order of display within the subject.
+        sync_status: Synchronization status.
+        sync_message: Optional error or status message.
+        parent_program_name: Name of the program the subject belongs to.
+        parent_subject_name: Name of the parent subject.
+        parent_subject_symbol: Symbol of the parent subject.
+        segel_path: Network path accessible to staff.
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    name: str
+    parent_subject_id: int
+    order: str
+    sync_status: SyncStatusEnum
+    sync_message: None | str
+    parent_program_name: str
+    parent_subject_name: str
+    parent_subject_symbol: str
+    segel_path: str
+
+    _parent_subject: "Subject | None" = field(init=False, default=None)
+
+    @property
+    def parent_subject(self) -> "Subject":
+        """Lazily load and return the parent subject."""
+        if self._parent_subject is None:
+            self._parent_subject = self.hive_client.get_subject(self.parent_subject_id)
+        return self._parent_subject
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the module to a dictionary."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "parent_subject": self.parent_subject_id,
+            "order": self.order,
+            "sync_status": self.sync_status.value,
+            "sync_message": self.sync_message,
+            "parent_program_name": self.parent_program_name,
+            "parent_subject_name": self.parent_subject_name,
+            "parent_subject_symbol": self.parent_subject_symbol,
+            "segel_path": self.segel_path,
+        }
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        """Deserialize a module from a dictionary."""
+        d = dict(src_dict)
+        return cls(
+            hive_client=hive_client,
+            id=d["id"],
+            name=d["name"],
+            parent_subject_id=d["parent_subject"],
+            order=d["order"],
+            sync_status=SyncStatusEnum(d["sync_status"]),
+            sync_message=cast("None | str", d["sync_message"]),
+            parent_program_name=d["parent_program_name"],
+            parent_subject_name=d["parent_subject_name"],
+            parent_subject_symbol=d["parent_subject_symbol"],
+            segel_path=d["segel_path"],
+        )
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, Module):
+            return False
+        return self.id == value.id and self.parent_subject == value.parent_subject
+
+    def __lt__(self, value: object) -> bool:
+        if not isinstance(value, Module):
+            return NotImplemented
+        return self.order < value.order
+
+    def get_exercises(self) -> Generator[Exercise]:
+        """Fetch all exercises within this module."""
+        return self.hive_client.get_exercises(parent_module__id=self.id)
+
+    def get_exercise(self, exercise_name: str) -> Exercise:
+        """Fetch a specific exercise by name within this module."""
+        exercises = list(
+            self.hive_client.get_exercises(
+                parent_module__id=self.id,
+                exercise_name=exercise_name,
+            )
+        )
+
+        if len(exercises) == 0:
+            raise ValueError(
+                f"Exercise '{exercise_name}' not found in module '{self.name}'"
+            )
+        if len(exercises) > 1:
+            raise ValueError(
+                f"Multiple exercises named '{exercise_name}' found in module '{self.name}'"
+            )
+        return exercises[0]
+
+    def __iter__(self) -> Generator["Exercise", None, None]:
+        """Allow iteration over this Module to yield its exercises."""
+        yield from self.get_exercises()
+
+    def __hash__(self) -> int:
+        return hash(
+            (
+                self.id,
+                self.parent_subject_id,
+            )
+        )
+
+
+ModuleLike = TypeVar("ModuleLike", Module, int)