PyHiveLMS 1.0.0__py3-none-any.whl

pyhive/src/authenticated_hive_client.py

@@ -0,0 +1,250 @@
+"""Authentication helpers and a small authenticated HTTP client for Hive.
+
+This module provides decorators that add retry and token-refresh behavior to
+HTTP calls and an internal ``_AuthenticatedHiveClient`` which wraps an
+:class:`httpx.Client` and handles login/refresh for the Hive API.
+"""
+
+import functools
+import time
+from collections.abc import Callable
+from types import TracebackType
+from typing import Any, TypeVar, cast
+
+import httpx
+
+F = TypeVar("F", bound=Callable[..., httpx.Response])
+
+MAX_RETRIES_ON_SERVER_ERRORS = 5
+INITIAL_BACKOFF_SECONDS = 0.5
+
+
+def _retry_on_bad_gateway(func: F) -> F:
+    """Decorator: retry a request when the server returns HTTP 502.
+
+    The wrapped function is expected to return an :class:`httpx.Response`.
+    Retries use exponential backoff and will re-raise the final response's
+    HTTP error if all retries fail.
+    """
+
+    @functools.wraps(func)
+    def wrapper(self: "_AuthenticatedHiveClient", *args: Any, **kwargs: Any):
+        delay = INITIAL_BACKOFF_SECONDS
+        if MAX_RETRIES_ON_SERVER_ERRORS <= 0:
+            raise ValueError("MAX_RETRIES_ON_SERVER_ERRORS must be greater than 0")
+        response = None
+        for attempt in range(MAX_RETRIES_ON_SERVER_ERRORS):
+            response = func(self, *args, **kwargs)
+            if response.status_code != httpx.codes.BAD_GATEWAY.value:
+                return response
+            if attempt < MAX_RETRIES_ON_SERVER_ERRORS - 1:
+                time.sleep(delay)
+                delay *= 2
+        assert response is not None
+        response.raise_for_status()
+        return response
+
+    return cast("F", wrapper)
+
+
+def _refresh_token_on_unauthorized(func: F) -> F:
+    """Decorator: refresh access token and retry on HTTP 401 Unauthorized.
+
+    If the wrapped function returns a 401 status, the client's
+    ``_refresh_access_token`` is called and the request is retried once.
+    """
+
+    @functools.wraps(func)
+    def wrapper(self: "_AuthenticatedHiveClient", *args: Any, **kwargs: Any):
+        response = func(self, *args, **kwargs)
+        if response.status_code == httpx.codes.UNAUTHORIZED.value:
+            self._refresh_access_token()  # pylint: disable=protected-access
+            response = func(self, *args, **kwargs)
+        response.raise_for_status()
+        return response
+
+    return cast("F", wrapper)
+
+
+def _with_retries_and_token_refresh(func: F) -> F:
+    """Compose the retry and token-refresh decorators.
+
+    Use this to wrap HTTP methods so they automatically handle transient
+    502 errors and expired access tokens.
+    """
+
+    return _refresh_token_on_unauthorized(_retry_on_bad_gateway(func))
+
+
+class _AuthenticatedHiveClient:
+    """Internal class used to handle authentication and re-authentication with Hive web endpoint."""
+
+    _refresh_token: str
+    _access_token: str
+    _session: httpx.Client
+    username: str
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        username: str,
+        password: str,
+        hive_url: str,
+        *,
+        timeout: httpx.Timeout | float | None = None,
+        headers: dict[str, str] | None = None,
+        verify: bool | str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Create an authenticated client.
+
+        Common HTTP client options may be provided explicitly (typed) or via
+        ``**kwargs`` and will be forwarded to :class:`httpx.Client`.
+
+        Typed kwargs provided (timeout, headers, verify) take precedence; the
+        rest are forwarded from ``kwargs``.
+        """
+        self.username = username
+        self.hive_url = hive_url
+
+        client_kwargs: dict[str, Any] = {}
+        if timeout is not None:
+            client_kwargs["timeout"] = timeout
+        if headers is not None:
+            client_kwargs["headers"] = headers
+        if verify is not None:
+            client_kwargs["verify"] = verify
+
+        # Include any other httpx.Client kwargs passed in **kwargs
+        client_kwargs.update(kwargs)
+
+        self._session = httpx.Client(
+            base_url=hive_url,
+            **client_kwargs,
+        ).__enter__()
+        self._login(username, password)
+
+    def __enter__(self) -> "_AuthenticatedHiveClient":
+        """Enter context manager and return this client instance.
+
+        The underlying :class:`httpx.Client` is managed by this object's
+        lifecycle; entering the context returns the authenticated client so
+        callers can perform API calls.
+        """
+
+        return self
+
+    def __exit__(
+        self,
+        type_: type[BaseException] | None,
+        value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None:
+        """Exit the context and close the underlying httpx session.
+
+        This delegates to the managed :class:`httpx.Client`'s ``__exit__``
+        method to ensure resources are released.
+        """
+
+        self._session.__exit__(type_, value, traceback)
+
+    def _login(self, username: str, password: str) -> None:
+        """Perform an authentication request and store access/refresh tokens.
+
+        This sets the ``Authorization`` header on the underlying session.
+        """
+
+        response = self._session.post(
+            "/api/core/token/",
+            json={"username": username, "password": password},
+        )
+        response.raise_for_status()
+        data = response.json()
+        self._access_token = data["access"]
+        self._refresh_token = data["refresh"]
+
+        self._session.headers.update({"Authorization": f"Bearer {self._access_token}"})
+
+    def _refresh_access_token(self) -> None:
+        """Refresh the access token using the stored refresh token.
+
+        Updates the stored access and refresh tokens and the session header.
+        """
+
+        response = self._session.post(
+            "/api/core/token/refresh/",
+            json={"refresh": self._refresh_token},
+        )
+        response.raise_for_status()
+        data = response.json()
+        self._access_token = data["access"]
+        self._refresh_token = data["refresh"]
+
+        self._session.headers.update({"Authorization": f"Bearer {self._access_token}"})
+
+    @_with_retries_and_token_refresh
+    def _get(
+        self, endpoint: str, params: httpx.QueryParams | None = None
+    ) -> httpx.Response:
+        """Low-level GET that returns an :class:`httpx.Response`.
+
+        This is decorated to handle retries and token refresh automatically.
+        """
+
+        return self._session.get(endpoint, params=params, headers={"Accept": "application/json"})
+
+    @_with_retries_and_token_refresh
+    def _post(self, endpoint: str, data: dict[Any, Any]) -> httpx.Response:
+        """Low-level POST that returns an :class:`httpx.Response` with JSON body.
+
+        The ``data`` is JSON-encoded into the request body.
+        """
+
+        return self._session.post(endpoint, json=data)
+
+    @_with_retries_and_token_refresh
+    def _patch(self, endpoint: str, data: dict[Any, Any]) -> httpx.Response:
+        """Low-level PATCH request; returns :class:`httpx.Response`.
+
+        The ``data`` is JSON-encoded into the request body.
+        """
+
+        return self._session.patch(endpoint, json=data)
+
+    @_with_retries_and_token_refresh
+    def _delete(self, endpoint: str) -> httpx.Response:
+        """Low-level DELETE request; returns :class:`httpx.Response`."""
+
+        return self._session.delete(endpoint)
+
+    @_with_retries_and_token_refresh
+    def _put(self, endpoint: str, data: dict[Any, Any]) -> httpx.Response:
+        """Low-level PUT request; returns :class:`httpx.Response`.
+
+        The ``data`` is JSON-encoded into the request body.
+        """
+
+        return self._session.put(endpoint, json=data)
+
+    def get(self, endpoint: str, params: httpx.QueryParams | None = None) -> Any:
+        """High-level GET that returns parsed JSON from the response.
+
+        This calls the decorated ``_get`` helper and returns its JSON body.
+        """
+
+        return self._get(endpoint, params).json()
+
+    def post(self, endpoint: str, data: dict[Any, Any]) -> Any:
+        """High-level POST that returns parsed JSON from the response.
+
+        The ``data`` dict is JSON-encoded for the request body.
+        """
+
+        return self._post(endpoint, data).json()
+
+    def __repr__(self) -> str:
+        """Return a short representation including username and hive_url.
+
+        The representation intentionally omits secrets.
+        """
+
+        return f"HiveClient({self.username!r}, input(), {self.hive_url!r})"

pyhive/src/types/assignment.py

@@ -0,0 +1,210 @@
+"""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, Generator
+
+from attrs import define, field
+from dateutil.parser import isoparse
+from .common import UNSET, Unset
+from .core_item import HiveCoreItem
+from .enums.assignment_status_enum import AssignmentStatusEnum
+from .notification_nested import NotificationNested
+
+if TYPE_CHECKING:
+    from ...client import HiveClient
+    from .exercise import Exercise
+    from .user import User
+    from .assignment_response import AssignmentResponse
+
+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
+        )
+
+    def __lt__(self, value: object) -> bool:
+        if not isinstance(value, Assignment):
+            return NotImplemented
+        return self.user.number < value.user.number
+
+    def get_responses(self) -> Generator["AssignmentResponse", None, None]:
+        """Fetch all responses to this assignment.
+        Responses include both student and mentor submissions, comments, WIP, ..."""
+        return self.hive_client.get_assignment_responses(assignment=self.id)
+
+    def __iter__(self) -> Generator["Assignment", None, None]:
+        """Allow iteration over this Assignment to yield its responses."""
+        yield from self.get_responses()
+
+
+AssignmentLike = TypeVar("AssignmentLike", Assignment, int)

