pyh5p 0.1.0__py3-none-any.whl

pyh5p/__init__.py

@@ -0,0 +1,44 @@
+"""Generic, schema-driven H5P package tooling.
+
+The core package has no dependency on a particular H5P content type. A library
+store supplies `library.json` and `semantics.json`; the same engine handles
+every supported and future semantic definition.
+"""
+
+from .content import H5PContent, build, load, schema, schema_json
+from .errors import H5PError, PackageError, SecurityError, ValidationError
+from .library import (
+    CoreApiVersion,
+    Dependency,
+    HubClient,
+    Library,
+    LibraryId,
+    LibraryStore,
+    RegistryClient,
+)
+from .package import H5PPackage, PackageLimits, read_package
+from .semantics import SemanticField, Semantics
+
+__all__ = [
+    "Dependency",
+    "CoreApiVersion",
+    "H5PContent",
+    "H5PError",
+    "H5PPackage",
+    "HubClient",
+    "Library",
+    "LibraryId",
+    "LibraryStore",
+    "PackageError",
+    "PackageLimits",
+    "RegistryClient",
+    "SecurityError",
+    "SemanticField",
+    "Semantics",
+    "ValidationError",
+    "build",
+    "load",
+    "read_package",
+    "schema",
+    "schema_json",
+]

pyh5p/_util.py

