PyBlackboard-LMS 0.1.0__py3-none-any.whl

blackboard_api/__init__.py

@@ -0,0 +1,27 @@
+import logging
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+from .client import BlackboardAPI
+from .identifiers import InvalidIdentifierError
+from .errors import (
+    BlackboardAPIError,
+    AuthenticationError,
+    NotFoundError,
+    QuotaExhaustedError,
+    WriteNotEnabledError,
+    ResponseFormatError,
+    TransportError,
+)
+
+__all__ = [
+    "BlackboardAPI",
+    "BlackboardAPIError",
+    "AuthenticationError",
+    "NotFoundError",
+    "QuotaExhaustedError",
+    "WriteNotEnabledError",
+    "ResponseFormatError",
+    "TransportError",
+    "InvalidIdentifierError",
+]

blackboard_api/api_quota.py

@@ -0,0 +1,59 @@
+import logging
+from dataclasses import dataclass
+from typing import Optional
+import requests
+
+from .errors import QuotaExhaustedError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ApiQuotaState:
+    max_requests_per_day: Optional[int] = None
+    remaining: Optional[int] = None
+    retry_after: Optional[int] = None
+
+    def update_from_response(self, response: requests.Response) -> None:
+        quota_limit = response.headers.get("X-Rate-Limit-Limit")
+        remaining = response.headers.get("X-Rate-Limit-Remaining")
+        retry_after = response.headers.get("Retry-After")
+        if remaining is None and (
+            self.max_requests_per_day is not None or self.remaining is not None
+        ):
+            logger.warning(
+                "Blackboard did not send the remaining-requests header; "
+                "preserving the last known value."
+            )
+        parsed_limit = _parse_int(quota_limit)
+        parsed_remaining = _parse_int(remaining)
+        parsed_retry_after = _parse_int(retry_after)
+        if quota_limit is not None and parsed_limit is None:
+            logger.warning(
+                "Invalid X-Rate-Limit-Limit header; preserving the prior value."
+            )
+        if remaining is not None and parsed_remaining is None:
+            logger.warning(
+                "Invalid X-Rate-Limit-Remaining header; preserving the prior "
+                "value."
+            )
+        if retry_after is not None and parsed_retry_after is None:
+            logger.warning(
+                "Invalid Retry-After header; preserving the prior value."
+            )
+        if parsed_limit is not None:
+            self.max_requests_per_day = parsed_limit
+        if parsed_remaining is not None:
+            self.remaining = parsed_remaining
+        if parsed_retry_after is not None:
+            self.retry_after = parsed_retry_after
+        if self.remaining == 0:
+            logger.error("Blackboard reported zero remaining API requests")
+            raise QuotaExhaustedError("Blackboard API quota is exhausted")
+
+
+def _parse_int(value: str | None) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None

