labharness 0.1.0__py3-none-any.whl

labharness/__init__.py

@@ -0,0 +1,19 @@
+"""LabHarness: a local-first Data-to-Paper harness.
+
+The package is organised as a thin core plus independent modules:
+
+- ``labharness.core``: module contract, registry, manifest and errors.
+- ``labharness.style``: the shared style (one typeface for the whole document).
+- ``labharness.watch``: the event-driven orchestrator.
+- ``labharness.cli``: the command-line interface, a thin layer over the above.
+- ``labharness.modules``: one subpackage per domain, each behind an optional extra.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("labharness")
+except PackageNotFoundError:  # running from a source checkout that is not installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

labharness/cli/__init__.py

@@ -0,0 +1,8 @@
+"""Command-line interface: a thin layer over the core, the watcher and the modules.
+
+No figure logic lives here, so the same functions can be driven from anywhere else.
+"""
+
+from labharness.cli.app import app, main
+
+__all__ = ["app", "main"]

labharness/cli/app.py

@@ -0,0 +1,207 @@
+"""The LabHarness command line.
+
+A thin layer: every command reads its workspace, calls into the core or the watcher, and
+prints the result. No figure logic lives here, so a graphical interface can reuse the same
+functions later.
+"""
+
+import time
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from labharness import __version__
+from labharness.core.errors import LabHarnessError, MissingExtraError
+from labharness.core.manifest import Figure, Workspace, load_workspace
+from labharness.core.workspace import create_workspace
+from labharness.doctor import everything_required_passes, run_checks
+from labharness.modules.chem import resolve_name
+from labharness.watch.runner import BuildResult
+from labharness.watch.runner import build as run_build
+from labharness.watch.session import DEFAULT_DEBOUNCE_MS, Cycle, watch
+from labharness.watch.viewer import open_pdf
+
+EXIT_ERROR = 1
+EXIT_MISSING_DEPENDENCY = 3
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    invoke_without_command=True,
+    help="Turn raw lab data into publication-ready LaTeX figures, and keep the PDF in sync.",
+)
+
+
+@app.callback()
+def _main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool, typer.Option("--version", help="Print the LabHarness version and exit.")
+    ] = False,
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+@app.command()
+def init(
+    path: Annotated[Path, typer.Argument(help="Where to create the workspace.")] = Path("."),
+    journal: Annotated[str, typer.Option(help="Journal template to use.")] = "acs",
+    force: Annotated[bool, typer.Option(help="Write into a folder that is not empty.")] = False,
+) -> None:
+    """Create a workspace: manuscript, data, scripts, figures and manifest."""
+    with _reporting_errors():
+        target = create_workspace(path, journal=journal, force=force)
+
+    typer.secho(f"Workspace created in {target}", fg=typer.colors.GREEN)
+    typer.echo("Next: add a figure with 'labharness add', then run 'labharness watch'.")
+
+
+@app.command()
+def build(
+    only: Annotated[str | None, typer.Option(help="Rebuild a single figure, by name.")] = None,
+    no_latex: Annotated[bool, typer.Option(help="Rebuild figures without compiling.")] = False,
+) -> None:
+    """Rebuild the figures and compile the document once."""
+    with _reporting_errors():
+        workspace = load_workspace()
+        figures = _selected(workspace, only)
+        result = _build(workspace, figures, compile_latex=not no_latex)
+
+    _print_result(result)
+    if not result.ok:
+        raise typer.Exit(EXIT_ERROR)
+
+
+@app.command("watch")
+def watch_command(
+    no_open: Annotated[bool, typer.Option("--no-open", help="Do not open the PDF viewer.")] = False,
+    debounce: Annotated[
+        int, typer.Option(help="Milliseconds used to group rapid saves.")
+    ] = DEFAULT_DEBOUNCE_MS,
+) -> None:
+    """Watch the workspace and rebuild on every save."""
+    with _reporting_errors():
+        workspace = load_workspace()
+        typer.secho(f"Watching {workspace.root}", fg=typer.colors.GREEN)
+
+        first = _build(workspace, list(workspace.figures), compile_latex=True)
+        _print_result(first)
+
+        pdf = first.compilation.pdf if first.compilation is not None else None
+        if not no_open and pdf is not None and not open_pdf(pdf):
+            typer.secho(
+                "No PDF viewer found. Install SumatraPDF (Windows) or Skim (macOS); "
+                "Adobe Acrobat locks the file and stops the rebuild.",
+                fg=typer.colors.YELLOW,
+            )
+
+        typer.echo("Waiting for changes. Press Ctrl+C to stop.")
+        try:
+            watch(workspace, on_cycle=_print_cycle, debounce_ms=debounce)
+        except KeyboardInterrupt:  # pragma: no cover - interactive
+            typer.echo("Stopped.")
+
+
+@app.command()
+def resolve(
+    name: Annotated[str, typer.Argument(help="Systematic IUPAC name, in quotes.")],
+    output: Annotated[Path, typer.Option("--output", "-o", help="Where to write the SMILES.")],
+) -> None:
+    """Turn an IUPAC name into a SMILES file, offline, with OPSIN."""
+    with _reporting_errors():
+        smiles = resolve_name(name, output=output)
+
+    typer.secho(f"{smiles}", fg=typer.colors.GREEN)
+    typer.echo(f"written to {output}. Check it before using it in a figure.")
+
+
+@app.command()
+def doctor() -> None:
+    """Check that this machine has everything LabHarness needs."""
+    checks = run_checks()
+    for check in checks:
+        if check.ok:
+            mark, colour = "OK  ", typer.colors.GREEN
+        elif check.required:
+            mark, colour = "FAIL", typer.colors.RED
+        else:
+            mark, colour = "WARN", typer.colors.YELLOW
+        typer.secho(f"{mark} {check.name}: {check.detail}", fg=colour)
+        if check.hint and not check.ok:
+            typer.echo(f"       {check.hint}")
+
+    if not everything_required_passes(checks):
+        raise typer.Exit(EXIT_MISSING_DEPENDENCY)
+
+
+def _selected(workspace: Workspace, only: str | None) -> list[Figure] | None:
+    if only is None:
+        return None
+    chosen = [figure for figure in workspace.figures if figure.name == only]
+    if not chosen:
+        known = ", ".join(figure.name for figure in workspace.figures) or "none"
+        raise LabHarnessError(f"no figure called '{only}' in the manifest. Known figures: {known}")
+    return chosen
+
+
+def _build(workspace: Workspace, figures: list[Figure] | None, compile_latex: bool) -> BuildResult:
+    return run_build(workspace, figures=figures, compile_latex=compile_latex)
+
+
+def _print_result(result: BuildResult) -> None:
+    for figure in result.figures:
+        if figure.ok:
+            typer.echo(f"  {figure.figure.output}  {_ms(figure.seconds)}")
+        else:
+            typer.secho(f"  {figure.figure.output}  failed", fg=typer.colors.RED)
+            typer.echo(f"      {figure.error}")
+
+    compilation = result.compilation
+    if compilation is not None and not compilation.ok:
+        typer.secho("  LaTeX failed", fg=typer.colors.RED)
+        for line in compilation.errors[:5]:
+            typer.echo(f"      {line}")
+
+    typer.echo(
+        f"  figures {_ms(result.figures_seconds)}  |  latex {_ms(result.latex_seconds)}  |  "
+        f"total {_ms(result.total_seconds)}"
+    )
+
+
+def _print_cycle(cycle: Cycle) -> None:
+    changed = ", ".join(path.name for path in cycle.changed)
+    typer.echo(f"\n{time.strftime('%H:%M:%S')}  {changed}")
+    _print_result(cycle.result)
+
+
+def _ms(seconds: float) -> str:
+    return f"{seconds * 1000:.0f} ms"
+
+
+class _reporting_errors:
+    """Turn LabHarness errors into a clear message and the right exit code."""
+
+    def __enter__(self) -> None:
+        return None
+
+    def __exit__(self, kind: object, error: BaseException | None, traceback: object) -> None:
+        if isinstance(error, MissingExtraError):
+            typer.secho(str(error), fg=typer.colors.RED)
+            raise typer.Exit(EXIT_MISSING_DEPENDENCY) from None
+        if isinstance(error, LabHarnessError):
+            typer.secho(str(error), fg=typer.colors.RED)
+            raise typer.Exit(EXIT_ERROR) from None
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

labharness/core/__init__.py

@@ -0,0 +1,21 @@
+"""Core of LabHarness: module contract, manifest, workspace and errors.
+
+Modules may only depend on the public API exported here and in ``labharness.style``.
+That rule is what makes ``labharness eject`` possible later on.
+"""
+
+from labharness.core.errors import LabHarnessError, MissingExtraError
+from labharness.core.extras import require
+from labharness.core.manifest import Figure, Workspace, find_workspace, load_workspace
+from labharness.core.workspace import create_workspace
+
+__all__ = [
+    "Figure",
+    "LabHarnessError",
+    "MissingExtraError",
+    "Workspace",
+    "create_workspace",
+    "find_workspace",
+    "load_workspace",
+    "require",
+]

labharness/core/atomic.py

@@ -0,0 +1,28 @@
+"""Writing outputs atomically.
+
+Every module writes this way: the watcher recompiles as soon as a figure changes, and LaTeX
+must never open a PDF that is still being written.
+"""
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def atomic_output(output: Path) -> Iterator[Path]:
+    """Yield a temporary path to write to, then move it into place.
+
+    If the writer raises, the temporary file is removed and the previous output is left
+    untouched, so a broken script never destroys the figure that was working.
+    """
+    output = Path(output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary = output.with_name(f".{output.name}.tmp")
+
+    try:
+        yield temporary
+        os.replace(temporary, output)
+    finally:
+        temporary.unlink(missing_ok=True)

labharness/core/errors.py

@@ -0,0 +1,17 @@
+"""Exception hierarchy shared by every part of LabHarness."""
+
+
+class LabHarnessError(Exception):
+    """Base class for every error raised by LabHarness."""
+
+
+class MissingExtraError(LabHarnessError, ImportError):
+    """A feature needs an optional extra that is not installed."""
+
+    def __init__(self, extra: str, package: str) -> None:
+        super().__init__(
+            f"This feature needs the '{extra}' extra (missing package: {package}). "
+            f'Install it with: uv sync --extra {extra}   or   pip install "labharness[{extra}]"'
+        )
+        self.extra = extra
+        self.package = package

labharness/core/extras.py

@@ -0,0 +1,18 @@
+"""Lazy imports of optional dependencies, with an actionable error when they are missing."""
+
+import importlib
+from types import ModuleType
+
+from labharness.core.errors import MissingExtraError
+
+
+def require(package: str, extra: str) -> ModuleType:
+    """Import ``package`` or explain which extra installs it.
+
+    Modules call this inside their functions, never at import time, so that
+    ``import labharness`` works with no extras installed.
+    """
+    try:
+        return importlib.import_module(package)
+    except ImportError as exc:
+        raise MissingExtraError(extra, package) from exc

labharness/core/latex.py

@@ -0,0 +1,107 @@
+"""Running latexmk, and turning its output into something a person can read.
+
+Shared by the watcher, which compiles the document, and by the diagrams module, which
+compiles each figure on its own.
+"""
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from labharness.core.errors import LabHarnessError
+
+
+@dataclass(frozen=True)
+class LatexResult:
+    ok: bool
+    pdf: Path | None
+    errors: tuple[str, ...]
+    log: str
+
+    @property
+    def summary(self) -> str:
+        return "\n".join(self.errors) if self.errors else "LaTeX failed, see the log"
+
+
+def run_latexmk(document: Path) -> LatexResult:
+    """Compile ``document`` once. Incremental: latexmk only redoes what changed.
+
+    No -halt-on-error: latexmk needs its extra passes for bibliographies and
+    cross-references, and nonstopmode already stops it from waiting for input.
+    """
+    latexmk = shutil.which("latexmk")
+    if latexmk is None:
+        raise LabHarnessError(
+            "cannot find 'latexmk'. Install a LaTeX distribution, and on Windows with MiKTeX "
+            "install Perl as well (for example Strawberry Perl)."
+        )
+
+    result = subprocess.run(
+        [latexmk, "-pdf", "-interaction=nonstopmode", document.name],
+        cwd=document.parent,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    output = result.stdout + result.stderr
+    pdf = document.with_suffix(".pdf")
+    ok = result.returncode == 0 and pdf.is_file()
+
+    errors = summarise_errors(output)
+    if not ok and not errors:
+        # latexmk summarises instead of repeating what LaTeX said, so the real message is
+        # in the log. Without this the terminal says "LaTeX failed" and nothing else.
+        errors = summarise_errors(read_log(document))
+
+    return LatexResult(ok=ok, pdf=pdf if pdf.is_file() else None, errors=errors, log=output)
+
+
+def run_pdflatex(document: Path, passes: int = 2) -> LatexResult:
+    """Compile with pdflatex directly, for when only a figure changed.
+
+    latexmk is the right tool when the bibliography or the cross-references may have moved,
+    but it costs about a second of its own before running anything, and then makes two or
+    three passes. Redrawing a figure needs one pass, and LaTeX itself says so when it needs
+    another, so the quick path listens for that instead of assuming.
+    """
+    pdflatex = shutil.which("pdflatex")
+    if pdflatex is None:
+        raise LabHarnessError(
+            "cannot find 'pdflatex'. Install a LaTeX distribution (MiKTeX or TeX Live)."
+        )
+
+    output = ""
+    for attempt in range(passes):
+        result = subprocess.run(
+            [pdflatex, "-interaction=nonstopmode", document.name],
+            cwd=document.parent,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        output = result.stdout + result.stderr
+        if "Rerun" not in output or attempt == passes - 1:
+            break
+
+    pdf = document.with_suffix(".pdf")
+    ok = result.returncode == 0 and pdf.is_file()
+    errors = summarise_errors(output) or (summarise_errors(read_log(document)) if not ok else ())
+    return LatexResult(ok=ok, pdf=pdf if pdf.is_file() else None, errors=errors, log=output)
+
+
+def read_log(document: Path) -> str:
+    log = document.with_suffix(".log")
+    if not log.is_file():
+        return ""
+    return log.read_text(encoding="utf-8", errors="replace")
+
+
+def summarise_errors(output: str) -> tuple[str, ...]:
+    """The lines a person needs: LaTeX errors and the line they happened on."""
+    interesting = [
+        line.rstrip()
+        for line in output.splitlines()
+        if line.startswith("!") or line.startswith("l.") or "not found" in line
+    ]
+    return tuple(dict.fromkeys(interesting))

labharness/core/manifest.py

@@ -0,0 +1,119 @@
+"""The workspace manifest: which script builds which figure, from which data.
+
+``labharness.toml`` is plain text the researcher can read and edit. It is also what lets the
+watcher rebuild only what changed, and what a future graphical interface will read.
+"""
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from labharness.core.errors import LabHarnessError
+
+MANIFEST_NAME = "labharness.toml"
+DOCUMENT_NAME = "paper.tex"
+STYLE_NAME = "labharness-style.tex"
+
+
+@dataclass(frozen=True)
+class Figure:
+    """One generated figure, with the script that builds it and the files it depends on."""
+
+    output: Path
+    script: Path
+    inputs: tuple[Path, ...]
+
+    @property
+    def name(self) -> str:
+        return self.output.stem
+
+    def depends_on(self, path: Path) -> bool:
+        return path == self.script or path in self.inputs
+
+
+@dataclass(frozen=True)
+class Workspace:
+    """A folder with a manifest in it."""
+
+    root: Path
+    journal: str
+    figures: tuple[Figure, ...]
+
+    @property
+    def document(self) -> Path:
+        return self.root / DOCUMENT_NAME
+
+    @property
+    def watched_paths(self) -> list[Path]:
+        return [self.root / name for name in ("data", "scripts", DOCUMENT_NAME, MANIFEST_NAME)]
+
+    def figures_affected_by(self, path: Path) -> list[Figure]:
+        """Figures to rebuild after ``path`` changed.
+
+        A change to the manifest or the style rebuilds everything, because either can change
+        how every figure looks.
+        """
+        relative = _relative_to(path, self.root)
+        if relative is None:
+            return []
+        if relative.name in (MANIFEST_NAME, STYLE_NAME):
+            return list(self.figures)
+        return [figure for figure in self.figures if figure.depends_on(relative)]
+
+
+def find_workspace(start: Path | None = None) -> Path:
+    """Walk up from ``start`` looking for a manifest, the way git looks for ``.git``."""
+    current = (start or Path.cwd()).resolve()
+    for folder in [current, *current.parents]:
+        if (folder / MANIFEST_NAME).is_file():
+            return folder
+    raise LabHarnessError(
+        f"no '{MANIFEST_NAME}' found here or in any parent folder. "
+        "Run this inside a workspace, or create one with: labharness init"
+    )
+
+
+def load_workspace(root: Path | None = None) -> Workspace:
+    """Read the manifest of a workspace."""
+    root = find_workspace(root) if root is None or not (root / MANIFEST_NAME).is_file() else root
+    manifest = root / MANIFEST_NAME
+
+    try:
+        data = tomllib.loads(manifest.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as error:
+        raise LabHarnessError(f"{manifest} is not valid TOML: {error}") from error
+
+    figures = tuple(_figure(entry, manifest) for entry in data.get("figure", []))
+    _reject_duplicates(figures, manifest)
+    return Workspace(root=root, journal=str(data.get("journal", "acs")), figures=figures)
+
+
+def _figure(entry: dict[str, object], manifest: Path) -> Figure:
+    for key in ("output", "script"):
+        if key not in entry:
+            raise LabHarnessError(f"{manifest}: a [[figure]] entry has no '{key}'")
+
+    inputs = entry.get("inputs", [])
+    if not isinstance(inputs, list):
+        raise LabHarnessError(f"{manifest}: 'inputs' must be a list of paths")
+
+    return Figure(
+        output=Path(str(entry["output"])),
+        script=Path(str(entry["script"])),
+        inputs=tuple(Path(str(item)) for item in inputs),
+    )
+
+
+def _reject_duplicates(figures: tuple[Figure, ...], manifest: Path) -> None:
+    seen: set[Path] = set()
+    for figure in figures:
+        if figure.output in seen:
+            raise LabHarnessError(f"{manifest}: two [[figure]] entries write to '{figure.output}'")
+        seen.add(figure.output)
+
+
+def _relative_to(path: Path, root: Path) -> Path | None:
+    try:
+        return path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return None

labharness/core/templates.py

@@ -0,0 +1,33 @@
+"""Locating the workspace template, which ships inside the installed package."""
+
+from pathlib import Path
+
+from labharness.core.errors import LabHarnessError
+
+WORKSPACE = "workspace"
+JOURNALS = "journals"
+
+
+def template_root() -> Path:
+    """The folder holding the workspace template.
+
+    Installed, it lives inside the package. Running from a source checkout it is the
+    ``templates/`` folder of the repository.
+    """
+    packaged = Path(__file__).resolve().parents[1] / "templates" / WORKSPACE
+    if packaged.is_dir():
+        return packaged
+
+    from_source = Path(__file__).resolve().parents[3] / "templates" / WORKSPACE
+    if from_source.is_dir():
+        return from_source
+
+    raise LabHarnessError("the workspace template is missing from this installation")
+
+
+def journal_template(journal: str) -> Path:
+    folder = template_root() / JOURNALS / journal
+    if not folder.is_dir():
+        available = sorted(item.name for item in (template_root() / JOURNALS).iterdir())
+        raise LabHarnessError(f"unknown journal '{journal}'. Available: {', '.join(available)}")
+    return folder

labharness/core/workspace.py

@@ -0,0 +1,30 @@
+"""Creating a workspace from the template."""
+
+import shutil
+from pathlib import Path
+
+from labharness.core.errors import LabHarnessError
+from labharness.core.manifest import MANIFEST_NAME
+from labharness.core.templates import JOURNALS, journal_template, template_root
+
+
+def create_workspace(target: Path, journal: str = "acs", force: bool = False) -> Path:
+    """Copy the template into ``target`` and drop in the chosen journal files."""
+    target = target.expanduser().resolve()
+    if target.exists() and any(target.iterdir()) and not force:
+        raise LabHarnessError(f"'{target}' is not empty. Use --force to write into it anyway.")
+
+    # The journals folder is not part of a workspace: only the chosen journal is copied,
+    # flattened into the root.
+    shutil.copytree(
+        template_root(),
+        target,
+        dirs_exist_ok=True,
+        ignore=shutil.ignore_patterns(JOURNALS),
+    )
+    for source in journal_template(journal).iterdir():
+        shutil.copy(source, target / source.name)
+
+    if not (target / MANIFEST_NAME).is_file():  # pragma: no cover - template would be broken
+        raise LabHarnessError(f"the template produced no {MANIFEST_NAME}")
+    return target