Python API

The CLI is a thin wrapper around render_file, which loads a spec file and calls render. Both paths go through the same Spec, so they cannot disagree about what an option does.

from prot_struct_viz import render_file

render_file("spec.yaml")

render_file and load_spec both take an out argument, the API side of the CLI's --out: a spec that names no output is rendered where the caller says, resolved relative to the working directory. Spec.out is required either way, populated from whichever source gave it.

To build a spec in Python instead of reading one, construct it directly. ViewConfig keeps its defaults here — the "no defaults" rule is a property of the spec file, which has to be readable on its own, not of the dataclass:

import pathlib

from prot_struct_viz import Spec, View, ViewConfig, render

render(
    Spec(
        structure="1F8B",
        out=pathlib.Path("view.html"),
        assembly="1",
        views=(
            View(
                name="Active site",
                csv=pathlib.Path("coloring.csv"),
                config=ViewConfig(assembly="1", waters="hide"),
                title_md=pathlib.Path("title.md"),
            ),
        ),
    )
)

assembly and on_mismatch appear on both Spec and each view's ViewConfig: they are shared settings, and load_spec stamps them onto every view so a view's config is a complete description of how that view is built. Constructing a Spec by hand, keep them in step.

render_file(spec_path, out=None)

Load a YAML spec file and render it. What the CLI does.

Parameters:

Name	Type	Description	Default
spec_path	str | Path	The YAML spec file.	required
out	str | Path | None	Output HTML file, resolved relative to the working directory rather than to the spec file. Exactly one of this and the spec's own out key must be given.	None

Returns:

Type	Description
Path	The path written.

render(spec)

Render one spec to a self-contained HTML file.

Parameters:

Name	Type	Description	Default
spec	Spec	The parsed spec: one structure, one output path, and one or more views.	required

Returns:

Type	Description
Path	The path written.

Raises:

Type	Description
InputError	On invalid input, or on a mismatch fatal under the spec's on_mismatch. The report file is written either way.

load_spec(path, out=None)

Read and validate a spec file.

Parameters:

Name	Type	Description	Default
path	str | Path	The YAML file. Paths inside it resolve relative to it.	required
out	str | Path | None	Output HTML file, resolved relative to the working directory rather than to the spec file. Exactly one of this and the spec's own out key must be given; see OUT_KEY.	None

Returns:

Type	Description
Spec	The parsed spec, with every view's options already validated by prot_struct_viz.ViewConfig.

Raises:

Type	Description
InputError	On anything the file gets wrong, naming the key at fault.

prot_struct_viz.Spec dataclass

A whole spec file: one structure, one output, and the views to draw.

prot_struct_viz.View dataclass

One named view of the structure: what to draw and how to draw it.

slug property

Filesystem- and ref-safe form of name, used inside the archive.

prot_struct_viz.ViewConfig dataclass

Everything that controls a rendered view, shared by the CLI and render.

Field names are spec-file keys; what each one means is in docs/spec.md.

prot_struct_viz.InputError

Bases: Exception

Raised on invalid user input (bad CSV, bad structure, failed validation).

The CLI catches this, writes the report, and exits non-zero. It never carries a traceback to the user: the message is the whole story.