PyBlackboard-LMS 0.1.0__tar.gz

pyblackboard_lms-0.1.0/.env.example

@@ -0,0 +1,4 @@
+# Blackboard connection settings
+APP_KEY=replace-me
+APP_SECRET=replace-me
+BB_INSTANCE_URL=https://blackboard.example.com

pyblackboard_lms-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to PyBlackboard-LMS are documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Version numbers have the form `MAJOR.MINOR.PATCH`:
+
+- Increment `MAJOR` for incompatible public API or CLI changes.
+- Increment `MINOR` for backwards-compatible functionality.
+- Increment `PATCH` for backwards-compatible bug fixes.
+
+The single authoritative version is `project.version` in `pyproject.toml`.
+
+## [0.1.0] - 2026-08-30
+
+### Added
+
+- Initial public package structure for the Blackboard API and CLI.

pyblackboard_lms-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Amo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyblackboard_lms-0.1.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include CHANGELOG.md
+include LICENSE
+include .env.example
+include pyproject.toml
+graft src
+prune src/*.egg-info
+
+prune audit
+prune data
+prune devdocs
+prune docs
+prune tests
+global-exclude .env
+global-exclude .env.*
+include .env.example
+global-exclude __pycache__
+global-exclude *.py[cod]

pyblackboard_lms-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: PyBlackboard-LMS
+Version: 0.1.0
+Summary: Python API and command-line interface for Blackboard Learn.
+Author-email: Alex Amo <hello@alejandroamo.eu>
+License-Expression: MIT
+Keywords: blackboard,blackboard-learn,cli,education,lms
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Requires-Dist: pandas<3,>=2.0
+Requires-Dist: XlsxWriter<4,>=3.1
+Provides-Extra: dev
+Requires-Dist: black<27,>=24.0; extra == "dev"
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: check-wheel-contents<1,>=0.6; extra == "dev"
+Requires-Dist: mypy<2,>=1.10; extra == "dev"
+Requires-Dist: ruff<1,>=0.6; extra == "dev"
+Requires-Dist: twine<7,>=5.1; extra == "dev"
+Dynamic: license-file
+
+# PyBlackboard-LMS
+
+Python and command-line interfaces for Blackboard LMS API.
+
+The Python API (`blackboard_api`) provides:
+
+- Resilient HTTP transport and OAuth authentication.
+- API quota tracking.
+- Transparent pagination for object collections.
+- Iterators for consuming large result sets without accumulating every item in memory.
+- An atomic operations layer for individual requests (`resources`).
+- A service layer for combinations of operations, such as upserts (`services`).
+- Public facades with validated, human-oriented methods.
+
+The `blackboard-cli` command exposes every public facade method except iterators,
+and can export data as JSON, CSV, or Microsoft Excel files. It is intended as a
+data exploration and management tool for Blackboard administrators.
+
+## Installation
+
+PyBlackboard-LMS requires Python 3.10 or later.
+
+```text
+python -m pip install PyBlackboard-LMS
+```
+
+The package installs the `blackboard-cli` command and the `blackboard_api` module.
+
+## Configuration with explicit parameter values (API only)
+
+In a Python script:
+
+```python
+from blackboard_api import BlackboardAPI
+client = BlackboardAPI(
+    url="https://blackboard.example.com",
+    client_id="...",
+    client_secret="...",
+)
+```
+
+`url` is the URL of the Blackboard instance. `client_id` is the value called
+`APP_KEY` in the [Blackboard Developer Portal](https://developer.blackboard.com/portal/applications),
+and `client_secret` is its corresponding `APP_SECRET` value.
+
+## Configuration with .env files (API and CLI)
+
+When creating `BlackboardAPI` without direct credentials, `env_file` is required.
+Both the API and CLI use dotenv-style files as their configuration source.
+
+1. Copy the `.env.example` template file to `.env.production.local` and configure it with
+API credentials and Blackboard instance URL of your **PRODUCTION** Blackboard instance.
+
+2. Copy the `.env.example` template file to `.env.test.local` and configure it with
+API credentials and Blackboard instance URL of your **TEST** Blackboard instance,
+if you have any.
+
+You can then specify the ENV-file path with:
+
+```text
+blackboard-cli --env-file .env.production.local <command>
+```
+
+or use the API directly:
+
+```python
+from blackboard_api import BlackboardAPI
+
+client = BlackboardAPI(env_file=".env.production.local")
+```
+
+The optional `BB_REQUEST_CONNECT_TIMEOUT` and `BB_REQUEST_READ_TIMEOUT` ENV
+settings are positive integer durations in seconds. They default to `10` and
+`60`, respectively. You can add them to env files if you want to tweak them.
+
+## Writes are disabled by default
+
+To reduce the risk of accidental changes, mutating operations are disabled by
+default. The API blocks `POST`, `PUT`, `PATCH`, and `DELETE` before they reach
+Blackboard unless writes are explicitly enabled.
+
+You can enable writing operations by passing
+`enable_write=True` to `BlackboardAPI`, or `--enable-write` to the CLI.
+
+## API reference
+
+See [the API reference](docs/api_reference.md) for the public interface and
+internal layers.
+
+## CLI command reference
+
+The CLI exposes one command for every public API facade method except iterators.
+Iterators are intended for progressive data consumption in Python scripts and
+do not provide a useful CLI abstraction.
+
+See [the CLI reference](docs/cli_reference.md) for the complete command list.
+
+Use `--command-help` to view every available command.
+
+## Developers only
+
+### Development setup
+
+Install the project and development tools in editable mode:
+
+```text
+python -m pip install -e ".[dev]"
+```
+
+### Unit tests
+
+Run automated tests with:
+
+```text
+python -m unittest discover -s tests/unit -v
+```
+
+Unit tests are 100% offline and never require Blackboard credentials or an
+environment file.
+
+### Live integration tests
+
+Run live integration tests with:
+
+```text
+python -m tests.integration.run
+```
+
+While unit tests are fully offline, live integration tests connect to Blackboard
+and create, modify, and delete test objects. Use an isolated **test tenant** and
+ensure that `.env.test.local` contains only its credentials. The test runner requires
+that file, but cannot verify that its URL is truly a non-production instance.
+If test environment dot-env file is missing or invalid, live integration tests fail.
+
+The test runner writes the same messages to standard output and to a timestamped log
+under `data/test-artifacts/logs/`. Use `--log-level DEBUG` for HTTP and
+fixture lifecycle diagnostics. It never logs credentials, OAuth tokens, or
+passwords.
+
+The integration test suite uses randomized, easily recognizable identifiers to avoid
+collisions with existing data. Its final test explicitly verifies cleanup,
+and emergency cleanup is attempted when the process exits.
+Failures outside the process or API failures may still require manual review of the
+test tenant.

pyblackboard_lms-0.1.0/README.md

@@ -0,0 +1,144 @@
+# PyBlackboard-LMS
+
+Python and command-line interfaces for Blackboard LMS API.
+
+The Python API (`blackboard_api`) provides:
+
+- Resilient HTTP transport and OAuth authentication.
+- API quota tracking.
+- Transparent pagination for object collections.
+- Iterators for consuming large result sets without accumulating every item in memory.
+- An atomic operations layer for individual requests (`resources`).
+- A service layer for combinations of operations, such as upserts (`services`).
+- Public facades with validated, human-oriented methods.
+
+The `blackboard-cli` command exposes every public facade method except iterators,
+and can export data as JSON, CSV, or Microsoft Excel files. It is intended as a
+data exploration and management tool for Blackboard administrators.
+
+## Installation
+
+PyBlackboard-LMS requires Python 3.10 or later.
+
+```text
+python -m pip install PyBlackboard-LMS
+```
+
+The package installs the `blackboard-cli` command and the `blackboard_api` module.
+
+## Configuration with explicit parameter values (API only)
+
+In a Python script:
+
+```python
+from blackboard_api import BlackboardAPI
+client = BlackboardAPI(
+    url="https://blackboard.example.com",
+    client_id="...",
+    client_secret="...",
+)
+```
+
+`url` is the URL of the Blackboard instance. `client_id` is the value called
+`APP_KEY` in the [Blackboard Developer Portal](https://developer.blackboard.com/portal/applications),
+and `client_secret` is its corresponding `APP_SECRET` value.
+
+## Configuration with .env files (API and CLI)
+
+When creating `BlackboardAPI` without direct credentials, `env_file` is required.
+Both the API and CLI use dotenv-style files as their configuration source.
+
+1. Copy the `.env.example` template file to `.env.production.local` and configure it with
+API credentials and Blackboard instance URL of your **PRODUCTION** Blackboard instance.
+
+2. Copy the `.env.example` template file to `.env.test.local` and configure it with
+API credentials and Blackboard instance URL of your **TEST** Blackboard instance,
+if you have any.
+
+You can then specify the ENV-file path with:
+
+```text
+blackboard-cli --env-file .env.production.local <command>
+```
+
+or use the API directly:
+
+```python
+from blackboard_api import BlackboardAPI
+
+client = BlackboardAPI(env_file=".env.production.local")
+```
+
+The optional `BB_REQUEST_CONNECT_TIMEOUT` and `BB_REQUEST_READ_TIMEOUT` ENV
+settings are positive integer durations in seconds. They default to `10` and
+`60`, respectively. You can add them to env files if you want to tweak them.
+
+## Writes are disabled by default
+
+To reduce the risk of accidental changes, mutating operations are disabled by
+default. The API blocks `POST`, `PUT`, `PATCH`, and `DELETE` before they reach
+Blackboard unless writes are explicitly enabled.
+
+You can enable writing operations by passing
+`enable_write=True` to `BlackboardAPI`, or `--enable-write` to the CLI.
+
+## API reference
+
+See [the API reference](docs/api_reference.md) for the public interface and
+internal layers.
+
+## CLI command reference
+
+The CLI exposes one command for every public API facade method except iterators.
+Iterators are intended for progressive data consumption in Python scripts and
+do not provide a useful CLI abstraction.
+
+See [the CLI reference](docs/cli_reference.md) for the complete command list.
+
+Use `--command-help` to view every available command.
+
+## Developers only
+
+### Development setup
+
+Install the project and development tools in editable mode:
+
+```text
+python -m pip install -e ".[dev]"
+```
+
+### Unit tests
+
+Run automated tests with:
+
+```text
+python -m unittest discover -s tests/unit -v
+```
+
+Unit tests are 100% offline and never require Blackboard credentials or an
+environment file.
+
+### Live integration tests
+
+Run live integration tests with:
+
+```text
+python -m tests.integration.run
+```
+
+While unit tests are fully offline, live integration tests connect to Blackboard
+and create, modify, and delete test objects. Use an isolated **test tenant** and
+ensure that `.env.test.local` contains only its credentials. The test runner requires
+that file, but cannot verify that its URL is truly a non-production instance.
+If test environment dot-env file is missing or invalid, live integration tests fail.
+
+The test runner writes the same messages to standard output and to a timestamped log
+under `data/test-artifacts/logs/`. Use `--log-level DEBUG` for HTTP and
+fixture lifecycle diagnostics. It never logs credentials, OAuth tokens, or
+passwords.
+
+The integration test suite uses randomized, easily recognizable identifiers to avoid
+collisions with existing data. Its final test explicitly verifies cleanup,
+and emergency cleanup is attempted when the process exits.
+Failures outside the process or API failures may still require manual review of the
+test tenant.

pyblackboard_lms-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "PyBlackboard-LMS"
+version = "0.1.0"
+description = "Python API and command-line interface for Blackboard Learn."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Alex Amo", email = "hello@alejandroamo.eu" },
+]
+keywords = ["blackboard", "blackboard-learn", "cli", "education", "lms"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Education",
+]
+dependencies = [
+    "requests>=2.31,<3",
+    "pandas>=2.0,<3",
+    "XlsxWriter>=3.1,<4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black>=24.0,<27",
+    "build>=1.2,<2",
+    "check-wheel-contents>=0.6,<1",
+    "mypy>=1.10,<2",
+    "ruff>=0.6,<1",
+    "twine>=5.1,<7",
+]
+
+[project.scripts]
+blackboard-cli = "blackboard_cli.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["blackboard_api*", "blackboard_cli*"]
+namespaces = false
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+extend-exclude = "^/(build|dist)/"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+extend-exclude = ["build", "dist"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src"]
+check_untyped_defs = true
+warn_return_any = true
+warn_unused_ignores = true
+exclude = "^(build|dist)/"

pyblackboard_lms-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyblackboard_lms-0.1.0/src/PyBlackboard_LMS.egg-info/SOURCES.txt

@@ -0,0 +1,50 @@
+.env.example
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/blackboard_api/__init__.py
+src/blackboard_api/api_quota.py
+src/blackboard_api/auth.py
+src/blackboard_api/client.py
+src/blackboard_api/config.py
+src/blackboard_api/errors.py
+src/blackboard_api/identifiers.py
+src/blackboard_api/transport.py
+src/blackboard_api/facades/__init__.py
+src/blackboard_api/facades/api_quota.py
+src/blackboard_api/facades/courses.py
+src/blackboard_api/facades/enrollments.py
+src/blackboard_api/facades/resources.py
+src/blackboard_api/facades/terms.py
+src/blackboard_api/facades/users.py
+src/blackboard_api/resources/__init__.py
+src/blackboard_api/resources/courses.py
+src/blackboard_api/resources/enrollment_roles.py
+src/blackboard_api/resources/enrollments.py
+src/blackboard_api/resources/nodes.py
+src/blackboard_api/resources/terms.py
+src/blackboard_api/resources/users.py
+src/blackboard_api/services/__init__.py
+src/blackboard_api/services/courses.py
+src/blackboard_api/services/enrollments.py
+src/blackboard_api/services/users.py
+src/blackboard_cli/__init__.py
+src/blackboard_cli/__main__.py
+src/blackboard_cli/cli.py
+src/blackboard_cli/encoding.py
+src/blackboard_cli/application/__init__.py
+src/blackboard_cli/converters/__init__.py
+src/blackboard_cli/converters/common.py
+src/blackboard_cli/converters/courses.py
+src/blackboard_cli/converters/enrollments.py
+src/blackboard_cli/converters/generic.py
+src/blackboard_cli/converters/nodes.py
+src/blackboard_cli/converters/roles.py
+src/blackboard_cli/converters/users.py
+src/blackboard_cli/output/__init__.py
+src/blackboard_cli/output/csv.py
+src/blackboard_cli/output/dataframe.py
+src/blackboard_cli/output/excel.py
+src/blackboard_cli/output/table.py

pyblackboard_lms-0.1.0/src/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",
+]

pyblackboard_lms-0.1.0/src/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

pyblackboard_lms-0.1.0/src/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