API reference¶

def viewer_script() -> str:
    """Return the viewer's JavaScript, for a page to inline in a ``<script>`` element.

    Running it defines one global, ``molviz``. The same release returns the same text.

    Raises
    ------
    FileNotFoundError
        If the viewer was never built: ``pixi run build-js`` writes it.
    """
    return files("molviz").joinpath("viewer.js").read_text(encoding="utf-8")

def check(record: dict[str, Any]) -> None:
    """Check ``record`` against the format, with the viewer's own check.

    Raises
    ------
    ValueError
        If the record breaks the format. The message names every problem by its path.
    TypeError
        If a value has no JSON form, such as a set.

    Examples
    --------
    >>> check({"name": "p", "circular": False, "bases": "ACGX"})
    Traceback (most recent call last):
    ...
    ValueError: bases: has "X" at index 3, which is not an IUPAC nucleotide letter
    """
    call("record", "check", record)

def check_gel(gel: dict[str, Any]) -> None:
    """Check ``gel`` against the gel format, with the viewer's own check.

    Raises
    ------
    ValueError
        If the gel breaks the format. The message names every problem by its path.
    TypeError
        If a value has no JSON form, such as a set.

    Examples
    --------
    >>> check_gel({"ladder": {"name": "100 bp", "bands": [100, 0]}, "lanes": []})
    Traceback (most recent call last):
    ...
    ValueError: ladder.bands[1]: must be 1 or more
    """
    call("gel", "check", gel)

def check_plate(plate: dict[str, Any]) -> None:
    """Check ``plate`` against the plate format, with the viewer's own check.

    Raises
    ------
    ValueError
        If the plate breaks the format. The message names every problem by its path.
    TypeError
        If a value has no JSON form, such as a set.

    Examples
    --------
    >>> check_plate({"rows": 8, "columns": 12, "wells": {"I1": "water"}})
    Traceback (most recent call last):
    ...
    ValueError: wells.I1: not on the plate, which runs A1 to H12
    """
    call("plate", "check", plate)

def draw(record: dict[str, Any], **options: Any) -> Drawing:
    """Draw ``record`` with ``options``, checking both with the viewer.

    The options are the viewer's, passed to it as they are, and each one left out takes its
    default. The API reference lists them: <https://liuhlab.github.io/liulab-molviz/api/#options>.

    Raises
    ------
    ValueError
        If the record breaks the format, or else if an option is unknown or wrong. The message
        names every problem by its path, an option's under ``options``.
    TypeError
        If a value has no JSON form, such as a set.

    Examples
    --------
    >>> draw({"name": "p", "circular": False, "bases": "ACGT"}, bogus=1)
    Traceback (most recent call last):
    ...
    ValueError: options.bogus: unknown key
    """
    drawn = call("record", "svg", record, options)
    return Drawing("record", record, drawn, record["name"], options)

def draw_gel(gel: dict[str, Any]) -> Drawing:
    """Draw ``gel``, checking it with the viewer.

    Ladder sizes that would crowd are left out and not counted, so the drawing's ``hidden``
    stays empty and its ``notice`` blank. A page written from it takes the gel's title, or
    "Gel" when it has none.

    Raises
    ------
    ValueError
        If the gel breaks the format. The message names every problem by its path.
    TypeError
        If a value has no JSON form, such as a set.

    Examples
    --------
    >>> gel = {
    ...     "title": "PCR products",
    ...     "ladder": {"name": "NEB 100 bp DNA Ladder (N3231)", "bands": [100, 200, 300]},
    ...     "lanes": [{"name": "GFP", "bands": [741]}, {"name": "empty vector", "bands": []}],
    ... }
    >>> draw_gel(gel).write("gel.pdf")  # doctest: +SKIP
    """
    drawn = call("gel", "svg", gel)
    return Drawing("gel", gel, drawn, gel.get("title") or "Gel")

def draw_plate(plate: dict[str, Any]) -> Drawing:
    """Draw ``plate``, checking it with the viewer.

    The drawing's ``hidden`` is empty and its ``notice`` blank. A page written from it takes
    the plate's title, or "Plate" when it has none.

    Raises
    ------
    ValueError
        If the plate breaks the format. The message names every problem by its path.
    TypeError
        If a value has no JSON form, such as a set.

    Examples
    --------
    >>> plate = {"title": "picked 1", "rows": 8, "columns": 12, "wells": {"A1": "water"}}
    >>> draw_plate(plate).write("plate.pdf")  # doctest: +SKIP
    """
    drawn = call("plate", "svg", plate)
    return Drawing("plate", plate, drawn, plate.get("title") or "Plate")