ff-ltitoolkit 0.1.0__tar.gz

ff_ltitoolkit-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenvs
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Keys / secrets (never commit tool private keys)
+*.pem
+.env
+
+# Reference clone we vendored from (kept locally, not part of the package)
+/pylti1.3/

ff_ltitoolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Dmitry Viskov
+
+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.

ff_ltitoolkit-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: ff-ltitoolkit
+Version: 0.1.0
+Summary: Framework-agnostic LTI 1.3 Advantage toolkit for Python — connect any app to any LMS.
+Project-URL: Homepage, https://github.com/CNIT-Organization/ltitoolkit
+Project-URL: Repository, https://github.com/CNIT-Organization/ltitoolkit
+Project-URL: Issues, https://github.com/CNIT-Organization/ltitoolkit/issues
+Author: Faisal Fida
+License-Expression: MIT
+License-File: LICENSE
+Keywords: canvas,education,lms,lti,lti-advantage,lti1.3,moodle,oidc
+Classifier: Development Status :: 3 - Alpha
+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
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jwcrypto>=1.5
+Requires-Dist: pyjwt[crypto]<3,>=2.8
+Requires-Dist: requests>=2.31
+Requires-Dist: typing-extensions>=4.9
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Requires-Dist: itsdangerous>=2.1; extra == 'fastapi'
+Requires-Dist: python-multipart>=0.0.9; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# ltitoolkit
+
+A framework-agnostic **LTI 1.3 Advantage** toolkit for Python. Connect any Python
+application to any LTI 1.3 compliant LMS — Canvas, Moodle, Blackboard, and more —
+with a single dependency.
+
+> Status: **early development (v0.1.0)** — the vendored LTI engine is in place;
+> the FastAPI adapter, Dynamic Registration, and token minting are being built.
+> See [`docs/PROJECT.md`](./docs/PROJECT.md) for the design rationale, capability
+> boundaries, and roadmap.
+
+## What it does (portable — same code on every LMS)
+
+- **Launch & identity** — verified OIDC/JWT launch: who the user is, which course,
+  what role.
+- **LTI Advantage**
+  - **AGS** — read/write grades for your tool's activities.
+  - **NRPS** — fetch the current course roster.
+  - **Deep Linking** — let instructors embed your content into a course.
+- **Dynamic Registration** — install on a new LMS by pasting one URL (no credentials).
+- **Client-credentials tokens** — authenticate as the tool with its own key; no user
+  login required.
+
+## What it deliberately does **not** do
+
+LTI is not a remote control for the whole LMS. Listing all courses, browsing/opening
+files, or creating native quizzes require each LMS's **proprietary** REST API and are
+**not** part of this portable core. Put that code in thin, per-LMS adapters (e.g. a
+Canvas adapter) built on top of the toolkit's generic token minting.
+
+## Layout
+
+```
+src/ltitoolkit/
+├── core/                  # vendored LTI 1.3 engine (PyLTI1p3, rebranded) — internal
+├── fastapi/               # FastAPI adapter (Phase 2)
+├── token/                 # generic client-credentials token minting (Phase 4)
+└── dynamic_registration/  # single-URL install (Phase 5)
+```
+
+## Install (as a dependency)
+
+Published via Git (no PyPI required). Pin to a tag:
+
+```bash
+pip install "git+https://github.com/CNIT-Organization/ltitoolkit.git@v0.1.0"
+# with the FastAPI adapter:
+pip install "ltitoolkit[fastapi] @ git+https://github.com/CNIT-Organization/ltitoolkit.git@v0.1.0"
+```
+
+## Develop (uv)
+
+```bash
+uv sync            # create the env + install runtime, fastapi extra, and dev tools
+uv run pytest      # tests
+uv run ruff check src tests
+uv run mypy src
+uv build           # build wheel + sdist into dist/
+```
+
+## License
+
+MIT. The `core/` engine is a vendored copy of
+[PyLTI1p3](https://github.com/dmitry-viskov/pylti1.3) (MIT); its original license
+is preserved in [`LICENSE`](./LICENSE).

ff_ltitoolkit-0.1.0/README.md

@@ -0,0 +1,65 @@
+# ltitoolkit
+
+A framework-agnostic **LTI 1.3 Advantage** toolkit for Python. Connect any Python
+application to any LTI 1.3 compliant LMS — Canvas, Moodle, Blackboard, and more —
+with a single dependency.
+
+> Status: **early development (v0.1.0)** — the vendored LTI engine is in place;
+> the FastAPI adapter, Dynamic Registration, and token minting are being built.
+> See [`docs/PROJECT.md`](./docs/PROJECT.md) for the design rationale, capability
+> boundaries, and roadmap.
+
+## What it does (portable — same code on every LMS)
+
+- **Launch & identity** — verified OIDC/JWT launch: who the user is, which course,
+  what role.
+- **LTI Advantage**
+  - **AGS** — read/write grades for your tool's activities.
+  - **NRPS** — fetch the current course roster.
+  - **Deep Linking** — let instructors embed your content into a course.
+- **Dynamic Registration** — install on a new LMS by pasting one URL (no credentials).
+- **Client-credentials tokens** — authenticate as the tool with its own key; no user
+  login required.
+
+## What it deliberately does **not** do
+
+LTI is not a remote control for the whole LMS. Listing all courses, browsing/opening
+files, or creating native quizzes require each LMS's **proprietary** REST API and are
+**not** part of this portable core. Put that code in thin, per-LMS adapters (e.g. a
+Canvas adapter) built on top of the toolkit's generic token minting.
+
+## Layout
+
+```
+src/ltitoolkit/
+├── core/                  # vendored LTI 1.3 engine (PyLTI1p3, rebranded) — internal
+├── fastapi/               # FastAPI adapter (Phase 2)
+├── token/                 # generic client-credentials token minting (Phase 4)
+└── dynamic_registration/  # single-URL install (Phase 5)
+```
+
+## Install (as a dependency)
+
+Published via Git (no PyPI required). Pin to a tag:
+
+```bash
+pip install "git+https://github.com/CNIT-Organization/ltitoolkit.git@v0.1.0"
+# with the FastAPI adapter:
+pip install "ltitoolkit[fastapi] @ git+https://github.com/CNIT-Organization/ltitoolkit.git@v0.1.0"
+```
+
+## Develop (uv)
+
+```bash
+uv sync            # create the env + install runtime, fastapi extra, and dev tools
+uv run pytest      # tests
+uv run ruff check src tests
+uv run mypy src
+uv build           # build wheel + sdist into dist/
+```
+
+## License
+
+MIT. The `core/` engine is a vendored copy of
+[PyLTI1p3](https://github.com/dmitry-viskov/pylti1.3) (MIT); its original license
+is preserved in [`LICENSE`](./LICENSE).

ff_ltitoolkit-0.1.0/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ff-ltitoolkit"
+version = "0.1.0"
+description = "Framework-agnostic LTI 1.3 Advantage toolkit for Python — connect any app to any LMS."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["lti", "lti1.3", "lti-advantage", "lms", "canvas", "moodle", "oidc", "education"]
+authors = [{ name = "Faisal Fida" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "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",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+# Pinned deliberately (we own the vendored core, so we control its deps).
+# pyjwt[crypto] pulls `cryptography`, required for RS256 sign/verify.
+dependencies = [
+    "pyjwt[crypto]>=2.8,<3",
+    "jwcrypto>=1.5",
+    "requests>=2.31",
+    "typing_extensions>=4.9",
+]
+
+# Runtime extra: consumers who use the FastAPI adapter install `ltitoolkit[fastapi]`.
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.110",
+    "itsdangerous>=2.1",      # required by Starlette SessionMiddleware
+    "python-multipart>=0.0.9",  # required to read the form-POSTed id_token
+]
+
+[project.urls]
+Homepage = "https://github.com/CNIT-Organization/ltitoolkit"
+Repository = "https://github.com/CNIT-Organization/ltitoolkit"
+Issues = "https://github.com/CNIT-Organization/ltitoolkit/issues"
+
+# Dev-only tooling (PEP 735). Not published to consumers; `uv sync` installs it
+# by default. Tests exercise the FastAPI adapter, so pull that extra in here.
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "httpx>=0.27",  # required by fastapi.testclient.TestClient
+    "ff-ltitoolkit[fastapi]",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ltitoolkit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/ltitoolkit", "LICENSE", "README.md"]
+
+# ---------------------------------------------------------------------------
+# Tooling — clean defaults
+# ---------------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+# The vendored core is upstream code; lint only our own code.
+extend-exclude = ["src/ltitoolkit/core"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_ignores = true
+ignore_missing_imports = true
+# Don't type-check the vendored core; it has its own (looser) conventions.
+exclude = ["src/ltitoolkit/core/"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

ff_ltitoolkit-0.1.0/src/ltitoolkit/__init__.py

@@ -0,0 +1,20 @@
+"""ltitoolkit — a framework-agnostic LTI 1.3 Advantage toolkit for Python.
+
+Connect any Python application to any LTI 1.3 compliant LMS (Canvas, Moodle,
+Blackboard, …) with one dependency:
+
+- LTI 1.3 launch + identity (who, which course, what role)
+- LTI Advantage: Assignment & Grade Services (AGS), Names & Role Provisioning
+  (NRPS), and Deep Linking — portable across every LMS
+- Dynamic Registration: single-URL, no-credentials tool install
+- Generic client-credentials token minting for LMS service/API calls
+
+The portable LTI engine lives in :mod:`ltitoolkit.core` (vendored). Framework
+glue lives in adapters such as :mod:`ltitoolkit.fastapi`. LMS-proprietary REST
+calls (listing files, quizzes, etc.) are intentionally *not* part of the core —
+they belong in thin, separate per-LMS adapters.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

ff_ltitoolkit-0.1.0/src/ltitoolkit/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""Per-LMS adapters for *proprietary* (Layer 3) APIs.
+
+Everything in this package is intentionally **outside** the portable LTI core.
+LTI standardises identity, roster (NRPS), and grades (AGS) — but **not** browsing
+course files, listing quizzes, or reading the full gradebook. Those require each
+LMS's own REST API, which differs per vendor and is not portable.
+
+Adapters here build on the portable pieces (`ltitoolkit.token` for auth,
+`ltitoolkit.http` for sessions, `ltitoolkit.exceptions` for errors) but call
+vendor-specific endpoints. Use them only against the LMS they target.
+"""

ff_ltitoolkit-0.1.0/src/ltitoolkit/adapters/brightspace/__init__.py

@@ -0,0 +1,35 @@
+"""Brightspace (D2L) proprietary REST API adapter (Layer 3 — NOT portable).
+
+Calls Brightspace's own Valence LE API (course content: modules, topics, files)
+using the tool's OAuth2 client-credentials token minted for a Service User — no
+user login. Requires the registered OAuth client to carry the matching scopes
+(e.g. ``content:modules:read``); the LMS admin approves those once at install.
+
+This works **only** on Brightspace. Other LMSs need their own adapter.
+"""
+
+from .client import (
+    SCOPE_CONTENT_FILE_READ,
+    SCOPE_CONTENT_READ,
+    SCOPE_CONTENT_TOPICS_READ,
+    SCOPE_ENROLLMENT_READ,
+    TOPIC_FILE,
+    TOPIC_LINK,
+    TYPE_MODULE,
+    TYPE_TOPIC,
+    BrightspaceAPIClient,
+    TokenProvider,
+)
+
+__all__ = [
+    "BrightspaceAPIClient",
+    "TokenProvider",
+    "SCOPE_CONTENT_READ",
+    "SCOPE_CONTENT_TOPICS_READ",
+    "SCOPE_CONTENT_FILE_READ",
+    "SCOPE_ENROLLMENT_READ",
+    "TYPE_MODULE",
+    "TYPE_TOPIC",
+    "TOPIC_FILE",
+    "TOPIC_LINK",
+]

ff_ltitoolkit-0.1.0/src/ltitoolkit/adapters/brightspace/client.py

@@ -0,0 +1,176 @@
+"""A thin Brightspace (D2L) Valence REST API client — Layer 3, NOT portable.
+
+Reads course content (modules / topics / files) from the Brightspace **Learning
+Environment (LE)** API, authenticated by an OAuth2 *client-credentials* Bearer
+token minted for a Brightspace **Service User** — no user login. The token's
+scopes are Brightspace scopes (``content:modules:read`` …) approved once on the
+registered OAuth client; the admin does that at install, the student does nothing.
+
+Brightspace's client-credentials assertion (``iss``=``sub``=client_id, ``aud``=
+token endpoint, RS256 + ``kid``) is exactly what
+:class:`ltitoolkit.token.AccessTokenService` already produces — only the token
+endpoint differs (``https://auth.brightspace.com/core/connect/token``).
+
+Endpoints (per docs.valence.desire2learn.com):
+
+    GET /d2l/api/le/{ver}/{orgUnitId}/content/root/
+    GET /d2l/api/le/{ver}/{orgUnitId}/content/modules/{moduleId}/structure/
+    GET /d2l/api/le/{ver}/{orgUnitId}/content/topics/{topicId}
+    GET /d2l/api/le/{ver}/{orgUnitId}/content/topics/{topicId}/file
+
+Works **only** on Brightspace. Other LMSs need their own adapter.
+
+.. note::
+   Response shapes follow the Valence docs. Verify against the client's instance
+   and its LE ``version`` (see ``GET /d2l/api/le/versions/``) before the demo.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+import requests
+
+from ...exceptions import ExternalRequestError
+from ...http import build_session
+
+# OAuth2 scopes (format: ``<group>:<resource>:<action>``), approved on the
+# registered OAuth client / Service User by the admin once.
+SCOPE_CONTENT_READ = "content:modules:read"
+SCOPE_CONTENT_TOPICS_READ = "content:topics:read"
+SCOPE_CONTENT_FILE_READ = "content:file:read"
+SCOPE_ENROLLMENT_READ = "enrollment:orgunit:read"
+
+# ContentObject.Type values.
+TYPE_MODULE = 0
+TYPE_TOPIC = 1
+
+# Topic.TopicType values.
+TOPIC_FILE = 1
+TOPIC_LINK = 3
+
+# Default LE API version; override per instance.
+_DEFAULT_LE_VERSION = "1.74"
+# Recursion guard against pathological / cyclic module structures.
+_MAX_MODULE_DEPTH = 25
+
+
+@t.runtime_checkable
+class TokenProvider(t.Protocol):
+    """Anything that can mint a Bearer token for a set of scopes."""
+
+    def get_token(self, scopes: t.Sequence[str]) -> str: ...
+
+
+class BrightspaceAPIClient:
+    """Read-only convenience wrapper over the Brightspace LE content API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token_provider: TokenProvider,
+        scopes: t.Sequence[str],
+        *,
+        le_version: str = _DEFAULT_LE_VERSION,
+        session: requests.Session | None = None,
+    ) -> None:
+        self._base = base_url.rstrip("/")
+        self._tokens = token_provider
+        self._scopes = tuple(scopes)
+        self._ver = le_version
+        self._session = session if session is not None else build_session()
+
+    # -- public API --------------------------------------------------------
+
+    def get_content_root(self, org_unit_id: str | int) -> list[dict[str, t.Any]]:
+        """Top-level modules of a course (``Type == TYPE_MODULE``)."""
+        return self._get_list(self._le(org_unit_id, "content/root/"))
+
+    def get_module_structure(
+        self, org_unit_id: str | int, module_id: str | int
+    ) -> list[dict[str, t.Any]]:
+        """Direct children of a module — a mix of submodules and topics."""
+        return self._get_list(
+            self._le(org_unit_id, f"content/modules/{module_id}/structure/")
+        )
+
+    def get_topic(self, org_unit_id: str | int, topic_id: str | int) -> dict[str, t.Any]:
+        """Metadata for a single topic (``Title``, ``TopicType``, ``Url`` …)."""
+        return self._get_json(self._le(org_unit_id, f"content/topics/{topic_id}"))
+
+    def download_topic_file(
+        self, org_unit_id: str | int, topic_id: str | int, *, stream: bool = False
+    ) -> bytes:
+        """Raw bytes of a file-type topic (feed to NeuralMentor's ingestion)."""
+        params = {"stream": "true"} if stream else None
+        response = self._request(
+            self._le(org_unit_id, f"content/topics/{topic_id}/file"), params
+        )
+        return response.content
+
+    def list_course_topics(self, org_unit_id: str | int) -> list[dict[str, t.Any]]:
+        """Flat list of every topic in a course (walks the full module tree).
+
+        Each topic is the raw ContentObject; useful as "the course's lessons" to
+        feed into a lesson-generation pipeline. Submodules are traversed; cycles
+        and excessive depth are guarded against.
+        """
+        topics: list[dict[str, t.Any]] = []
+        seen: set[t.Any] = set()
+
+        def walk(entries: list[dict[str, t.Any]], depth: int) -> None:
+            if depth > _MAX_MODULE_DEPTH:
+                return
+            for obj in entries:
+                if obj.get("Type") == TYPE_TOPIC:
+                    topics.append(obj)
+                elif obj.get("Type") == TYPE_MODULE:
+                    module_id = obj.get("Id")
+                    if module_id is None or module_id in seen:
+                        continue
+                    seen.add(module_id)
+                    walk(self.get_module_structure(org_unit_id, module_id), depth + 1)
+
+        walk(self.get_content_root(org_unit_id), 0)
+        return topics
+
+    # -- internals ---------------------------------------------------------
+
+    def _le(self, org_unit_id: str | int, path: str) -> str:
+        return f"{self._base}/d2l/api/le/{self._ver}/{org_unit_id}/{path}"
+
+    def _headers(self) -> dict[str, str]:
+        token = self._tokens.get_token(self._scopes)
+        return {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+
+    def _request(
+        self, url: str, params: dict[str, t.Any] | None = None
+    ) -> requests.Response:
+        try:
+            response = self._session.get(url, params=params, headers=self._headers())
+        except requests.Timeout as exc:
+            raise ExternalRequestError(
+                f"Timed out calling Brightspace: {exc}", url=url, is_timeout=True
+            ) from exc
+        except requests.RequestException as exc:
+            raise ExternalRequestError(
+                f"Error calling Brightspace: {exc}", url=url
+            ) from exc
+
+        if not response.ok:
+            raise ExternalRequestError(
+                "Brightspace API request failed",
+                status_code=response.status_code,
+                url=url,
+                response_text=response.text,
+            )
+        return response
+
+    def _get_json(self, url: str) -> dict[str, t.Any]:
+        return self._request(url).json()
+
+    def _get_list(self, url: str) -> list[dict[str, t.Any]]:
+        body = self._request(url).json()
+        if not isinstance(body, list):
+            raise ExternalRequestError("Expected a list response from Brightspace", url=url)
+        return body

ff_ltitoolkit-0.1.0/src/ltitoolkit/adapters/canvas/__init__.py

@@ -0,0 +1,27 @@
+"""Canvas LMS proprietary REST API adapter (Layer 3 — NOT portable).
+
+Calls Canvas's own REST API (files, quizzes, …) using the tool's LTI
+client-credentials token — no user login. Requires the tool's developer key to
+carry the matching Canvas API scopes (e.g. ``url:GET|/api/v1/courses/:id/files``);
+the LMS admin approves those once at install.
+
+This works **only** on Canvas. Other LMSs need their own adapter.
+"""
+
+from .client import (
+    SCOPE_GET_FILE,
+    SCOPE_GET_FILE_PUBLIC_URL,
+    SCOPE_LIST_COURSE_FILES,
+    SCOPE_LIST_QUIZZES,
+    CanvasAPIClient,
+    TokenProvider,
+)
+
+__all__ = [
+    "CanvasAPIClient",
+    "TokenProvider",
+    "SCOPE_LIST_COURSE_FILES",
+    "SCOPE_GET_FILE",
+    "SCOPE_GET_FILE_PUBLIC_URL",
+    "SCOPE_LIST_QUIZZES",
+]