pyhive/src/types/assignment_response.py

@@ -0,0 +1,205 @@
+"""Responses to assignments given to students."""
+
+import datetime
+from typing import TYPE_CHECKING, Any, TypeVar, Union, Generator
+from attrs import define, field
+from dateutil.parser import isoparse
+
+from .core_item import HiveCoreItem
+from .autocheck_status import AutoCheckStatus
+from .assignment import Assignment
+from .enums.assignment_response_type_enum import AssignmentResponseTypeEnum
+from .common import UNSET, Unset
+
+if TYPE_CHECKING:
+    from .user import User
+    from .assignment_response_content import AssignmentResponseContent
+    from ...client import HiveClient
+
+
+T = TypeVar("T", bound="AssignmentResponse")
+
+
+@define
+class AssignmentResponse(HiveCoreItem):
+    """
+    Attributes:
+        id (int):
+        user_id (int):
+        contents (list['AssignmentResponseContent']):
+        date (datetime.datetime):
+        response_type (AssignmentResponseTypeEnum):
+            * `Comment` - Comment
+            * `Work In Progress` - Workinprogress
+            * `Submission` - Submission
+            * `AutoCheck` - Autocheck
+            * `Redo` - Redo
+            * `Done` - Done
+        autocheck_statuses (Union[None, list['Status']]):
+        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"
+    assignment_id: int
+    id: int
+    user_id: int
+    contents: list["AssignmentResponseContent"]
+    date: datetime.datetime
+    response_type: AssignmentResponseTypeEnum
+    autocheck_statuses: Union[None, list["AutoCheckStatus"]]
+    file_name: Union[Unset, str] = UNSET
+    dear_student: Union[Unset, bool] = True
+    hide_checker_name: Union[Unset, bool] = UNSET
+    segel_only: Union[Unset, bool] = UNSET
+
+    # Lazy-loaded objects
+    _user: "User | None" = field(init=False, default=None)
+    _assignment: "Assignment | None" = field(init=False, default=None)
+
+    def to_dict(self) -> dict[str, Any]:
+        contents = []
+        for contents_item_data in self.contents:
+            contents_item = contents_item_data.to_dict()
+            contents.append(contents_item)
+
+        autocheck_statuses: Union[None, list[dict[str, Any]]]
+        if isinstance(self.autocheck_statuses, list):
+            autocheck_statuses = []
+            for autocheck_statuses_type_0_item_data in self.autocheck_statuses:
+                autocheck_statuses_type_0_item = (
+                    autocheck_statuses_type_0_item_data.to_dict()
+                )
+                autocheck_statuses.append(autocheck_statuses_type_0_item)
+
+        else:
+            autocheck_statuses = self.autocheck_statuses
+
+        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": self.id,
+                "user": self.user,
+                "contents": contents,
+                "date": self.date.isoformat(),
+                "response_type": self.response_type.value,
+                "autocheck_statuses": autocheck_statuses,
+            }
+        )
+        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(  # pylint: disable=too-many-locals, arguments-differ
+        cls: type[T],
+        src_dict: dict[str, Any],
+        assignment_id: int,
+        hive_client: "HiveClient",
+    ) -> T:
+        from .assignment_response_content import (
+            AssignmentResponseContent,
+        )  # pylint: disable=import-outside-toplevel
+
+        d = dict(src_dict)
+        id = d.pop("id")
+
+        user_id = d.pop("user")
+
+        contents = []
+        _contents = d.pop("contents")
+        if not isinstance(_contents, list):
+            raise TypeError(
+                f"Assignment response contents must be a list, not {type(_contents)}"
+            )
+        for contents_item_data in _contents:
+            contents_item = AssignmentResponseContent.from_dict(
+                contents_item_data,
+                assignment=assignment_id,
+                assignment_response_id=id,
+                hive_client=hive_client,
+            )
+            contents.append(contents_item)
+        date = isoparse(d.pop("date"))
+        response_type = AssignmentResponseTypeEnum(d.pop("response_type"))
+
+        def _parse_autocheck_statuses(
+            data: object,
+        ) -> Union[None, list["AutoCheckStatus"]]:
+            if data is None:
+                return data
+            if not isinstance(data, list):
+                raise TypeError(f"Autocheck statuses must be a list, not {type(data)}")
+            autocheck_statuses_type_0 = []
+            _autocheck_statuses_type_0 = data
+            for autocheck_statuses_type_0_item_data in _autocheck_statuses_type_0:
+                autocheck_statuses_type_0_item = AutoCheckStatus.from_dict(
+                    autocheck_statuses_type_0_item_data,
+                    hive_client=hive_client,
+                )
+
+                autocheck_statuses_type_0.append(autocheck_statuses_type_0_item)
+
+            return autocheck_statuses_type_0
+
+        autocheck_statuses = _parse_autocheck_statuses(d.pop("autocheck_statuses"))
+
+        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(
+            hive_client=hive_client,
+            assignment_id=assignment_id,
+            id=id,
+            user_id=user_id,
+            contents=contents,
+            date=date,
+            response_type=response_type,
+            autocheck_statuses=autocheck_statuses,
+            file_name=file_name,
+            dear_student=dear_student,
+            hide_checker_name=hide_checker_name,
+            segel_only=segel_only,
+        )
+
+    @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 assignment(self) -> "Assignment":
+        """Lazily load and return the assignment this response belongs to."""
+        if self._assignment is None:
+            self._assignment = self.hive_client.get_assignment(
+                assignment_id=self.assignment_id
+            )
+        return self._assignment
+
+    def __iter__(self) -> Generator["AssignmentResponseContent", None, None]:
+        """Allow iteration over this AssignmentResponse to yield its contents."""
+        yield from self.contents