auto-html-report 0.1.0__py3-none-any.whl

auto_html_report/__init__.py

@@ -0,0 +1,141 @@
+"""auto_html_report -- dynamic, self-contained HTML report generation.
+
+This module is the public surface: everything a block author, a report factory or a job script should
+import. It grew in stages -- the author-facing names in stage 3, the report model and entry point in
+stages 5 and 6, the configuration factories in stage 7, the event store and discovery job in stage 8,
+the processing job and exit codes in stage 9, and the report family and examples in stage 10.
+Stage 11 added the optional PostgreSQL store and S3 writer, which import their drivers only when
+constructed. ``auto_html_report.testing`` is public too, but is not re-exported here, because production
+code has no use for it.
+
+Nothing here imports matplotlib or pyplot eagerly: a report built only from HTML tables never pays for
+them, and a test in ``tests/unit/test_rendering_figures.py`` pins that in a subprocess.
+"""
+
+from __future__ import annotations
+
+from auto_html_report._version import get_version
+from auto_html_report.application.collect_blocks import collect_blocks
+from auto_html_report.application.context import DiscoveryContext, RenderContext, ReportContext
+from auto_html_report.application.discovery import (
+    Discoverer,
+    DiscoveryOutcome,
+    DiscoveryRun,
+    run_discovery,
+)
+from auto_html_report.application.ports import (
+    Clock,
+    EventStore,
+    FailureRecord,
+    HttpClient,
+    OutputWriter,
+    SaveResult,
+)
+from auto_html_report.domain.block import Block, BlockOutcome, BlockStatus
+from auto_html_report.domain.errors import (
+    AutoHtmlReportError,
+    BlockError,
+    ConfigurationError,
+    OutputError,
+    PermanentBlockError,
+    StoreError,
+    TransientBlockError,
+)
+from auto_html_report.domain.event import Event, EventStatus
+from auto_html_report.domain.report import (
+    OutputLocation,
+    Report,
+    ReportDefinition,
+    ReportResult,
+    ReportRow,
+)
+from auto_html_report.exit_codes import ExitCode, exit_code_for
+from auto_html_report.generate import generate_report, report_filename
+from auto_html_report.infrastructure.clock import SystemClock
+from auto_html_report.infrastructure.factories import (
+    build_output_writer,
+    new_discovery_context,
+    new_report_context,
+)
+from auto_html_report.infrastructure.logging_setup import configure_logging
+from auto_html_report.infrastructure.settings import Settings, load_settings
+from auto_html_report.infrastructure.stores.postgres_store import PostgresEventStore
+from auto_html_report.infrastructure.stores.sqlite_store import SqliteEventStore
+from auto_html_report.infrastructure.writers.local_writer import LocalDirectoryWriter
+from auto_html_report.infrastructure.writers.s3_writer import S3Writer
+from auto_html_report.processing import (
+    EventProcessingOutcome,
+    ProcessingRun,
+    run_processing,
+)
+from auto_html_report.registry import register_report
+from auto_html_report.rendering.escaping import escape, html_table
+from auto_html_report.rendering.figures import figure_lock, figure_to_data_uri
+from auto_html_report.rendering.shell import render_report
+
+# Deliberately flat and alphabetical. The names fall into groups -- writing a block, building a report,
+# producing the document, configuring it, and classifying a failure -- but the ordering carries no
+# meaning, because an unsorted __all__ is a lint error in this project.
+#: The installed version, computed once at import from the distribution metadata. ``get_version()``
+#: remains the source (``docs/08-packaging.md`` §7); this is the attribute a consumer reaches for first.
+__version__ = get_version()
+
+
+__all__ = [
+    "AutoHtmlReportError",
+    "Block",
+    "BlockError",
+    "BlockOutcome",
+    "BlockStatus",
+    "Clock",
+    "ConfigurationError",
+    "Discoverer",
+    "DiscoveryContext",
+    "DiscoveryOutcome",
+    "DiscoveryRun",
+    "Event",
+    "EventProcessingOutcome",
+    "EventStatus",
+    "EventStore",
+    "ExitCode",
+    "FailureRecord",
+    "HttpClient",
+    "LocalDirectoryWriter",
+    "OutputError",
+    "OutputLocation",
+    "OutputWriter",
+    "PermanentBlockError",
+    "PostgresEventStore",
+    "ProcessingRun",
+    "RenderContext",
+    "Report",
+    "ReportContext",
+    "ReportDefinition",
+    "ReportResult",
+    "ReportRow",
+    "S3Writer",
+    "SaveResult",
+    "Settings",
+    "SqliteEventStore",
+    "StoreError",
+    "SystemClock",
+    "TransientBlockError",
+    "__version__",
+    "build_output_writer",
+    "collect_blocks",
+    "configure_logging",
+    "escape",
+    "exit_code_for",
+    "figure_lock",
+    "figure_to_data_uri",
+    "generate_report",
+    "html_table",
+    "load_settings",
+    "new_discovery_context",
+    "new_report_context",
+    "register_report",
+    "render_report",
+    "report_filename",
+    "run_discovery",
+    "run_processing",
+]

