PyHiveLMS 5.12.0__py3-none-any.whl

pyhive/src/types/assignment.py

@@ -0,0 +1,192 @@
+"""Defines the Assignment type and related logic for representing student assignments in the Hive API."""
+
+import datetime
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+
+from attrs import define, field
+from dateutil.parser import isoparse
+from src.types.common import UNSET, Unset
+from src.types.core_item import HiveCoreItem
+from src.types.enums.assignment_status_enum import AssignmentStatusEnum
+from src.types.notification_nested import NotificationNested
+
+if TYPE_CHECKING:
+    from client import HiveClient
+    from src.types.exercise import Exercise
+    from src.types.user import User
+
+T = TypeVar("T", bound="Assignment")
+
+
+@define
+class Assignment(HiveCoreItem):
+    """Represents a student's assignment for an exercise.
+
+    Attributes:
+        hive_client: Reference to the Hive API client.
+        id: Unique assignment ID.
+        user_id: ID of the assigned student.
+        checker_id: ID of the assigned checker, or None.
+        checker_first_name: First name of the checker.
+        checker_last_name: Last name of the checker.
+        is_subscribed: Whether the student is subscribed to updates.
+        exercise_id: ID of the exercise.
+        assignment_status: Current state of the assignment.
+        patbas: Whether it's a PATBAS assignment.
+        notifications: List of related notifications.
+        last_staff_updated: Timestamp of the last staff update.
+        work_time: Total work time in minutes.
+        student_assignment_status: The student’s view of the assignment status.
+        description: Optional text description.
+        submission_count: Total number of submissions.
+        total_check_count: Number of total checks.
+        manual_check_count: Number of manual checks.
+        flagged: Whether the assignment is flagged for review.
+        timer: Optional timer state string.
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    user_id: int
+    checker_id: None | int
+    checker_first_name: str
+    checker_last_name: str
+    is_subscribed: bool
+    exercise_id: int
+    assignment_status: AssignmentStatusEnum
+    patbas: bool
+    notifications: list["NotificationNested"]
+    last_staff_updated: datetime.datetime
+    work_time: int
+    student_assignment_status: Unset | AssignmentStatusEnum = UNSET
+    description: None | Unset | str = UNSET
+    submission_count: Unset | int = UNSET
+    total_check_count: Unset | int = UNSET
+    manual_check_count: Unset | int = UNSET
+    flagged: Unset | bool = UNSET
+    timer: None | Unset | str = UNSET
+
+    # Lazy-loaded objects
+    _user: "User | None" = field(init=False, default=None)
+    _checker: "User | None" = field(init=False, default=None)
+    _exercise: "Exercise | None" = field(init=False, default=None)
+
+    @property
+    def user(self) -> "User":
+        """Lazily load and return the user this assignment belongs to."""
+        if self._user is None:
+            self._user = self.hive_client.get_user(self.user_id)
+        return self._user
+
+    @property
+    def checker(self) -> "User | None":
+        """Lazily load and return the checker (if any) assigned to this assignment."""
+        if self.checker_id is None:
+            return None
+        if self._checker is None:
+            self._checker = self.hive_client.get_user(self.checker_id)
+        return self._checker
+
+    @property
+    def exercise(self) -> "Exercise":
+        """Lazily load and return the exercise associated with this assignment."""
+        if self._exercise is None:
+            self._exercise = self.hive_client.get_exercise(self.exercise_id)
+        return self._exercise
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize Assignment to a dictionary."""
+        result: dict[str, None | str | int | list[dict[str, Any]]] = {
+            "id": self.id,
+            "user": self.user_id,
+            "checker": self.checker_id,
+            "checker_first_name": self.checker_first_name,
+            "checker_last_name": self.checker_last_name,
+            "is_subscribed": self.is_subscribed,
+            "exercise": self.exercise_id,
+            "assignment_status": self.assignment_status.value,
+            "patbas": self.patbas,
+            "notifications": [n.to_dict() for n in self.notifications],
+            "last_staff_updated": self.last_staff_updated.isoformat(),
+            "work_time": self.work_time,
+        }
+
+        # Conditionally include optional/unset fields
+        if not isinstance(self.student_assignment_status, Unset):
+            result["student_assignment_status"] = self.student_assignment_status.value
+        if not isinstance(self.description, Unset):
+            result["description"] = self.description
+        if not isinstance(self.submission_count, Unset):
+            result["submission_count"] = self.submission_count
+        if not isinstance(self.total_check_count, Unset):
+            result["total_check_count"] = self.total_check_count
+        if not isinstance(self.manual_check_count, Unset):
+            result["manual_check_count"] = self.manual_check_count
+        if not isinstance(self.flagged, Unset):
+            result["flagged"] = self.flagged
+        if not isinstance(self.timer, Unset):
+            result["timer"] = self.timer
+
+        return result
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        """Deserialize Assignment from a dictionary."""
+
+        d = dict(src_dict)
+
+        notifications = [
+            NotificationNested.from_dict(n, hive_client=hive_client)
+            for n in d.pop("notifications", [])
+        ]
+
+        student_assignment_status = (
+            AssignmentStatusEnum(d["student_assignment_status"])
+            if "student_assignment_status" in d
+            and not isinstance(d["student_assignment_status"], Unset)
+            else UNSET
+        )
+
+        description = d.pop("description", UNSET)
+        submission_count = d.pop("submission_count", UNSET)
+        total_check_count = d.pop("total_check_count", UNSET)
+        manual_check_count = d.pop("manual_check_count", UNSET)
+        flagged = d.pop("flagged", UNSET)
+        timer = d.pop("timer", UNSET)
+
+        return cls(
+            hive_client=hive_client,
+            id=d["id"],
+            user_id=d["user"],
+            checker_id=cast("int | None", d["checker"]),
+            checker_first_name=d["checker_first_name"],
+            checker_last_name=d["checker_last_name"],
+            is_subscribed=d["is_subscribed"],
+            exercise_id=d["exercise"],
+            assignment_status=AssignmentStatusEnum(d["assignment_status"]),
+            patbas=d["patbas"],
+            notifications=notifications,
+            last_staff_updated=isoparse(d["last_staff_updated"]),
+            work_time=d["work_time"],
+            student_assignment_status=student_assignment_status,
+            description=cast("str | None | Unset", description),
+            submission_count=cast("int | Unset", submission_count),
+            total_check_count=cast("int | Unset", total_check_count),
+            manual_check_count=cast("int | Unset", manual_check_count),
+            flagged=cast("bool | Unset", flagged),
+            timer=cast("str | None | Unset", timer),
+        )
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, Assignment):
+            return False
+        return (
+            self.id == value.id
+            and self.exercise_id == value.exercise_id
+            and self.user_id == value.user_id
+            and self.checker_id == value.checker_id
+            and self.assignment_status == value.assignment_status
+            and self.exercise == value.exercise
+        )

