smd-reports 0.1.0__py3-none-any.whl

smd_reports/__init__.py

@@ -0,0 +1,29 @@
+"""JSON-based report rendering with embedded HTML assets and optional PDF export."""
+
+import logging
+
+__version__ = "0.1.0"
+
+from .errors import (
+    PDFUnavailableError,
+    ReportAssetError,
+    ReportInputError,
+    ReportRenderError,
+    format_validation_error,
+)
+from .loading import ReportLoader
+from .rendering import ReportRenderer
+from .themes import Theme
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "ReportLoader",
+    "ReportRenderer",
+    "ReportAssetError",
+    "ReportInputError",
+    "ReportRenderError",
+    "PDFUnavailableError",
+    "format_validation_error",
+    "Theme",
+]

smd_reports/__main__.py

@@ -0,0 +1,5 @@
+"""Allow the same commands through python -m smd_reports."""
+
+from .cli import main
+
+raise SystemExit(main())

smd_reports/_models.py

@@ -0,0 +1,80 @@
+"""Base models and field types for report JSON."""
+
+from typing import Annotated, Literal
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictBool,
+    StrictFloat,
+    StrictInt,
+    StrictStr,
+    field_validator,
+)
+
+Language = Literal["en", "sv"]
+Translations = Annotated[dict[Language, str], Field(min_length=1)]
+LocalizedText = str | Translations
+Scalar = StrictBool | StrictInt | StrictFloat | StrictStr | None
+CellValue = Scalar | Translations
+
+
+class Model(BaseModel):
+    """Reject unknown fields and non-finite numbers."""
+
+    model_config = ConfigDict(extra="forbid", allow_inf_nan=False, validate_assignment=True)
+
+
+class FieldValue(Model):
+    """An ordered metadata label paired with a scalar or translated value."""
+
+    label: LocalizedText
+    value: CellValue
+
+
+class ImageAsset(Model):
+    """A local or embedded plot and its display options.
+
+    Attributes:
+        source: Local path or embedded data URI.
+        caption: Literal or translated caption text.
+        alt: Alternative text, falling back to the caption when omitted.
+        frame: Zero-based frame or TIFF page index.
+        width_percent: Width relative to the content area.
+        max_height_mm: Optional additional physical height limit.
+    """
+
+    source: str
+    caption: LocalizedText = ""
+    alt: LocalizedText = ""
+    frame: int = Field(default=0, ge=0)
+    width_percent: float = Field(default=100, gt=0, le=100)
+    max_height_mm: float | None = Field(default=None, gt=0)
+
+    @field_validator("source")
+    @classmethod
+    def image_reference(cls, value):
+        """Validate the image path or embedded content.
+
+        Args:
+            value: Local image path or base64 data URI.
+
+        Returns:
+            The validated reference.
+
+        Raises:
+            ValueError: The reference or embedded image is unsupported.
+        """
+        from .assets import validate_image_reference
+
+        return validate_image_reference(value)
+
+
+class SectionBase(Model):
+    """Shared section identity, heading, pagination, and inline image fields."""
+
+    key: str = Field(min_length=1)
+    heading: LocalizedText = ""
+    page_break_before: bool = False
+    images: list[ImageAsset] = Field(default_factory=list)

smd_reports/assets.py