auto_html_report/_naming.py

@@ -0,0 +1,35 @@
+"""Slug generation, shared by the things that need a filesystem- and attribute-safe token.
+
+Two callers want this and they must not disagree: the row's ``data-block`` attribute
+(``rendering/cells.py``) and the report filename (stage 6, ``docs/06-output-html.md`` §2). One
+implementation, so a title that slugs cleanly for a filename slugs identically in the document.
+"""
+
+from __future__ import annotations
+
+import re
+
+#: Matches runs of anything that is not a lowercase letter or digit.
+_NON_SLUG_CHARACTERS = re.compile(r"[^a-z0-9]+")
+
+#: The documented cap, chosen so that a filename built from a title, an event id and a timestamp
+#: still fits comfortably inside filesystem and S3 key limits.
+DEFAULT_MAX_LENGTH = 60
+
+
+def slug(text: str, *, max_length: int = DEFAULT_MAX_LENGTH, fallback: str = "") -> str:
+    """Return ``text`` as a lowercase, hyphen-separated token of at most ``max_length`` characters.
+
+    ``fallback`` is returned when nothing survives -- a title consisting only of emoji or punctuation
+    slugs to the empty string, and every caller needs *something* rather than a silently blank
+    identifier. Callers pass their own fallback (``"block"``, ``"report"``) rather than each inventing
+    a check.
+    """
+    if max_length < 1:
+        raise ValueError(f"max_length must be at least 1, got {max_length}")
+
+    slugified = _NON_SLUG_CHARACTERS.sub("-", text.lower()).strip("-")
+    if len(slugified) > max_length:
+        # Truncate, then strip again: cutting mid-word can leave a trailing hyphen.
+        slugified = slugified[:max_length].rstrip("-")
+    return slugified or fallback

auto_html_report/_version.py

@@ -0,0 +1,29 @@
+"""Resolves the installed package version.
+
+``pyproject.toml`` is the single source of truth. Nothing here stores a copy of it, because a second
+copy is a copy that drifts -- the same reasoning that removed ``requirements.txt`` (ADR-0021).
+
+Resolution is at runtime, and the not-installed path is real rather than hypothetical: running from
+a source tree with the package not installed raises ``PackageNotFoundError``, which this module
+converts into a placeholder rather than a guess. See ``docs/08-packaging.md`` §7 and ADR-0023.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+#: Distribution name, matching ``[project] name`` in pyproject.toml. Both the hyphen and underscore
+#: spellings resolve, so this constant is not a portability trap whichever one a reader expects.
+_DISTRIBUTION_NAME = "auto-html-report"
+
+#: Reported when the package is not installed. Deliberately not a plausible release number: a report
+#: footer should never claim a version that was never built.
+UNKNOWN_VERSION = "0+unknown"
+
+
+def get_version() -> str:
+    """Return the installed distribution's version, or :data:`UNKNOWN_VERSION` if not installed."""
+    try:
+        return version(_DISTRIBUTION_NAME)
+    except PackageNotFoundError:
+        return UNKNOWN_VERSION

auto_html_report/application/__init__.py

@@ -0,0 +1 @@
+"""The application layer: use cases that compose domain types and injected ports."""

auto_html_report/application/collect_blocks.py

