PyHiveLMS 1.0.2__py3-none-any.whl

pyhive/__init__.py

@@ -0,0 +1,13 @@
+"""Public package for the pyhive distribution.
+
+Expose the public convenience symbol `HiveClient` at package level so users
+can do `from pyhive import HiveClient`.
+"""
+
+from __future__ import annotations
+
+# Import the implementation from the `pyhive` package (implementation
+# lives there) and expose the client at package level.
+from pyhive.client import HiveClient  # re-export
+
+__all__ = ["HiveClient"]

pyhive/cli/main.py

@@ -0,0 +1,31 @@
+"""PyHive CLI entry point"""
+
+import typer
+
+from pyhive.src._generated_versions import SUPPORTED_API_VERSIONS
+
+app = typer.Typer(help="PyHive CLI")
+
+
+@app.command()
+def versions():
+    """Show supported Hive versions"""
+    print("Supported Hive Versions:")
+    for v in SUPPORTED_API_VERSIONS:
+        print(v)
+
+
+@app.command()
+def versions2():
+    """Show supported API versions"""
+    for v in SUPPORTED_API_VERSIONS:
+        print(v)
+
+
+def main():
+    """PyHive CLI main entry point"""
+    app()
+
+
+if __name__ == "__main__":
+    main()

pyhive/client/__init__.py