pyhive/src/types/class_.py

@@ -0,0 +1,113 @@
+"""
+Defines the Class type representing a school class/group in a program,
+including serialization and lazy-loading of related objects.
+"""
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, TypeVar, cast
+
+from attrs import define, field
+from src.types.common import UNSET, Unset
+from src.types.core_item import HiveCoreItem
+from src.types.enums.class_type_enum import ClassTypeEnum
+
+if TYPE_CHECKING:
+    from client import HiveClient
+    from src.types.program import Program
+    from src.types.user import User
+
+T = TypeVar("T", bound="Class")
+
+
+@define
+class Class(HiveCoreItem):
+    """Represents a school class/group in a program.
+
+    Attributes:
+        id: Unique class ID.
+        name: Internal name.
+        display_name: Display name for UI.
+        program_id: ID of the associated program.
+        user_ids: List of user IDs assigned to this class.
+        program_name: Name of the program.
+        email: Optional class email address.
+        type_: Type of class, e.g., Room or Student Group.
+        description: Optional description text.
+
+    """
+
+    hive_client: "HiveClient"
+    id: int
+    name: str
+    display_name: str
+    program_id: int
+    user_ids: list[int]
+    program_name: str
+    email: Unset | str = UNSET
+    type_: Unset | ClassTypeEnum = UNSET
+    description: None | Unset | str = UNSET
+
+    # Lazy-loaded fields
+    _program: "Program | None" = field(init=False, default=None)
+    _users: "list[User] | None" = field(init=False, default=None)
+
+    @property
+    def program(self) -> "Program":
+        """Lazily load the associated Program object."""
+        if self._program is None:
+            self._program = self.hive_client.get_program(self.program_id)
+        return self._program
+
+    @property
+    def users(self) -> list["User"]:
+        """Lazily load the list of User objects in this class."""
+        if self._users is None:
+            self._users = [self.hive_client.get_user(uid) for uid in self.user_ids]
+        return self._users
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize Class to dictionary form."""
+        result: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "display_name": self.display_name,
+            "program": self.program_id,
+            "users": self.user_ids,
+            "program__name": self.program_name,
+        }
+
+        if not isinstance(self.email, Unset):
+            result["email"] = self.email
+        if not isinstance(self.type_, Unset):
+            result["type"] = self.type_.value
+        if not isinstance(self.description, Unset):
+            result["description"] = self.description
+
+        return result
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any], hive_client: "HiveClient") -> Self:
+        """Deserialize Class from dictionary form."""
+        d = dict(src_dict)
+
+        return cls(
+            hive_client=hive_client,
+            id=d["id"],
+            name=d["name"],
+            display_name=d["display_name"],
+            program_id=d["program"],
+            user_ids=cast("list[int]", d["users"]),
+            program_name=d["program__name"],
+            email=d.get("email", UNSET),
+            type_=(
+                UNSET
+                if isinstance((type_val := d.get("type", UNSET)), Unset)
+                else ClassTypeEnum(type_val)
+            ),
+            description=cast("None | Unset | str", d.get("description", UNSET)),
+        )
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, Class):
+            return False
+        return self.id == value.id and self.program_id == value.program_id

pyhive/src/types/common.py

@@ -0,0 +1,56 @@
+"""Contains some shared types for properties."""
+
+from collections.abc import Mapping, MutableMapping
+from http import HTTPStatus
+from typing import IO, BinaryIO, Generic, Literal, TypeVar, Union
+
+from attrs import define
+
+
+class Unset:  # pylint: disable=too-few-public-methods
+    """Sentinel type for unset optional values."""
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+
+UNSET: Unset = Unset()
+
+# The types that `httpx.Client(files=)` can accept, copied from that library.
+FileContent = Union[IO[bytes], bytes, str]
+FileTypes = Union[
+    # (filename, file (or bytes), content_type)
+    tuple[str | None, FileContent, str | None],
+    # (filename, file (or bytes), content_type, headers)
+    tuple[str | None, FileContent, str | None, Mapping[str, str]],
+]
+RequestFiles = list[tuple[str, FileTypes]]
+
+
+@define
+class File:
+    """Contains information for file uploads."""
+
+    payload: BinaryIO
+    file_name: str | None = None
+    mime_type: str | None = None
+
+    def to_tuple(self) -> FileTypes:
+        """Return a tuple representation that httpx will accept for multipart/form-data ."""
+        return self.file_name, self.payload, self.mime_type
+
+
+T = TypeVar("T")
+
+
+@define
+class Response(Generic[T]):
+    """A response from an endpoint."""
+
+    status_code: HTTPStatus
+    content: bytes
+    headers: MutableMapping[str, str]
+    parsed: T | None
+
+
+__all__ = ["UNSET", "File", "FileTypes", "RequestFiles", "Response", "Unset"]

pyhive/src/types/core_item.py

@@ -0,0 +1,22 @@
+"""Base class for Hive core items."""
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self
+
+if TYPE_CHECKING:
+    from client import HiveClient
+
+
+class HiveCoreItem:
+    """Base class for Hive core items."""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this HiveCoreItem instance to a plain dictionary."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_dict(
+        cls, src_dict: Mapping[str, Any], hive_client: "HiveClient"
+    ) -> Self:  # noqa: D102
+        """Deserialize a HiveCoreItem instance from a mapping."""
+        raise NotImplementedError

pyhive/src/types/enums/action_enum.py

@@ -0,0 +1,18 @@
+"""Enumeration of possible action states for auto-tests."""
+
+from enum import Enum
+
+
+class ActionEnum(str, Enum):
+    """Enumeration of possible action states for auto-tests."""
+
+    BUILT = "Built"
+    ERROR = "Error"
+    FINISHED = "Finished"
+    HANDLING = "Handling"
+    NO_CHECK = "No Check"
+    SENDING = "Sending"
+    SUCCESS = "Success"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/assignment_status_enum.py

@@ -0,0 +1,17 @@
+"""Enumeration for assignment statuses (auto-generated)."""
+
+from enum import Enum
+
+
+class AssignmentStatusEnum(str, Enum):
+    """The status of an assignment."""
+
+    AUTOCHECKED = "AutoChecked"
+    DONE = "Done"
+    NEW = "New"
+    REDO = "Redo"
+    SUBMITTED = "Submitted"
+    WORK_IN_PROGRESS = "Work In Progress"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/class_type_enum.py

@@ -0,0 +1,13 @@
+"""Enumeration of class types."""
+
+from enum import Enum
+
+
+class ClassTypeEnum(str, Enum):
+    """Enumeration of class types."""
+
+    ROOM = "Room"
+    STUDENT_GROUP = "Student Group"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/clearance_enum.py

@@ -0,0 +1,16 @@
+"""Enumeration for user clearance levels."""
+
+from enum import IntEnum
+
+
+class ClearanceEnum(IntEnum):
+    """Enumeration of user clearance levels in the Hive system."""
+
+    # TODO: Replace VALUE_X with actual clearance level names
+    VALUE_1 = 1
+    VALUE_2 = 2
+    VALUE_3 = 3
+    VALUE_5 = 5
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/event_type_enum.py

@@ -0,0 +1,14 @@
+"""Enumeration for event types (auto-generated)."""
+
+from enum import Enum
+
+
+class EventTypeEnum(str, Enum):
+    """Enumeration of possible event types in the Hive system."""
+
+    הרצאה = "הרצאה"  # pylint: disable=non-ascii-name
+    עע = "עע"  # pylint: disable=non-ascii-name
+    פתבס = "פתבס"  # pylint: disable=non-ascii-name
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/exercise_patbas_enum.py

@@ -0,0 +1,15 @@
+"""Enumeration for PATBAS settings (auto-generated)."""
+
+from enum import Enum
+
+
+class PatbasEnum(str, Enum):
+    """PATBAS settings."""
+
+    ALWAYS = "Always"
+    NEVER = "Never"
+    ON_DONE = "On Done"
+    STAFF_ONLY = "Staff Only"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/exercise_preview_types.py

@@ -0,0 +1,15 @@
+"""Enumeration for exercise preview types.
+This is the document type of the instructions for an exercise (auto-generated)."""
+
+from enum import Enum
+
+
+class ExercisePreviewTypes(str, Enum):
+    """Exercise preview types."""
+
+    DISABLED = "Disabled"
+    MARKDOWN = "Markdown"
+    PDF = "PDF"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/form_field_type_enum.py

@@ -0,0 +1,15 @@
+"""Enumeration for form field types (auto-generated)."""
+
+from enum import Enum
+
+
+class FormFieldTypeEnum(str, Enum):
+    """Enumeration of possible form field types."""
+
+    MULTIPLE = "multiple"
+    MULTIRESPONSE = "multiResponse"
+    NUMBER = "number"
+    TEXT = "text"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/gender_enum.py

@@ -0,0 +1,14 @@
+"""Enumeration for gender types."""
+
+from enum import Enum
+
+
+class GenderEnum(str, Enum):
+    """Enumeration of gender types."""
+
+    FEMALE = "Female"
+    MALE = "Male"
+    NONBINARY = "NonBinary"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/help_response_type_enum.py

@@ -0,0 +1,14 @@
+"""Enumeration for help response types (auto-generated)."""
+
+from enum import Enum
+
+
+class HelpResponseTypeEnum(str, Enum):
+    """Enumeration of possible help response types."""
+
+    COMMENT = "Comment"
+    OPEN = "Open"
+    RESOLVE = "Resolve"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/help_status_enum.py

@@ -0,0 +1,13 @@
+"""Help Status Enum"""
+
+from enum import Enum
+
+
+class HelpStatusEnum(str, Enum):
+    """Help Status Enum"""
+
+    OPEN = "Open"
+    RESOLVED = "Resolved"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/help_type_enum.py

@@ -0,0 +1,18 @@
+"""Enumeration for help request types (auto-generated)."""
+
+from enum import Enum
+
+
+class HelpTypeEnum(str, Enum):
+    """Enumeration of possible help request types."""
+
+    CHAT = "Chat"
+    ERROR = "Error"
+    EXERCISE = "Exercise"
+    MEDICAL = "Medical"
+    MUSIC = "Music"
+    OTHER = "Other"
+    REQUEST = "Request"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/queue_rule_enum.py

@@ -0,0 +1,15 @@
+"""Enumeration for exercise Queue Rules."""
+
+from enum import Enum
+
+
+class QueueRuleEnum(str, Enum):
+    """Enumeration for exercise Queue Rules."""
+
+    CHOOSE = "Choose"
+    WAIT_FOR_AUTOCHECKS = "Wait For AutoChecks"
+    WAIT_FOR_DONE = "Wait For Done"
+    WAIT_FOR_SUBMITTED = "Wait For Submitted"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/status_enum.py

@@ -0,0 +1,21 @@
+"""StatusEnum class representing various user statuses."""
+
+from enum import Enum
+
+
+class StatusEnum(str, Enum):
+    """Enumeration of user statuses."""
+
+    HOME = "Home"
+    MEDICAL = "Medical"
+    PERSONAL_TALK = "Personal Talk"
+    PRAYER = "Prayer"
+    PRESENT = "Present"
+    RAISED_HAND = "Raised Hand"
+    ROOM = "Room"
+    TOILET = "Toilet"
+    TOILET_REQUEST = "Toilet Request"
+    WORK_TALK = "Work Talk"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/sync_status_enum.py

@@ -0,0 +1,15 @@
+"""Enumeration for synchronization status (auto-generated)."""
+
+from enum import Enum
+
+
+class SyncStatusEnum(str, Enum):
+    """Enumeration of possible synchronization statuses."""
+
+    CREATING = "Creating"
+    DELETING = "Deleting"
+    ERROR = "Error"
+    NORMAL = "Normal"
+
+    def __str__(self) -> str:
+        return str(self.value)

pyhive/src/types/enums/visibility_enum.py

@@ -0,0 +1,14 @@
+"""Enumeration for visibility levels of help requests."""
+
+from enum import Enum
+
+
+class VisibilityEnum(str, Enum):
+    """Enumeration of visibility levels for help requests."""
+
+    ALL_STAFF = "All Staff"
+    ALL_STAFF_AND_CHECKERS = "All Staff And Checkers"
+    AUTHOR_ONLY = "Author Only"
+
+    def __str__(self) -> str:
+        return str(self.value)