@@ -0,0 +1,196 @@
+"""Embed local report artwork and validate static SVG without external resources."""
+
+import base64
+import re
+from io import BytesIO
+from pathlib import Path
+from typing import Literal
+
+from defusedxml import ElementTree
+
+from .errors import ReportInputError
+
+ImageFormat = Literal["png", "jpeg", "svg", "webp", "gif", "tiff", "bmp"]
+IMAGE_MIMES = {
+    "png": "image/png",
+    "jpeg": "image/jpeg",
+    "svg": "image/svg+xml",
+    "webp": "image/webp",
+    "gif": "image/gif",
+    "tiff": "image/tiff",
+    "bmp": "image/bmp",
+}
+IMAGE_EXTENSIONS = {
+    ".png": "png",
+    ".jpg": "jpeg",
+    ".jpeg": "jpeg",
+    ".svg": "svg",
+    ".webp": "webp",
+    ".gif": "gif",
+    ".tif": "tiff",
+    ".tiff": "tiff",
+    ".bmp": "bmp",
+}
+
+
+def validate_image_reference(value: str) -> str:
+    """Validate a local path or embedded image reference without fetching URLs.
+
+    Args:
+        value: An image path or base64 data URI.
+
+    Returns:
+        The validated reference.
+
+    Raises:
+        ValueError: The path is empty or remote, or embedded image data is invalid.
+    """
+    if value.startswith("data:"):
+        validate_image(value)
+    elif not value.strip() or (":" in value and not Path(value).is_absolute()) or "\x00" in value:
+        raise ReportInputError("Use a local image path or embedded image data URI")
+    return value
+
+
+SVG_TAGS = {
+    "svg",
+    "g",
+    "path",
+    "rect",
+    "circle",
+    "ellipse",
+    "line",
+    "polyline",
+    "polygon",
+    "text",
+    "tspan",
+    "defs",
+    "use",
+    "symbol",
+    "clipPath",
+    "mask",
+    "linearGradient",
+    "radialGradient",
+    "stop",
+    "title",
+    "desc",
+}
+
+
+def validate_image(value: str) -> str:
+    """Validate raster content or a restricted static SVG document.
+
+    Args:
+        value: A supported base64 image data URI.
+
+    Returns:
+        The original data URI.
+
+    Raises:
+        ValueError: Content is empty, malformed, unsafe, or inconsistent with its MIME type.
+    """
+    prefix, separator, encoded = value.partition(",")
+    if not separator or prefix not in {f"data:{mime};base64" for mime in IMAGE_MIMES.values()}:
+        raise ReportInputError("Supply a supported base64 image data URI")
+    try:
+        raw = base64.b64decode(encoded, validate=True)
+    except ValueError as exc:
+        raise ReportInputError("Invalid base64 image data") from exc
+    if not raw:
+        raise ReportInputError("Empty image")
+    if prefix == "data:image/svg+xml;base64":
+        without_declaration = re.sub(rb"^\s*<\?xml\s[^?]*\?>", b"", raw)
+        if b"<?" in without_declaration or b"<!DOCTYPE" in raw.upper():
+            raise ReportInputError("SVG processing instructions and document types are prohibited")
+        try:
+            root = ElementTree.fromstring(raw)
+        except Exception as exc:
+            raise ReportInputError("Invalid or unsafe SVG") from exc
+        if root.tag.split("}")[-1] != "svg":
+            raise ReportInputError("Expected an SVG root")
+        for element in root.iter():
+            if element.tag.split("}")[-1] not in SVG_TAGS:
+                raise ReportInputError("SVG must contain static artwork only")
+            for name, attribute in element.attrib.items():
+                name = name.split("}")[-1].lower()
+                if name.startswith("on") or name in {"src", "base"}:
+                    raise ReportInputError("Active SVG attributes are prohibited")
+                if name == "href" and not re.fullmatch(r"#[A-Za-z_][\w.-]*", attribute):
+                    raise ReportInputError("SVG references must be local fragments")
+                # Disallow CSS escapes/imports and all URL functions, including encoded variants.
+                if "\\" in attribute or "@" in attribute or re.search(r"url\s*\(", attribute, re.I):
+                    raise ReportInputError("SVG URL/CSS resources are prohibited")
+    else:
+        from PIL import Image
+
+        try:
+            with Image.open(BytesIO(raw)) as image:
+                expected = prefix.removeprefix("data:").removesuffix(";base64").split("/")[-1]
+                if image.format.lower() != expected:
+                    raise ReportInputError("Image content does not match its MIME type")
+                image.verify()
+        except (OSError, SyntaxError, Image.DecompressionBombError) as exc:
+            raise ReportInputError("Invalid or unsupported raster image") from exc
+    return value
+
+
+def prepare_image(value: str, *, frame: int = 0, accepted_formats=None) -> str:
+    """Select an image frame and produce portable HTML image data.
+
+    Args:
+        value: A supported embedded image data URI.
+        frame: Nonnegative frame or TIFF page index, starting at zero.
+        accepted_formats: Optional allowed format names; None permits every
+            format supported by the package.
+
+    Returns:
+        A PNG, JPEG, or static SVG data URI. Other supported raster formats
+        are converted to a static PNG.
+
+    Raises:
+        ValueError: The image format or requested frame is not accepted.
+    """
+    validate_image(value)
+    prefix, encoded = value.split(",", 1)
+    image_format = next(
+        name for name, mime in IMAGE_MIMES.items() if prefix == f"data:{mime};base64"
+    )
+    if accepted_formats is not None and image_format not in accepted_formats:
+        raise ReportInputError("Image format is not in accepted_image_formats")
+    if image_format == "svg":
+        if frame != 0:
+            raise ReportInputError("SVG images have only one frame")
+        return value
+    from PIL import Image
+
+    with Image.open(BytesIO(base64.b64decode(encoded))) as image:
+        if frame >= getattr(image, "n_frames", 1):
+            raise ReportInputError("The selected image frame does not exist")
+        image.seek(frame)
+        image.load()
+        if image_format in {"png", "jpeg"} and frame == 0 and getattr(image, "n_frames", 1) == 1:
+            return value
+        output = BytesIO()
+        image.convert("RGBA").save(output, format="PNG")
+    return "data:image/png;base64," + base64.b64encode(output.getvalue()).decode()
+
+
+def embed_image(path: str | Path) -> str:
+    """Read a local artwork file and encode it as validated image data.
+
+    Args:
+        path: Path to a supported image file.
+
+    Returns:
+        A base64 image data URI.
+
+    Raises:
+        OSError: The file cannot be read.
+        ValueError: The extension or file contents are unsupported.
+    """
+    path = Path(path)
+    image_format = IMAGE_EXTENSIONS.get(path.suffix.lower())
+    if image_format is None:
+        raise ReportInputError("Unsupported image file extension")
+    mime = IMAGE_MIMES[image_format]
+    return validate_image(f"data:{mime};base64," + base64.b64encode(path.read_bytes()).decode())