@@ -0,0 +1,112 @@
+"""High-level Hive API client aggregator."""
+
+from types import TracebackType
+from typing import TYPE_CHECKING, Optional, Union
+
+from ..src.api_versions import (LATEST_API_VERSION, MIN_API_VERSION,
+                                SUPPORTED_API_VERSIONS)
+from .assignment_responses import AssignmentResponsesClientMixin
+from .assignments import AssignmentClientMixin
+from .classes import ClassesClientMixin
+from .exercises import ExerciseClientMixin
+from .fields import FieldsClientMixin
+from .help import HelpClientMixin
+from .modules import ModuleClientMixin
+from .programs import ProgramClientMixin
+from .queues import QueuesClientMixin
+from .subjects import SubjectClientMixin
+from .users import UserClientMixin
+from .version import VersionClientMixin
+
+if TYPE_CHECKING:
+    from httpx import Timeout
+    from httpx._types import ProxyTypes
+
+
+class HiveClient(  # pylint: disable=too-many-ancestors,abstract-method
+    ProgramClientMixin,
+    SubjectClientMixin,
+    ModuleClientMixin,
+    ExerciseClientMixin,
+    AssignmentClientMixin,
+    UserClientMixin,
+    ClassesClientMixin,
+    FieldsClientMixin,
+    AssignmentResponsesClientMixin,
+    QueuesClientMixin,
+    HelpClientMixin,
+    VersionClientMixin,
+):
+    """Aggregated HTTP client for accessing Hive API resources."""
+
+    def __init__(
+        self,
+        *args,
+        skip_version_check: bool = False,
+        timeout: Optional[Union["Timeout", float]] = None,
+        headers: Optional[dict[str, str]] = None,
+        verify: Optional[Union[bool, str]] = None,
+        proxy: Optional["ProxyTypes"] = None,
+        **kwargs,
+    ):
+        super().__init__(
+            *args,
+            timeout=timeout,
+            headers=headers,
+            verify=verify,
+            proxy=proxy,
+            **kwargs,
+        )
+        if not skip_version_check:
+            self._api_version_check()
+
+    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})"
+
+    def __enter__(self) -> "HiveClient":
+        """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,
+    ) -> 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 _api_version_check(self) -> None:
+        """Validate that the Hive server API version is supported.
+
+        Fetches the server version via ``get_hive_version`` and verifies it is present
+        in ``SUPPORTED_API_VERSIONS``. If unsupported, raises a RuntimeError with
+        guidance to align the client and server versions.
+
+        Raises:
+            RuntimeError: If the server API version is not supported by this client.
+        """
+        version_str = self.get_hive_version()
+        if version_str not in SUPPORTED_API_VERSIONS:
+            supported_range = f"{MIN_API_VERSION} .. {LATEST_API_VERSION}"
+            raise RuntimeError(
+                (
+                    f"Unsupported Hive API version '{version_str}'. Supported versions: {supported_range}. "
+                    f"Please upgrade/downgrade the server or use a compatible client."
+                )
+            )

pyhive/client/assignment_responses.py

@@ -0,0 +1,45 @@
+"""
+Assignment Response resource mixin for HiveClient.
+
+Provides methods for listing and retrieving AssignmentResponse records for a given assignment
+through the Hive API. Intended only for use as a mixin on HiveClient.
+"""
+
+from ..src.types.assignment_response import AssignmentResponse
+from .client_shared import ClientCoreMixin
+from .utils import resolve_item_or_id
+
+
+class AssignmentResponsesClientMixin(ClientCoreMixin):
+    """
+    Mixin class providing assignment response API methods to HiveClient.
+
+    Methods
+    -------
+    get_assignment_responses(assignment)
+        List all assignment responses for a single assignment.
+    get_assignment_response(assignment, response_id)
+        Retrieve one assignment response by id for a given assignment.
+    """
+
+    def get_assignment_responses(self, assignment):
+        """Yield assignment responses for the provided ``assignment`` (id or instance)."""
+        assignment_id = resolve_item_or_id(assignment)
+        return self._get_core_items(
+            f"/api/core/assignments/{assignment_id}/responses/",
+            AssignmentResponse,
+            assignment_id=assignment_id,
+        )
+
+    def get_assignment_response(self, assignment, response_id: int):
+        """Return a single response by ``response_id`` for the given ``assignment``."""
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+
+        assignment_id = resolve_item_or_id(assignment)
+        return AssignmentResponse.from_dict(
+            self.get(f"/api/core/assignments/{assignment_id}/responses/{response_id}/"),
+            assignment_id=assignment_id,
+            hive_client=self,
+        )

pyhive/client/assignments.py

@@ -0,0 +1,115 @@
+"""
+Assignment resource mixin for HiveClient.
+
+Adds methods for listing and retrieving Assignment records via the Hive API. Meant only
+for use as a mixin on HiveClient.
+"""
+
+from typing import TYPE_CHECKING, Iterable, Optional, Sequence
+
+from ..src.types.assignment import Assignment
+from .client_shared import ClientCoreMixin
+from .utils import assert_mutually_exclusive_filters, resolve_item_or_id
+
+if TYPE_CHECKING:
+    from ..src.types.module import ModuleLike
+    from ..src.types.subject import SubjectLike
+    from ..src.types.user import UserLike
+
+
+class AssignmentClientMixin(ClientCoreMixin):
+    """
+    Mixin class providing assignment-related API methods to HiveClient.
+
+    Methods
+    -------
+    get_assignments(...various filters...)
+        List all or filtered assignments, supporting complex relational filters.
+    get_assignment(assignment_id)
+        Retrieve a single assignment by its id.
+    """
+
+    def get_assignments(  # pylint: disable=too-many-arguments,too-many-locals
+        self,
+        *,
+        exercise__id: Optional[int] = None,
+        exercise__parent_module__id: Optional[int] = None,
+        exercise__parent_module__parent_subject__id: Optional[int] = None,
+        exercise__tags__id__in: Optional[Sequence[int]] = None,
+        queue__id: Optional[int] = None,
+        user__classes__id: Optional[int] = None,
+        user__classes__id__in: Optional[Sequence[int]] = None,
+        user__id__in: Optional[Sequence[int]] = None,
+        user__mentor__id: Optional[int] = None,
+        user__mentor__id__in: Optional[Sequence[int]] = None,
+        user__program__id__in: Optional[Sequence[int]] = None,
+        # Non built-in filters
+        parent_module: Optional["ModuleLike"] = None,
+        parent_subject: Optional["SubjectLike"] = None,
+        for_user: Optional["UserLike"] = None,
+        for_mentees_of: Optional["UserLike"] = None,
+    ) -> Iterable[Assignment]:
+        """Yield ``Assignment`` objects filtered by the provided criteria."""
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+
+        if parent_module is not None and exercise__parent_module__id is not None:
+            assert exercise__parent_module__id == resolve_item_or_id(parent_module)
+        exercise__parent_module__id = (
+            exercise__parent_module__id
+            if exercise__parent_module__id is not None
+            else resolve_item_or_id(parent_module)
+        )
+        if (
+            parent_subject is not None
+            and exercise__parent_module__parent_subject__id is not None
+        ):
+            assert exercise__parent_module__parent_subject__id == resolve_item_or_id(
+                parent_subject
+            )
+        exercise__parent_module__parent_subject__id = (
+            exercise__parent_module__parent_subject__id
+            if exercise__parent_module__parent_subject__id is not None
+            else resolve_item_or_id(parent_subject)
+        )
+
+        assert_mutually_exclusive_filters(user__classes__id, user__classes__id__in)
+
+        assert (not (user__id__in is not None and for_user is not None)) or (
+            len(user__id__in) == 1 and user__id__in[0] == resolve_item_or_id(for_user)
+        ), "Filters user__id__in and for_user conflict!"
+        if for_user is not None:
+            user__id__in = [resolve_item_or_id(for_user)]
+
+        assert_mutually_exclusive_filters(
+            user__mentor__id, user__mentor__id__in, for_mentees_of
+        )
+        if for_mentees_of is not None:
+            user__mentor__id = resolve_item_or_id(for_mentees_of)
+
+        return self._get_core_items(
+            "/api/core/assignments/",
+            Assignment,
+            exercise__id=exercise__id,
+            exercise__parent_module__id=exercise__parent_module__id,
+            exercise__parent_module__parent_subject__id=exercise__parent_module__parent_subject__id,
+            exercise__tags__id__in=exercise__tags__id__in,
+            queue__id=queue__id,
+            user__classes__id=user__classes__id,
+            user__classes__id__in=user__classes__id__in,
+            user__id__in=user__id__in,
+            user__mentor__id=user__mentor__id,
+            user__mentor__id__in=user__mentor__id__in,
+            user__program__id__in=user__program__id__in,
+        )
+
+    def get_assignment(self, assignment_id: int) -> Assignment:
+        """Return a single ``Assignment`` by its id."""
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+        return Assignment.from_dict(
+            self.get(f"/api/core/assignments/{assignment_id}/"),
+            hive_client=self,
+        )

pyhive/client/classes.py

@@ -0,0 +1,108 @@
+"""
+Class resource mixin for HiveClient.
+
+Provides listing and retrieval of Class records from the Hive API. Use only as a mixin for the main HiveClient.
+"""
+
+from typing import TYPE_CHECKING, Iterable, Optional
+
+from ..src.types.class_ import Class, ClassLike
+from ..src.types.enums.class_type_enum import ClassTypeEnum
+from .client_shared import ClientCoreMixin
+from .utils import resolve_item_or_id
+
+if TYPE_CHECKING:
+    from ..src.types.program import ProgramLike
+    from ..src.types.user import UserLike
+
+
+class ClassesClientMixin(ClientCoreMixin):
+    """
+    Mixin class providing class-related API methods for HiveClient.
+
+    Methods
+    -------
+    get_classes(id__in=None, name=None, program__id__in=None, type_=None, ...)
+        List all or filtered classes via the Hive API. Supports multiple relationship filters.
+    get_class(class_id)
+        Retrieve a single class by id.
+    """
+
+    def get_classes(
+        self,
+        *,
+        id__in: Optional[list[int]] = None,
+        name: Optional[str] = None,
+        program__id__in: Optional[list[int]] = None,
+        type_: Optional[ClassTypeEnum] = None,
+    ) -> Iterable[Class]:
+        """Yield ``Class`` objects filtered by the provided criteria."""
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+        return self._get_core_items(
+            "/api/core/management/classes/",
+            Class,
+            id__in=id__in,
+            name=name,
+            program__id__in=program__id__in,
+            type_=type_,
+        )
+
+    def get_class(
+        self,
+        class_id: int,
+    ) -> Class:
+        """Return a single ``Class`` by its id."""
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+        return Class.from_dict(
+            self.get(f"/api/core/management/classes/{class_id}/"),
+            hive_client=self,
+        )
+
+    def create_class(
+        self,
+        name: str,
+        *,
+        program: "ProgramLike",
+        users: Optional[list["UserLike"]] = None,
+        email: Optional[str] = None,
+        type_: Optional[ClassTypeEnum] = None,
+        classes: Optional[list["ClassLike"]] = None,
+        description: Optional[str] = None,
+    ) -> Class:
+        """
+        Create a Class via the Hive API.
+        """
+
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+
+        payload: dict[str, object] = {
+            "name": name,
+            "program": resolve_item_or_id(program),
+        }
+
+        # Users list - include always, default to empty list like create_user does for mentees
+        if users is None:
+            users = []
+        payload["users"] = [resolve_item_or_id(u) for u in users]
+
+        # Optional fields
+        if email is not None:
+            payload["email"] = email
+        if type_ is not None:
+            payload["type"] = type_.value
+        if classes is not None:
+            payload["classes"] = [resolve_item_or_id(c) for c in classes]
+        if description is not None:
+            payload["description"] = description
+
+        response = self.post("/api/core/management/classes/", payload)
+        return Class.from_dict(response, hive_client=self)
+
+    def delete_class(self, class_: "ClassLike") -> None:
+        self.delete(f"/api/core/management/classes/{resolve_item_or_id(class_)}/")

pyhive/client/client_shared.py

@@ -0,0 +1,75 @@
+"""Shared client utilities and common mixin base for Hive API access.
+
+- ``ClientCoreMixin``: base class that provides ``_get_core_items`` used by resource mixins.
+"""
+
+from typing import Any, Generator, Iterable, Optional
+
+import httpx
+
+from ..src.authenticated_hive_client import AuthenticatedHiveClient
+from .utils import CoreItemTypeT
+
+
+class ClientCoreMixin(AuthenticatedHiveClient):
+    """Common mixin base that exposes ``_get_core_items`` for list endpoints.
+
+    This relies on the authenticated transport provided by the base client and is designed to be used only on
+    the composed ``HiveClient``.
+    """
+
+    def _get_core_items(
+        self,
+        endpoint: str,
+        item_type: type[CoreItemTypeT],
+        /,
+        extra_ctor_params: Optional[dict[str, Any]] = None,
+        **kwargs,
+    ) -> Iterable[CoreItemTypeT]:
+        """Yield typed items from a list endpoint with optional query parameters.
+
+        Handles both non-paginated list responses and DRF-style paginated
+        responses of the form:
+
+            {"count": N, "next": url | null, "previous": url | null, "results": [...]}
+        """
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+
+        if extra_ctor_params is None:
+            extra_ctor_params = {}
+
+        # Build query params, converting lists to comma-separated values
+        query_params = httpx.QueryParams()
+        for name, value in kwargs.items():
+            if value is None:
+                continue
+            if isinstance(value, list):
+                query_params = query_params.set(name, ",".join(str(x) for x in value))
+            else:
+                query_params = query_params.set(name, value)
+
+        data = self.get(endpoint, params=query_params)
+
+        # Non-paginated: assume the payload is the items list (or empty)
+        if not (isinstance(data, dict) and "results" in data):
+            items: list = data if isinstance(data, list) else []
+            yield from (
+                item_type.from_dict(x, **extra_ctor_params, hive_client=self)
+                for x in items
+            )
+
+        # Paginated: follow "next" links and yield all pages
+        def _paginate() -> Iterable[CoreItemTypeT]:
+            page = data
+            while True:
+                items = page.get("results", [])
+                for x in items:
+                    yield item_type.from_dict(x, **extra_ctor_params, hive_client=self)
+                next_url = page.get("next")
+                if not next_url:
+                    break
+                page = self.get(next_url)
+
+        return _paginate()

pyhive/client/exercises.py

@@ -0,0 +1,82 @@
+"""
+Exercise resource mixin for HiveClient.
+
+Provides listing and retrieval of Exercise records, with rich filtering, via the Hive API.
+Intended for mixing into the main HiveClient only.
+"""
+
+from typing import TYPE_CHECKING, Iterable, Optional
+
+from ..src.types.exercise import Exercise
+from .client_shared import ClientCoreMixin
+from .utils import resolve_item_or_id
+
+if TYPE_CHECKING:
+    from ..src.types.module import ModuleLike
+    from ..src.types.subject import SubjectLike
+
+class ExerciseClientMixin(ClientCoreMixin):
+    """
+    Mixin class providing exercise-related API methods for HiveClient.
+
+    Methods
+    -------
+    get_exercises(parent_module__id=None, parent_module=None, parent_subject=None, exercise_name=None, ...)
+        List all or filtered exercises via the Hive API. Supports advanced hierarchical filtering.
+    get_exercise(exercise_id)
+        Retrieve a single exercise by id.
+    """
+
+    # NOTE: Intended to be used only as part of the HiveClient composite class
+    def get_exercises(  # pylint: disable=too-many-arguments
+        self,
+        *,
+        parent_module__id: Optional[int] = None,
+        parent_module__parent_subject__id: Optional[int] = None,
+        parent_module__parent_subject__parent_program__id__in: Optional[list[int]] = None,
+        queue__id: Optional[int] = None,
+        tags__id__in: Optional[list[int]] = None,
+        parent_module: Optional["ModuleLike"] = None,
+        parent_subject: Optional["SubjectLike"] = None,
+        exercise_name: Optional[str] = None,
+    ) -> Iterable[Exercise]:
+        """Yield ``Exercise`` objects, supporting rich parent-based filtering."""
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+        if parent_module is not None and parent_module__id is not None:
+            assert parent_module__id == resolve_item_or_id(parent_module)
+        parent_module__id = (
+            parent_module__id
+            if parent_module__id is not None
+            else resolve_item_or_id(parent_module)
+        )
+        if parent_subject is not None and parent_module__parent_subject__id is not None:
+            assert parent_module__parent_subject__id == resolve_item_or_id(parent_subject)
+        parent_module__parent_subject__id = (
+            parent_module__parent_subject__id
+            if parent_module__parent_subject__id is not None
+            else resolve_item_or_id(parent_subject)
+        )
+        exercises: Iterable[Exercise] = self._get_core_items(
+            "/api/core/course/exercises/",
+            Exercise,
+            parent_module__id=parent_module__id,
+            parent_module__parent_subject__id=parent_module__parent_subject__id,
+            parent_module__parent_subject__parent_program__id__in=parent_module__parent_subject__parent_program__id__in,
+            queue__id=queue__id,
+            tags__id__in=tags__id__in,
+        )
+        if exercise_name is not None:
+            exercises = filter(lambda e: e.name == exercise_name, exercises)
+        return exercises
+
+    def get_exercise(self, exercise_id: int) -> Exercise:
+        """Return a single ``Exercise`` by its id."""
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+        return Exercise.from_dict(
+            self.get(f"/api/core/course/exercises/{exercise_id}/"),
+            hive_client=self,
+        )

pyhive/client/fields.py

@@ -0,0 +1,41 @@
+"""Exercise form fields mixin for HiveClient.
+
+Provides methods to list and retrieve form fields for a specific exercise.
+"""
+
+from typing import Generator
+
+from ..src.types.form_field import FormField
+from .client_shared import ClientCoreMixin
+from .utils import resolve_item_or_id
+
+
+class FieldsClientMixin(ClientCoreMixin):
+    """Mixin that exposes form-field endpoints for exercises."""
+
+    def get_exercise_fields(
+        self,
+        exercise,
+    ) -> Generator[FormField, None, None]:
+        """Yield all form fields for the given ``exercise`` (id or instance)."""
+        exercise_id = resolve_item_or_id(exercise)
+        return self._get_core_items(
+            f"/api/core/course/exercises/{exercise_id}/fields/",
+            FormField,
+            exercise_id=exercise_id,
+        )
+
+    def get_exercise_field(
+        self,
+        exercise,
+        field_id: int,
+    ) -> FormField:
+        """Return a single form field for ``exercise`` by ``field_id``."""
+        from ..client import HiveClient
+
+        assert isinstance(self, HiveClient), "self must be an instance of HiveClient"
+        exercise_id = resolve_item_or_id(exercise)
+        return FormField.from_dict(
+            self.get(f"/api/core/course/exercises/{exercise_id}/fields/{field_id}/"),
+            hive_client=self,
+        )