blackboard_api/auth.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any
+import logging
+
+import requests
+
+from .errors import AuthenticationError, TransportError
+
+logger = logging.getLogger(__name__)
+
+
+class AuthService:
+    def __init__(
+        self, base_url: str, client_id: str, client_secret: str, transport: Any
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._transport = transport
+        self.token = None
+        self.token_expires_at = 0
+
+    def is_token_expired(self, now: float) -> bool:
+        return self.token is None or now >= self.token_expires_at
+
+    def request_access_token(self) -> dict[str, Any]:
+        logger.debug("Requesting OAuth token from Blackboard")
+        try:
+            response = self._transport.request(
+                "POST",
+                f"{self.base_url}/learn/api/public/v1/oauth2/token",
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                data={"grant_type": "client_credentials"},
+                auth=(self.client_id, self.client_secret),
+                track_api_quota=False,
+            )
+        except TransportError as exc:
+            logger.warning("Could not reach the authentication endpoint")
+            raise AuthenticationError(
+                "Could not reach the authentication endpoint"
+            ) from exc
+        try:
+            response.raise_for_status()
+            data = response.json()
+        except requests.exceptions.HTTPError as exc:
+            logger.warning("Blackboard rejected OAuth authentication")
+            raise AuthenticationError(
+                "Blackboard rejected authentication credentials"
+            ) from exc
+        except ValueError as exc:
+            logger.warning("Blackboard returned invalid JSON during authentication")
+            raise AuthenticationError("Authentication JSON response is invalid") from exc
+        if not isinstance(data, dict) or not data.get("access_token"):
+            logger.warning("OAuth response does not contain a valid access_token")
+            raise AuthenticationError(
+                "Authentication response does not contain access_token"
+            )
+        return data
+
+    def authenticate(self, now: float) -> str:
+        if not self.is_token_expired(now):
+            logger.debug("Reusing valid OAuth token")
+            return self.token
+        data = self.request_access_token()
+        self.token = data["access_token"]
+        try:
+            expires_in = max(1, int(data.get("expires_in", 3600)))
+        except (TypeError, ValueError) as exc:
+            raise AuthenticationError(
+                "Authentication response contains invalid expires_in"
+            ) from exc
+        # Prevent very short-lived tokens from expiring immediately.
+        skew = min(60, max(0, expires_in // 10))
+        self.token_expires_at = now + expires_in - skew
+        logger.debug("OAuth token obtained; expiry uses a safety margin")
+        return self.token

blackboard_api/client.py

@@ -0,0 +1,228 @@
+import time
+import logging
+from urllib.parse import parse_qsl, urlencode, urljoin, urlparse, urlunparse
+
+import requests
+from typing import Any
+
+from .auth import AuthService
+from .config import api_config_from_environment
+from .errors import (
+    NotFoundError,
+    QuotaExhaustedError,
+    WriteNotEnabledError,
+    ResponseFormatError,
+)
+from .api_quota import ApiQuotaState
+from .transport import Transport
+from .resources.courses import CourseResource
+from .resources.users import UserResource
+from .resources.enrollments import EnrollmentResource
+from .resources.nodes import NodeResource
+from .resources.enrollment_roles import EnrollmentRoleResource
+from .resources.terms import TermResource
+from .services.enrollments import EnrollmentService
+from .services.users import UserService
+from .services.courses import CourseService, TermService
+from .facades.resources import NodeFacade, EnrollmentRoleFacade
+from .facades.enrollments import EnrollmentFacade
+from .facades.users import UserFacade
+from .facades.courses import CourseFacade
+from .facades.terms import TermFacade
+from .facades.api_quota import ApiQuotaFacade
+
+logger = logging.getLogger(__name__)
+
+
+class BlackboardAPI:
+    def __init__(
+        self, url: str | None = None, client_id: str | None = None,
+        client_secret: str | None = None,
+        env_file: str | None = None,
+        enable_write: bool = False,
+        max_retries: int | None = None,
+        results_per_page: int = 100,
+    ) -> None:
+        if url is None and client_id is None and client_secret is None:
+            if env_file is None:
+                raise ValueError(
+                    "env_file is required when credentials are not provided"
+                )
+            config = api_config_from_environment(env_file)
+            url = config["url"]
+            client_id = config["client_id"]
+            client_secret = config["client_secret"]
+            timeout = (config["connect_timeout"], config["read_timeout"])
+        elif not all((url, client_id, client_secret)):
+            raise ValueError("Provide all three credentials or none")
+        else:
+            timeout = (10, 60)
+        parsed = urlparse(url)
+        if parsed.scheme != "https" or not parsed.netloc:
+            raise ValueError("BB_INSTANCE_URL must be a valid HTTPS URL")
+        self._url = url.rstrip("/")
+        self.enable_write = enable_write
+        if not isinstance(self.enable_write, bool):
+            raise TypeError("enable_write must be a boolean")
+        self.results_per_page = results_per_page
+        self._api_quota = ApiQuotaState()
+        self._transport = Transport(
+            self._api_quota,
+            timeout=timeout,
+            max_retries=(3 if max_retries is None else max_retries),
+        )
+        self._auth = AuthService(
+            self._url, client_id, client_secret, self._transport
+        )
+        self._courses_resource = CourseResource(self)
+        self._users_resource = UserResource(self)
+        self._enrollments_resource = EnrollmentResource(self)
+        self._nodes_resource = NodeResource(self)
+        self._enrollment_roles_resource = EnrollmentRoleResource(self)
+        self._terms_resource = TermResource(self)
+        self._enrollment_service = EnrollmentService(
+            self._enrollments_resource, self._enrollment_roles_resource
+        )
+        self._user_service = UserService(self._users_resource)
+        self._course_service = CourseService(
+            self._courses_resource, self._terms_resource
+        )
+        self._term_service = TermService(
+            self._courses_resource, self._terms_resource
+        )
+        self.courses = CourseFacade(self._courses_resource, self._course_service)
+        self.users = UserFacade(self._users_resource, self._user_service)
+        self.enrollments = EnrollmentFacade(
+            self._enrollments_resource, self._enrollment_service
+        )
+        self.nodes = NodeFacade(self._nodes_resource)
+        self.enrollment_roles = EnrollmentRoleFacade(self._enrollment_roles_resource)
+        self.terms = TermFacade(self._terms_resource, self._term_service)
+        self.api_quota = ApiQuotaFacade(
+            self._get_api_quota,
+        )
+
+    @property
+    def token(self) -> str | None:
+        return self._auth.token
+
+    @property
+    def api_quota_remaining(self) -> int | None:
+        return self._api_quota.remaining
+
+    @property
+    def max_requests_per_day(self) -> int | None:
+        return self._api_quota.max_requests_per_day
+
+    @property
+    def results_per_page(self) -> int:
+        """Return the default number of results requested per collection page."""
+        return self._results_per_page
+
+    @results_per_page.setter
+    def results_per_page(self, value: int) -> None:
+        """Set the default collection result count for future requests."""
+        if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+            raise ValueError("results_per_page must be a positive integer")
+        self._results_per_page = value
+
+    def _ensure_api_quota(self) -> None:
+        """Probe Blackboard once when no quota headers are known yet."""
+        if (
+            self._api_quota.max_requests_per_day is None
+            and self._api_quota.remaining is None
+        ):
+            self._update_api_quota()
+
+    def _get_api_quota(self) -> dict[str, int | None]:
+        self._ensure_api_quota()
+        return {
+            "remaining": self.api_quota_remaining,
+            "max_requests_per_day": self.max_requests_per_day,
+        }
+
+    def _authenticate(self) -> None:
+        previous_token = self._auth.token
+        token = self._auth.authenticate(time.time())
+        if token != previous_token:
+            self._update_api_quota()
+
+    def _get_headers(self) -> dict[str, str]:
+        self._authenticate()
+        return {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    def _request(self, method: str, path_or_url: str, **kwargs: Any) -> requests.Response:
+        if not self.enable_write and method.upper() not in {"GET", "HEAD", "OPTIONS"}:
+            logger.warning("Writes are disabled; blocked %s", method.upper())
+            raise WriteNotEnabledError(
+                f"{method.upper()} requires enable_write=True"
+            )
+        url = (
+            path_or_url
+            if path_or_url.startswith("http")
+            else urljoin(self._url + "/", path_or_url.lstrip("/"))
+        )
+        headers = kwargs.pop("headers", None)
+        if headers is None:
+            headers = self._get_headers()
+        response = self._transport.request(method, url, headers=headers, **kwargs)
+        logger.debug("HTTP request completed: %s", method.upper())
+        try:
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as exc:
+            if response.status_code == 404:
+                raise NotFoundError(f"Resource not found: {url}") from exc
+            raise
+        return response
+
+    def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            return self._request(method, path, **kwargs).json()
+        except ValueError as exc:
+            raise ResponseFormatError(
+                f"Invalid JSON response for {method.upper()} {path}"
+            ) from exc
+
+    def _iter_paginated(self, path: str):
+        """Yield collection items one page at a time without accumulating them."""
+        url = BlackboardAPI._with_results_per_page(self, path)
+        while url:
+            data = self._request_json("GET", url)
+            if not isinstance(data, dict):
+                raise ResponseFormatError(
+                    "Blackboard collection is not a JSON object"
+                )
+            if "results" not in data:
+                raise ResponseFormatError("Collection does not contain results")
+            results = data["results"]
+            paging = data.get("paging", {})
+            if not isinstance(results, list):
+                raise ResponseFormatError("Collection results is not a list")
+            if not isinstance(paging, dict):
+                raise ResponseFormatError("Collection paging is not an object")
+            next_page = paging.get("nextPage")
+            if next_page is not None and not isinstance(next_page, str):
+                raise ResponseFormatError("Collection paging.nextPage is not text")
+            yield from results
+            url = next_page
+
+    def _with_results_per_page(self, path: str) -> str:
+        """Add the configured pagination limit without changing an explicit one."""
+        parsed = urlparse(path)
+        query = parse_qsl(parsed.query, keep_blank_values=True)
+        if not any(key == "limit" for key, _ in query):
+            query.append((
+                "limit",
+                str(getattr(self, "_results_per_page", 100)),
+            ))
+        return urlunparse(parsed._replace(query=urlencode(query)))
+
+    def _update_api_quota(self) -> dict[str, int | None]:
+        self._request("GET", "/learn/api/public/v1/users/me")
+        return {
+            "max_requests_per_day": self._api_quota.max_requests_per_day,
+            "remaining": self._api_quota.remaining,
+        }

blackboard_api/config.py

@@ -0,0 +1,55 @@
+import os
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONNECT_TIMEOUT_SECONDS = 10
+DEFAULT_READ_TIMEOUT_SECONDS = 60
+
+
+def load_environment(path: str | Path) -> dict[str, str]:
+    env_path = Path(path)
+    if not env_path.is_file():
+        raise FileNotFoundError(f"Environment file does not exist: {env_path}")
+    values = {}
+    for line_number, raw_line in enumerate(env_path.read_text(encoding="utf-8").splitlines(), 1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            raise ValueError(f"Invalid format in {env_path}, line {line_number}")
+        key, value = line.split("=", 1)
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] == value[-1] and value[0] in {"'", '"'}:
+            value = value[1:-1]
+        values[key.strip()] = value
+    return values
+
+
+def _positive_int(value: Any, name: str, default: int) -> int:
+    value = default if value in (None, "") else value
+    try:
+        value = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be a positive integer") from exc
+    if value <= 0:
+        raise ValueError(f"{name} must be a positive integer")
+    return value
+
+
+def api_config_from_environment(path: str | Path) -> dict[str, Any]:
+    values = load_environment(path)
+    required = {
+        "BB_INSTANCE_URL": values.get("BB_INSTANCE_URL"),
+        "APP_KEY": values.get("APP_KEY"),
+        "APP_SECRET": values.get("APP_SECRET"),
+    }
+    missing = [name for name, value in required.items() if not value]
+    if missing:
+        raise ValueError("Missing required environment variables: " + ", ".join(missing))
+    return {
+        "url": required["BB_INSTANCE_URL"],
+        "client_id": required["APP_KEY"],
+        "client_secret": required["APP_SECRET"],
+        "connect_timeout": _positive_int(values.get("BB_REQUEST_CONNECT_TIMEOUT") or os.environ.get("BB_REQUEST_CONNECT_TIMEOUT"), "connect timeout", DEFAULT_CONNECT_TIMEOUT_SECONDS),
+        "read_timeout": _positive_int(values.get("BB_REQUEST_READ_TIMEOUT") or os.environ.get("BB_REQUEST_READ_TIMEOUT"), "read timeout", DEFAULT_READ_TIMEOUT_SECONDS),
+    }

blackboard_api/errors.py

@@ -0,0 +1,26 @@
+class BlackboardAPIError(RuntimeError):
+    """Base exception for the Blackboard client."""
+
+
+class AuthenticationError(BlackboardAPIError):
+    pass
+
+
+class QuotaExhaustedError(BlackboardAPIError):
+    """The quota reported by Blackboard is exactly zero."""
+
+
+class TransportError(BlackboardAPIError):
+    pass
+
+
+class ResponseFormatError(BlackboardAPIError):
+    """The Blackboard response has an unexpected format."""
+
+
+class NotFoundError(BlackboardAPIError):
+    """Blackboard could not find the requested resource."""
+
+
+class WriteNotEnabledError(BlackboardAPIError):
+    """The operation is blocked because writes are not enabled."""

blackboard_api/facades/__init__.py

@@ -0,0 +1,19 @@
+"""Public facades grouped by resource."""
+
+from .resources import ResourceFacade, NodeFacade, EnrollmentRoleFacade
+from .enrollments import EnrollmentFacade
+from .users import UserFacade
+from .courses import CourseFacade
+from .terms import TermFacade
+from .api_quota import ApiQuotaFacade
+
+__all__ = [
+    "ResourceFacade",
+    "NodeFacade",
+    "EnrollmentRoleFacade",
+    "EnrollmentFacade",
+    "UserFacade",
+    "CourseFacade",
+    "TermFacade",
+    "ApiQuotaFacade",
+]

blackboard_api/facades/api_quota.py

@@ -0,0 +1,19 @@
+"""Public facade for the API usage quota."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+
+class ApiQuotaFacade:
+    """Expose API quota state separately from pagination settings."""
+
+    def __init__(
+        self,
+        get_state: Callable[[], dict[str, int | None]],
+    ) -> None:
+        self._get_state = get_state
+
+    def get(self) -> dict[str, int | None]:
+        """Return remaining requests and the daily request maximum."""
+        return self._get_state()

blackboard_api/facades/courses.py

@@ -0,0 +1,96 @@
+"""Public facade for atomic and composite course operations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from .resources import ResourceFacade
+
+
+class CourseFacade(ResourceFacade):
+    """Expose course resource operations and convenience services."""
+
+    def __init__(self, resource: Any, service: Any) -> None:
+        super().__init__(resource)
+        self._service = service
+
+    def list(self) -> list[dict]:
+        return self._resource.list()
+
+    def iter(self) -> Iterator[dict]:
+        return self._resource.iter()
+
+    def get(self, *, course_identifier: str) -> dict:
+        return self._resource.get(course_identifier=course_identifier)
+
+    def create(self, data: dict) -> dict:
+        """Create a course without Blackboard-generated ``id`` or UUID."""
+        return self._resource.create(data)
+
+    def update(self, *, course_identifier: str, data: dict) -> dict:
+        return self._resource.update(
+            course_identifier=course_identifier, data=data
+        )
+
+    def delete(self, *, course_identifier: str) -> None:
+        return self._resource.delete(course_identifier=course_identifier)
+
+    def set_available(self, *, course_identifier: str) -> dict:
+        return self._resource.set_available(course_identifier=course_identifier)
+
+    def set_unavailable(self, *, course_identifier: str) -> dict:
+        return self._resource.set_unavailable(course_identifier=course_identifier)
+
+    def set_disabled(self, *, course_identifier: str) -> dict:
+        return self._resource.set_disabled(course_identifier=course_identifier)
+
+    def assign_node(
+        self,
+        *,
+        course_identifier: str,
+        node_identifier: str,
+        primary: bool | None = None,
+    ) -> dict:
+        return self._resource.assign_node(
+            course_identifier=course_identifier,
+            node_identifier=node_identifier,
+            primary=primary,
+        )
+
+    def unassign_node(
+        self, *, course_identifier: str, node_identifier: str
+    ) -> None:
+        return self._resource.unassign_node(
+            course_identifier=course_identifier,
+            node_identifier=node_identifier,
+        )
+
+    def list_by_node(self, *, node_identifier: str) -> list[dict]:
+        return self._resource.list_by_node(node_identifier=node_identifier)
+
+    def iter_by_node(self, *, node_identifier: str) -> Iterator[dict]:
+        return self._resource.iter_by_node(node_identifier=node_identifier)
+
+    def assign_term(
+        self, *, course_identifier: str, term_identifier: str
+    ) -> dict:
+        return self._service.assign_term(
+            course_identifier=course_identifier,
+            term_identifier=term_identifier,
+        )
+
+    def unassign_term(self, *, course_identifier: str) -> dict:
+        return self._service.unassign_term(
+            course_identifier=course_identifier
+        )
+
+    def list_by_term(self, *, term_identifier: str) -> list[dict]:
+        """List courses assigned to a term by primary ID or ``externalId``."""
+        return self._service.list_by_term(term_identifier=term_identifier)
+
+    def get_copy_history(
+        self, *, course_identifier: str
+    ) -> list[dict] | None:
+        """Return the copy history of a given course."""
+        return self._service.get_copy_history(course_identifier=course_identifier)