smd_reports/cli.py

@@ -0,0 +1,167 @@
+"""Validate, normalize and render report JSON from the command line."""
+
+import argparse
+import json
+import logging
+import os
+import stat
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from pydantic import ValidationError
+
+from .errors import ReportInputError, ReportRenderError, format_validation_error
+from .loading import APPLICATIONS, ReportLoader
+from .rendering import ReportRenderer
+
+
+@contextmanager
+def _event_logging(enabled):
+    """Temporarily send package events to stderr when requested.
+
+    Args:
+        enabled: Whether the command was invoked with --verbose.
+
+    Yields:
+        Control to the command without changing application logging permanently.
+    """
+    logger = logging.getLogger("smd_reports")
+    if not enabled:
+        yield
+        return
+    level, propagate = logger.level, logger.propagate
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(levelname)s %(name)s: %(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
+    try:
+        yield
+    finally:
+        logger.removeHandler(handler)
+        handler.close()
+        logger.setLevel(level)
+        logger.propagate = propagate
+
+
+def _write_output(path: Path, output: str | bytes) -> None:
+    """Replace output only after a complete write succeeds.
+
+    Args:
+        path: Destination whose parent directory must exist.
+        output: Complete HTML, PDF, JSON or JSON Schema output.
+
+    Raises:
+        OSError: The destination cannot be written or replaced.
+    """
+    path = path.resolve()
+    with TemporaryDirectory(prefix=".smd-reports-", dir=path.parent) as directory:
+        temporary = Path(directory) / "output"
+        if isinstance(output, bytes):
+            temporary.write_bytes(output)
+        else:
+            temporary.write_text(output, encoding="utf-8")
+        if path.exists():
+            temporary.chmod(stat.S_IMODE(path.stat().st_mode))
+        os.replace(temporary, path)
+    logging.getLogger(__name__).info("Report output written")
+
+
+def _run(args) -> int:
+    """Execute a parsed command and report recoverable failures.
+
+    Args:
+        args: Parsed command-line options.
+
+    Returns:
+        Zero on success, two for input/setup errors, or one for rendering failures.
+    """
+    loader = ReportLoader()
+    operation = "read the input JSON file"
+    try:
+        if args.command == "schema":
+            output = json.dumps(loader.schema(args.application), ensure_ascii=False, indent=2)
+        else:
+            if hasattr(args, "output") and (
+                args.output.resolve() == args.input.resolve()
+                or (
+                    args.output.exists()
+                    and args.input.exists()
+                    and args.output.samefile(args.input)
+                )
+            ):
+                raise ReportInputError("Output must not overwrite input JSON; choose another file.")
+            report = loader.load(args.input)
+            if args.command == "validate":
+                print(f"Valid {report.application} report ({report.language})")
+                return 0
+            if args.command == "normalize":
+                output = report.model_dump_json(indent=2)
+            else:
+                renderer = ReportRenderer()
+                output = (
+                    renderer.render_html(report)
+                    if args.format == "html"
+                    else renderer.render_pdf(report)
+                )
+        operation = "write the output file"
+        _write_output(args.output, output)
+        print(f"Written {args.output}")
+        return 0
+    except ValidationError as exc:
+        message = format_validation_error(exc)
+    except json.JSONDecodeError as exc:
+        message = f"Invalid JSON at line {exc.lineno}, column {exc.colno}; check the JSON syntax."
+    except UnicodeError:
+        message = "Cannot decode input JSON; save the file with UTF-8 encoding."
+    except ReportInputError as exc:
+        message = str(exc)
+    except ReportRenderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    except FileNotFoundError:
+        message = f"Cannot {operation}: file or parent directory not found."
+    except PermissionError:
+        message = f"Cannot {operation}: permission denied. Check file and directory permissions."
+    except IsADirectoryError:
+        message = f"Cannot {operation}: the selected path is a directory; choose a file."
+    except OSError:
+        message = f"Cannot {operation}: filesystem error. Check the location and available space."
+    except Exception:
+        logging.getLogger(__name__).error("Report command failed unexpectedly")
+        print(
+            "Report command failed unexpectedly; check the installation and report format.",
+            file=sys.stderr,
+        )
+        return 1
+    print(message, file=sys.stderr)
+    return 2
+
+
+def main(argv=None) -> int:
+    """Run a JSON validation, normalization, schema, or rendering command.
+
+    Args:
+        argv: Command arguments, excluding the executable name. None reads sys.argv.
+
+    Returns:
+        Zero on success, two for input/setup errors, or one for rendering failures.
+    """
+    parser = argparse.ArgumentParser(prog="smd-reports", description=__doc__)
+    parser.add_argument("--verbose", action="store_true", help="Log main events to stderr")
+    commands = parser.add_subparsers(dest="command", required=True)
+    schema = commands.add_parser("schema", help="Export a report JSON Schema")
+    schema.add_argument("--application", choices=APPLICATIONS)
+    schema.add_argument("--output", type=Path, required=True)
+    for name in ("validate", "normalize", "render"):
+        command = commands.add_parser(name)
+        command.add_argument("input", type=Path)
+        if name != "validate":
+            command.add_argument("--output", type=Path, required=True)
+        if name == "render":
+            command.add_argument("--format", choices=("html", "pdf"), required=True)
+    args = parser.parse_args(argv)
+    with _event_logging(args.verbose):
+        return _run(args)