myprepcourse 0.1.0__py3-none-any.whl

MyPrepCourse/MPCSession.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+import logging
+import os
+import time
+from datetime import datetime, timezone
+from typing import Any, Mapping
+import requests
+from dateutil import parser as dateparser
+
+from .exceptions import AuthenticationError
+from .logging_utils import get_logger
+
+DEFAULT_BASE_URL = "https://api.myprepcourse.com"
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/110.0.5481.78 Safari/537.36"
+)
+
+
+class MPCSession:
+    """Low-level session wrapper for making authenticated API requests."""
+
+    def __init__(
+        self,
+        email: str | None = None,
+        password: str | None = None,
+        *,
+        token: str | None = None,
+        token_expiry: datetime | None = None,
+        base_url: str | None = None,
+        origin: str | None = None,
+        user_agent: str = DEFAULT_USER_AGENT,
+        course_id: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: int = 30,
+        retry_after_default: int = 30,
+        max_retries: int = 3,
+        logger: logging.Logger | None = None,
+    ):
+        """Initialize a session for API requests.
+
+        :param email: Account email address for authentication.
+        :param password: Account password for authentication.
+        :param token: Existing bearer token to use instead of logging in.
+        :param token_expiry: Optional token expiry timestamp.
+        :param base_url: Base URL for the API. Falls back to the
+            ``MYPREPCOURSE_BASE_URL`` environment variable, then to
+            ``DEFAULT_BASE_URL``.
+        :param origin: Tenant origin URL to send as the Origin header. Falls
+            back to the ``MYPREPCOURSE_ORIGIN`` environment variable.
+        :param user_agent: User agent header to include with requests.
+        :param course_id: Optional course ID header to set.
+        :param headers: Additional headers to include with requests.
+        :param timeout: Request timeout in seconds.
+        :param retry_after_default: Retry delay in seconds for rate limiting.
+        :param max_retries: Maximum number of retries for rate-limited requests.
+        :param logger: Optional logger for request logging.
+        :raises ValueError: When no origin is provided by argument or environment.
+        """
+        self.logger = logger or get_logger("session")
+        # The MyPrepCourse API expects a double-slash path structure.
+        resolved_base_url = (
+            base_url or os.environ.get("MYPREPCOURSE_BASE_URL") or DEFAULT_BASE_URL
+        )
+        self.base_url = resolved_base_url + "//api/"
+        self.timeout = timeout
+        self.retry_after_default = retry_after_default
+        self.max_retries = max_retries
+
+        self.token = token
+        self.token_expiry = token_expiry
+        self.recent_login_response = None
+        self.user = None
+        self.origin = origin or os.environ.get("MYPREPCOURSE_ORIGIN")
+        if not self.origin:
+            raise ValueError(
+                "Origin URL is required (e.g., 'https://yourorg.myprepcourse.com'). "
+                "Pass origin= or set MYPREPCOURSE_ORIGIN."
+            )
+
+        # The MyPrepCourse API validates browser-like headers and rejects
+        # requests without them, so we include standard browser headers.
+        self.headers = {
+            "Origin": self.origin,
+            "User-Agent": user_agent,
+            "Content-Type": "application/json",
+            "Access-Control-Allow-Origin": "*",
+            "Accept": "application/json",
+            "Sec-Ch-Ua-Platform": "Windows",
+            "Sec-Fetch-Site": "same-site",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Dest": "empty",
+            "Referrer": f"{self.origin.rstrip('/')}/",
+        }
+        if course_id:
+            self.headers["X-Course-Id"] = course_id
+        if headers:
+            self.headers.update(headers)
+
+        self.email = email or os.environ.get("MYPREPCOURSE_EMAIL")
+        self.password = password or os.environ.get("MYPREPCOURSE_PASSWORD")
+
+        self.session = requests.Session()
+        self.session.headers.update(self.headers)
+
+        if self.token:
+            self.update_header("Authorization", f"Bearer {self.token}")
+
+    def update_header(self, header: str, value: str) -> None:
+        """Update a single header value for the session."""
+        self.headers[header] = value
+        self.session.headers.update(self.headers)
+
+    def set_credentials(self, email: str, password: str) -> None:
+        """Update stored credentials for authentication."""
+        self.email = email
+        self.password = password
+
+    def set_token(self, token: str, token_expiry: datetime | None = None) -> None:
+        """Update the bearer token and optional expiry."""
+        self.token = token
+        if token_expiry is not None:
+            self.token_expiry = token_expiry
+        self.update_header("Authorization", f"Bearer {token}")
+
+    def login(self) -> str:
+        """Authenticate and refresh the bearer token.
+
+        :raises AuthenticationError: If no credentials are set, or the API rejects them.
+        :raises requests.RequestException: If the HTTP request fails.
+        """
+        self.logger.info("Logging in")
+        if self.email and self.password:
+            login_data = {
+                "email": self.email,
+                "password": self.password,
+            }
+            login_url = f"{self.base_url}login"
+            self.session.headers.update(self.headers)
+            self.recent_login_response = self.session.post(
+                login_url,
+                json=login_data,
+                timeout=self.timeout,
+            )
+            response = self.recent_login_response
+            self.logger.debug(
+                "Login response <%s>: %s",
+                response.status_code,
+                response.content,
+            )
+            if response.status_code == 200:
+                self.logger.info("Login valid. Updating authorization information")
+                content = response.json()
+                self.token = content["token"]
+                self.token_expiry = dateparser.parse(content["expires_at"])
+                self.update_header("Authorization", f"Bearer {self.token}")
+                return self.token
+            raise AuthenticationError(
+                f"Login failed with status {response.status_code}: {response.text}"
+            )
+        raise AuthenticationError("Email and password are required to login.")
+
+    def logout(self) -> requests.Response:
+        """Log out the current session.
+
+        :raises requests.RequestException: If the HTTP request fails.
+        """
+        response = self.session.post(
+            f"{self.base_url}logout",
+            timeout=self.timeout,
+        )
+        return response
+
+    def check_token(self) -> None:
+        """Ensure a valid token is available, re-authenticating if necessary.
+
+        :raises AuthenticationError: If the token expired and re-authentication fails.
+        """
+        if not self.token:
+            self.logger.debug("No token set; attempting login.")
+            self.login()
+            return
+        if self.token_expiry:
+            expiry = self.token_expiry
+            if expiry.tzinfo is None:
+                expiry = expiry.replace(tzinfo=timezone.utc)
+            if datetime.now(tz=timezone.utc) >= expiry:
+                self.logger.info("Token expired; re-authenticating.")
+                self.login()
+
+    def _request(self, method: str, url: str, data: Mapping[str, Any] | None = None) -> requests.Response:
+        """Make an authenticated request with retry handling."""
+        self.logger.debug("%s %s: %s", method, url, data)
+        self.check_token()
+        response = self.session.request(
+            method,
+            f"{self.base_url}{url}",
+            json=data,
+            timeout=self.timeout,
+        )
+        if response.status_code == 401:
+            self.logger.info("Unauthorized, re-authenticating")
+            self.login()
+            response = self.session.request(
+                method,
+                f"{self.base_url}{url}",
+                json=data,
+                timeout=self.timeout,
+            )
+        for attempt in range(self.max_retries):
+            if response.status_code != 429:
+                break
+            retry_after = response.headers.get("Retry-After")
+            base_wait = int(retry_after) if retry_after else self.retry_after_default
+            wait_time = min(base_wait * (2 ** attempt), 120)
+            self.logger.warning(
+                "Rate limited (attempt %s/%s), waiting %s seconds",
+                attempt + 1, self.max_retries, wait_time,
+            )
+            time.sleep(wait_time)
+            response = self.session.request(
+                method,
+                f"{self.base_url}{url}",
+                json=data,
+                timeout=self.timeout,
+            )
+        return response
+
+    def get(self, url: str = "") -> requests.Response:
+        """
+        Performs a GET request against the MyPrepCourse API, ensuring valid authentication.
+
+        :param url: The relative URL to call on the API.
+        :returns: The HTTP response object from the GET request.
+        :raises AuthenticationError: If re-authentication is required and fails.
+        :raises requests.RequestException: If the HTTP request fails (connection
+            error, timeout, or similar).
+        """
+        return self._request("GET", url)
+
+    def get_all(self, url: str = "", per_page: int | None = 25) -> list[Mapping[str, Any]]:
+        """
+        Performs GET requests to retrieve all paginated results from the MyPrepCourse API.
+
+        :param url: The relative URL to call on the API.
+        :param per_page: The number of items to retrieve per page. Defaults to 25.
+        :returns: A list of all items retrieved from the paginated GET requests.
+        :raises AuthenticationError: If re-authentication is required and fails.
+        :raises requests.RequestException: If the HTTP request fails (connection
+            error, timeout, or similar).
+        """
+        all_items = []
+        page = 1
+
+        while True:
+            response = self.get(url + f"?page={page}&per_page={per_page}")
+            if not response.ok:
+                self.logger.error("Failed to retrieve data: %s from page %s", response.text, page)
+                break
+
+            data = response.json().get('data', [])
+            all_items.extend(data)
+
+            if page == response.json().get('meta', {}).get('last_page', page):
+                break
+            page += 1
+
+        return all_items
+
+    def post(self, url: str = "", data: Mapping[str, Any] | None = None) -> requests.Response:
+        """
+        Performs a POST request against the MyPrepCourse API, ensuring valid authentication.
+
+        :param url: The relative URL to call on the API.
+        :param data: The data to include in the POST request.
+        :returns: The HTTP response object from the POST request.
+        :raises AuthenticationError: If re-authentication is required and fails.
+        :raises requests.RequestException: If the HTTP request fails (connection
+            error, timeout, or similar).
+        """
+        return self._request("POST", url, data)
+
+    def patch(self, url: str = "", data: Mapping[str, Any] | None = None) -> requests.Response:
+        """
+        Performs a PATCH request against the MyPrepCourse API, ensuring valid authentication.
+
+        :param url: The relative URL to call on the API.
+        :param data: The data to include in the PATCH request.
+        :returns: The HTTP response object from the PATCH request.
+        :raises AuthenticationError: If re-authentication is required and fails.
+        :raises requests.RequestException: If the HTTP request fails (connection
+            error, timeout, or similar).
+        """
+        return self._request("PATCH", url, data)
+
+    def delete(self, url: str = "", data: Mapping[str, Any] | None = None) -> requests.Response:
+        """
+        Performs a DELETE request against the MyPrepCourse API, ensuring valid authentication.
+
+        :param url: The relative URL to call on the API.
+        :param data: The data to include in the DELETE request.
+        :returns: The HTTP response object from the DELETE request.
+        :raises AuthenticationError: If re-authentication is required and fails.
+        :raises requests.RequestException: If the HTTP request fails (connection
+            error, timeout, or similar).
+        """
+        return self._request("DELETE", url, data)