@@ -0,0 +1,90 @@
+"""Small internal helpers with deterministic and security-conscious behavior."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import mimetypes
+import os
+import re
+from collections.abc import Iterator, Mapping
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+JSONValue = None | bool | int | float | str | list["JSONValue"] | dict[str, "JSONValue"]
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def json_bytes(value: Any) -> bytes:
+    return (canonical_json(value) + "\n").encode("utf-8")
+
+
+def sha256(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def is_safe_relative_path(value: str, *, allow_empty: bool = False) -> bool:
+    if (
+        not isinstance(value, str)
+        or "\x00" in value
+        or ":" in value
+        or (not value and not allow_empty)
+    ):
+        return False
+    if "\\" in value or value.startswith("/") or re.match(r"^[A-Za-z]:", value):
+        return False
+    parts = PurePosixPath(value).parts
+    return all(part not in {"", ".", ".."} for part in parts)
+
+
+def safe_join(root: Path, relative: str) -> Path:
+    if not is_safe_relative_path(relative):
+        raise ValueError(f"unsafe relative path: {relative!r}")
+    target = (root / Path(*PurePosixPath(relative).parts)).resolve()
+    root_resolved = root.resolve()
+    if os.path.commonpath([str(root_resolved), str(target)]) != str(root_resolved):
+        raise ValueError(f"path escapes root: {relative!r}")
+    return target
+
+
+def walk_files(root: Path) -> Iterator[tuple[str, Path]]:
+    for path in sorted(root.rglob("*"), key=lambda item: item.as_posix()):
+        if path.is_file():
+            yield path.relative_to(root).as_posix(), path
+
+
+def version_tuple(value: Any, default: int = 0) -> tuple[int, int, int]:
+    if isinstance(value, (tuple, list)):
+        parts = list(value)
+    else:
+        parts = re.findall(r"\d+", str(value))
+    numbers = [int(item) for item in parts[:3]]
+    numbers.extend([default] * (3 - len(numbers)))
+    return tuple(numbers[:3])  # type: ignore[return-value]
+
+
+def guess_mime(path: str) -> str:
+    return mimetypes.guess_type(path)[0] or "application/octet-stream"
+
+
+def deep_copy_json(value: Any) -> Any:
+    return json.loads(json.dumps(value, ensure_ascii=False))
+
+
+def get_path(value: Any, path: str, default: Any = None) -> Any:
+    current = value
+    if path in {"", "$"}:
+        return current
+    for part in path.replace("$.", "", 1).split("."):
+        if not part:
+            continue
+        if isinstance(current, Mapping):
+            current = current.get(part, default)
+        elif isinstance(current, list) and part.isdigit() and int(part) < len(current):
+            current = current[int(part)]
+        else:
+            return default
+    return current

pyh5p/cli.py

@@ -0,0 +1,169 @@
+"""Command-line interface for inspection and reproducible package workflows."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .content import build
+from .errors import H5PError, LibraryNotFoundError
+from .hooks import JavaScriptCompatibility
+from .library import LibraryStore
+from .package import read_package
+
+
+def _core_api(value: str) -> tuple[int, int]:
+    parts = value.split(".")
+    if len(parts) != 2 or not all(part.isdigit() for part in parts):
+        raise argparse.ArgumentTypeError("Core API must have the form MAJOR.MINOR")
+    return int(parts[0]), int(parts[1])
+
+
+def _store(paths: list[str], *, cache_dir: Path | None = None) -> LibraryStore:
+    return LibraryStore(*paths, cache_dir=cache_dir)
+
+
+def _common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--libraries", action="append", default=[], help="library source directory (repeatable)"
+    )
+
+
+def make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pyh5p", description="Generic H5P inspection, validation and packaging"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    inspect = sub.add_parser("inspect", help="show package metadata and libraries")
+    inspect.add_argument("package", type=Path)
+
+    validate = sub.add_parser("validate", help="validate package structure and content")
+    validate.add_argument("package", type=Path)
+    validate.add_argument("--libraries", action="append", default=[])
+    validate.add_argument(
+        "--content-only", action="store_true", help="allow a package without library files"
+    )
+
+    schema = sub.add_parser("schema", help="emit JSON Schema for an installed library")
+    schema.add_argument("library")
+    _common(schema)
+    schema.add_argument("-o", "--output", type=Path)
+
+    build_parser = sub.add_parser("build", help="build an H5P package from JSON content")
+    build_parser.add_argument("library")
+    build_parser.add_argument("content", type=Path, help="JSON file containing semantic content")
+    build_parser.add_argument("output", type=Path)
+    _common(build_parser)
+    build_parser.add_argument("--title")
+    build_parser.add_argument("--language", default="und")
+    build_parser.add_argument("--content-only", action="store_true")
+    build_parser.add_argument(
+        "--fetch", dest="fetch", action="store_true", default=True,
+        help="download missing official libraries and dependencies (default)",
+    )
+    build_parser.add_argument(
+        "--offline", dest="fetch", action="store_false",
+        help="use only libraries already present in --libraries",
+    )
+    build_parser.add_argument(
+        "--cache-dir", type=Path, default=Path(".pyh5p-libraries"),
+        help="library cache used with --fetch",
+    )
+    build_parser.add_argument(
+        "--core-api", type=_core_api,
+        help="target an H5P Core API, such as 1.27; useful for older hosts",
+    )
+
+    unpack = sub.add_parser("unpack", help="securely unpack an H5P archive")
+    unpack.add_argument("package", type=Path)
+    unpack.add_argument("destination", type=Path)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = make_parser().parse_args(argv)
+    try:
+        if args.command == "inspect":
+            package = read_package(args.package)
+            hooks = {
+                str(item.id): JavaScriptCompatibility().inspect_files(item.files).note
+                for item in package.libraries
+                if "presave.js" in item.files or "upgrades.js" in item.files
+            }
+            print(
+                json.dumps(
+                    {
+                        "metadata": package.metadata,
+                        "content": package.content is not None,
+                        "libraries": [str(item.id) for item in package.libraries],
+                        "files": len(package.files),
+                        "hooks": hooks,
+                    },
+                    indent=2,
+                    ensure_ascii=False,
+                )
+            )
+            return 0
+        if args.command == "validate":
+            package = read_package(args.package)
+            issues = package.validate(
+                require_content=True,
+                allow_content_only=args.content_only,
+            )
+            if args.libraries and package.content is not None:
+                store = _store(args.libraries)
+                main = package.metadata.get("mainLibrary")
+                if isinstance(main, str):
+                    issues.extend(store.schema(main).validate(package.content))
+            if issues:
+                for issue in issues:
+                    print(issue, file=sys.stderr)
+                return 1
+            print("valid")
+            return 0
+        if args.command == "schema":
+            payload = _store(args.libraries).schema(args.library).json_schema()
+            encoded = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+            if args.output:
+                args.output.write_text(encoded, encoding="utf-8")
+            else:
+                print(encoded, end="")
+            return 0
+        if args.command == "build":
+            content = json.loads(args.content.read_text(encoding="utf-8"))
+            store = _store(args.libraries, cache_dir=args.cache_dir if args.fetch else None)
+            if args.fetch:
+                try:
+                    installed = store.get(args.library)
+                except LibraryNotFoundError:
+                    store.install_from_hub(args.library, core_api=args.core_api)
+                else:
+                    if args.core_api is not None:
+                        closure = store.resolve_closure(installed.id)
+                        if any(
+                            not item.core_api.compatible_with(args.core_api)
+                            for item in closure.all
+                        ):
+                            store.install_from_hub(args.library, core_api=args.core_api)
+            result = build(
+                args.library,
+                content,
+                store=store,
+                title=args.title,
+                language=args.language,
+                target_core_api=args.core_api,
+            )
+            result.save(args.output, content_only=args.content_only)
+            print(args.output)
+            return 0
+        if args.command == "unpack":
+            read_package(args.package).extract(args.destination)
+            print(args.destination)
+            return 0
+    except (OSError, ValueError, H5PError, json.JSONDecodeError) as exc:
+        print(f"pyh5p: {exc}", file=sys.stderr)
+        return 2
+    return 2