@@ -0,0 +1,161 @@
+"""Concurrent collection: every block in a report, assembled into ordered rows.
+
+**Collection produces data and outcomes; rendering produces HTML.** A failed block's row carries an
+empty ``html`` and a populated ``outcome``, and the error cell is built by the renderer from that
+outcome. That is not an accident of layering (application/ may not import rendering/) — it is the right
+split: this module knows *what happened*, the renderer knows *how it looks*, and the error detail level
+is a presentation setting.
+
+**The execution rules are not here.** Timeout accounting, the retry loop, backoff and the hang guard
+live in ``application/execution.py``, because discoverers obey the same rules (``docs/05`` §1) and two
+copies of that logic would drift. This module supplies the block-specific parts: which callables to
+run, the duplicate-name check, and the mapping from an execution result to a :class:`ReportRow`. The
+one thing it keeps in the worker is the success log line, so ``block.finish`` is emitted when the block
+finishes rather than when the slowest sibling does.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from datetime import datetime
+from typing import Any
+
+from auto_html_report.application.context import RenderContext, ReportContext
+from auto_html_report.application.execution import (
+    BLOCK_EXECUTION,
+    ExecutionResult,
+    ExecutionStatus,
+    Task,
+    execute_tasks,
+)
+from auto_html_report.domain.block import Block, BlockOutcome, BlockStatus
+from auto_html_report.domain.errors import ConfigurationError
+from auto_html_report.domain.report import ReportRow
+
+#: Execution results speak about tasks; a report speaks about blocks. One mapping, so the two cannot
+#: drift and neither module has to know the other's enum.
+_STATUS: dict[ExecutionStatus, BlockStatus] = {
+    ExecutionStatus.OK: BlockStatus.OK,
+    ExecutionStatus.FAILED: BlockStatus.FAILED,
+    ExecutionStatus.TIMED_OUT: BlockStatus.TIMED_OUT,
+}
+
+
+def collect_blocks(
+    blocks: Sequence[Block[Any]],
+    *,
+    context: ReportContext,
+    report_title: str = "",
+    generated_at: datetime | None = None,
+) -> tuple[ReportRow, ...]:
+    """Collect and render every block concurrently; return rows in argument order.
+
+    Never raises for a block-level failure: such a row carries a ``FAILED`` or ``TIMED_OUT`` outcome and
+    an empty ``html``, which the renderer turns into an error cell. Raises :class:`ConfigurationError`
+    for an invalid block set, because that is a programming error rather than a data condition.
+
+    ``report_title`` is offered to blocks through their ``RenderContext``. It defaults to empty because
+    collection is also usable outside a report definition, but a report should always pass it.
+
+    ``generated_at`` is the instant the report is stamped with, and it reaches every block's
+    ``RenderContext``. Pass the same value the :class:`Report` will carry so that a block rendering it
+    agrees with the document header; it defaults to the clock's current reading for standalone use.
+    """
+    _validate(blocks)
+
+    render_context = RenderContext(
+        generated_at=generated_at if generated_at is not None else context.clock.now(),
+        report_title=report_title,
+    )
+    results = execute_tasks(
+        [_task(block, context, render_context) for block in blocks],
+        settings=context.settings,
+        clock=context.clock,
+        logger=context.logger,
+        run_id=context.run.run_id,
+        vocabulary=BLOCK_EXECUTION,
+        on_success=_finish_logger(context),
+    )
+    return tuple(_row(block, result) for block, result in zip(blocks, results, strict=True))
+
+
+def _task(
+    block: Block[Any], context: ReportContext, render_context: RenderContext
+) -> Task[Any, str]:
+    """One block as a task: ``collect()`` per attempt, ``render()`` once on success.
+
+    Named closures rather than lambdas: mypy cannot infer the callable types through ``Task``'s two type
+    parameters, and a function with annotations is clearer than a lambda with a cast. Each call creates
+    its own closures over ``block``, so the late-binding trap a comprehension would set does not exist.
+    """
+
+    def attempt(_attempt_number: int) -> Any:
+        return block.collect(context)
+
+    def finalise(data: Any, _attempt_number: int) -> str:
+        return block.render(data, render_context)
+
+    return Task(
+        name=block.name,
+        attempt=attempt,
+        finalise=finalise,
+        timeout_seconds=block.timeout_seconds,
+        max_retries=block.max_retries,
+    )
+
+
+def _finish_logger(
+    context: ReportContext,
+) -> Callable[[str, ExecutionResult[Any]], None]:
+    """The success log line, emitted from the worker the moment a block finishes."""
+
+    def log_finish(name: str, result: ExecutionResult[Any]) -> None:
+        context.logger.info(
+            "block.finish",
+            extra={
+                "run_id": context.run.run_id,
+                "block": name,
+                "status": BlockStatus.OK.value,
+                "duration_ms": round(result.duration_seconds * 1000, 1),
+                "attempts": result.attempts,
+            },
+        )
+
+    return log_finish
+
+
+def _row(block: Block[Any], result: ExecutionResult[Any]) -> ReportRow:
+    """One execution result as a row. A failed block's cell is the renderer's job."""
+    outcome = BlockOutcome(
+        name=block.name,
+        status=_STATUS[result.status],
+        duration_seconds=result.duration_seconds,
+        attempts=result.attempts,
+        error_type=result.error_type,
+        error_message=result.error_message,
+    )
+    html = result.value if result.value is not None else ""
+    return ReportRow(item=block.name, html=html, outcome=outcome)
+
+
+def _validate(blocks: Sequence[Block[Any]]) -> None:
+    """Reject the block sets that cannot produce a sensible report.
+
+    The per-block overrides (``timeout_seconds``, ``max_retries``) and the settings bounds are checked
+    by :func:`~auto_html_report.application.execution.execute_tasks`, which is where those values are used.
+    """
+    if not blocks:
+        raise ConfigurationError("a report must contain at least one block")
+
+    seen: set[str] = set()
+    duplicates: set[str] = set()
+    for block in blocks:
+        if block.name in seen:
+            duplicates.add(block.name)
+        seen.add(block.name)
+
+    if duplicates:
+        raise ConfigurationError(
+            f"duplicate block names: {sorted(duplicates)}. Names fill the Item column, so a reader "
+            "cannot tell duplicate rows apart; pass name=... to distinguish repeated blocks."
+        )

auto_html_report/application/context.py

@@ -0,0 +1,65 @@
+"""The frozen contexts handed to blocks, discoverers and jobs.
+
+These live here rather than in ``domain/`` because they bundle injected dependencies -- ``Settings``
+from the infrastructure layer, and the ``HttpClient`` and ``Clock`` ports. ``domain/block.py`` names
+two of them in its method signatures, importing them under ``TYPE_CHECKING`` only, so the domain
+layer keeps no *runtime* dependency on this module. See ``docs/01-overview.md`` §4 rule 1 and
+``docs/03-report-api.md`` §5.
+
+All four are frozen, and therefore safe to share with every worker thread in a report. That is a
+contract, not an accident: anything mutable added here would need to be thread-safe and documented
+as such. The v1 answer is "don't" -- use per-instance state on the block, which the framework
+guarantees is used by one thread at a time.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+
+from auto_html_report.application.ports import Clock, HttpClient
+from auto_html_report.infrastructure.settings import Settings
+
+
+@dataclass(frozen=True, slots=True)
+class RunMetadata:
+    """Identity of one job run, generated once per context."""
+
+    run_id: str
+    started_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class ReportContext:
+    """Everything a block's ``collect()`` is allowed to depend on."""
+
+    settings: Settings
+    http: HttpClient
+    logger: logging.Logger
+    clock: Clock
+    run: RunMetadata
+
+
+@dataclass(frozen=True, slots=True)
+class RenderContext:
+    """What ``render()`` is allowed to touch.
+
+    Slimmer than :class:`ReportContext` on purpose: no HTTP, no store, and **no logger**, because
+    ``render()`` is pure and logging is a side effect. A block that needs to log does it in
+    ``collect()``.
+    """
+
+    generated_at: datetime
+    report_title: str
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveryContext:
+    """Everything a discoverer's ``discover()`` is allowed to depend on."""
+
+    settings: Settings
+    http: HttpClient
+    logger: logging.Logger
+    clock: Clock
+    run: RunMetadata