curlyarrows 0.2.0__py3-none-any.whl

curlyarrows/__init__.py

@@ -0,0 +1,148 @@
+"""curlyarrows – draw molecules, reactions and arrow-pushing mechanisms from
+natural language, SMILES, or a JSON spec.  Built for LLM agents.
+
+Quick start::
+
+    import curlyarrows
+    curlyarrows.draw("ethanol + acetic acid -> ethyl acetate + water", "ester.svg")
+    curlyarrows.draw("CC(=O)O.OCC>>CC(=O)OCC.O", "ester.png")
+    curlyarrows.draw({"steps": [
+        {"species": ["[OH-:1]", "[CH3:2][Br:3]"], "arrows": ["1 -> 2", "2-3 -> 3"]},
+        {"species": ["[CH3:2][OH:1]", "[Br-:3]"]},
+    ]}, "sn2.svg")
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .spec import Species, Reaction, Scheme, MechStep, CurlyArrow, load_spec
+from .spec import Mechanism as _SpecMechanism
+from .style import Style, DEFAULT
+from .resolve import resolve, to_smiles, try_smiles, is_smiles, is_reaction_smiles, ResolveError
+from .parse import parse_reaction
+from .render import render_reaction, render_scheme, render_mechanism, render_species, save, svg_to_png, png_available
+from .render.rdkit_backend import render_species as _render_species_image
+
+__all__ = [
+    "draw", "draw_svg", "draw_molecule", "draw_reaction", "draw_mechanism", "parse", "parse_reaction",
+    "resolve", "to_smiles", "try_smiles", "is_smiles", "is_reaction_smiles", "ResolveError",
+    "Species", "Reaction", "Scheme", "MechStep", "CurlyArrow", "Style", "load_spec",
+    "render_reaction", "render_scheme", "render_mechanism", "render_species", "save", "svg_to_png", "png_available",
+    "GUIDE", "__version__",
+    # v2 graph API (see CONTRACT.md): explicit molecule graphs + routed curly arrows
+    "Molecule", "Atom", "Bond", "GraphError", "Arrow", "Frame", "Mechanism", "draw_v2", "EndpointError",
+]
+__version__ = "0.2.0"
+
+SpecLike = "str | dict | Species | Reaction | Scheme | Mechanism"
+
+
+def parse(inp: Any, **resolve_kw) -> Species | Reaction | Scheme | Mechanism:
+    """Turn any input into a spec object.
+
+    * dict / JSON text  -> :func:`curlyarrows.spec.load_spec`
+    * reaction SMILES   -> Reaction
+    * SMILES or name    -> Species
+    * free text         -> Reaction / Scheme via the NL parser
+    """
+    if isinstance(inp, (Species, Reaction, Scheme, _SpecMechanism, Molecule, Frame, Mechanism)):
+        return inp
+    if isinstance(inp, Path):
+        inp = inp.read_text()
+    if isinstance(inp, str) and inp.strip().startswith("{"):
+        inp = json.loads(inp.strip())
+    if isinstance(inp, dict):
+        if _is_v2(inp):                      # frames spec (v2) -> scene objects
+            from .scene import coerce as _coerce_v2
+            return _coerce_v2(inp)
+        return load_spec(inp)
+    s = str(inp).strip()
+    if is_reaction_smiles(s):
+        return parse_reaction(s)
+    if s.lower().startswith("smiles:"):
+        return Species(s[7:].strip())
+    if is_smiles(s) and " " not in s:
+        return Species(s)
+    # a bare name with no reaction arrow -> single molecule
+    from .parse import _ARROW_SPLIT, _SPLIT_LIST
+    if not _ARROW_SPLIT.search(s) and not _SPLIT_LIST.search(s):
+        r = resolve(s, **resolve_kw)
+        return Species(r.smiles, name=s, label=s if r.source != "smiles" else None)
+    return parse_reaction(s, **resolve_kw)
+
+
+def _is_v2(inp: Any) -> bool:
+    if isinstance(inp, (Molecule, Frame, Mechanism)):
+        return True
+    return isinstance(inp, dict) and ("frames" in inp or "species" in inp)
+
+
+def draw_svg(inp: Any, style: Style = DEFAULT, **resolve_kw) -> str:
+    """Render any input to an SVG string (v1 specs / text, or v2 graph objects)."""
+    if _is_v2(inp):
+        from .scene import draw_svg as _draw_v2_svg
+        return _draw_v2_svg(inp, style)
+    spec = parse(inp, **resolve_kw)
+    if isinstance(spec, Species):
+        return render_species(spec, style)
+    if isinstance(spec, Reaction):
+        return render_reaction(spec, style)
+    if isinstance(spec, Scheme):
+        return render_scheme(spec, style)
+    return render_mechanism(spec, style)
+
+
+def draw(inp: Any, out: str | Path | None = None, *, style: Style = DEFAULT, scale: float = 2.0, **resolve_kw):
+    """Render any input.  With *out* the file is written (.svg/.png/.pdf) and its
+    Path returned; without it the SVG string is returned."""
+    svg = draw_svg(inp, style, **resolve_kw)
+    if out is None:
+        return svg
+    return save(svg, out, scale=scale)
+
+
+def draw_molecule(smiles_or_name: str, out=None, *, label: str | None = None, style: Style = DEFAULT, **kw):
+    r = resolve(smiles_or_name, **kw)
+    sp = Species(r.smiles, label=label if label is not None else (smiles_or_name if r.source != "smiles" else None))
+    svg = render_species(sp, style)
+    return save(svg, out) if out else svg
+
+
+def draw_reaction(text_or_spec, out=None, *, style: Style = DEFAULT, **kw):
+    spec = parse(text_or_spec, **kw)
+    if isinstance(spec, Species):
+        spec = Reaction(reactants=[spec], arrow="none")
+    svg = render_scheme(spec, style) if isinstance(spec, Scheme) else render_reaction(spec, style)
+    return save(svg, out) if out else svg
+
+
+def draw_mechanism(spec, out=None, *, style: Style = DEFAULT):
+    if _is_v2(spec):
+        from .scene import draw as _draw_v2
+        return _draw_v2(spec, out, style=style)
+    spec = load_spec(spec) if not isinstance(spec, _SpecMechanism) else spec
+    if not isinstance(spec, _SpecMechanism):
+        raise TypeError("draw_mechanism needs a Mechanism spec: {'steps': [{'species': [...], 'arrows': [...]}]}")
+    svg = render_mechanism(spec, style)
+    return save(svg, out) if out else svg
+
+
+from .guide import GUIDE  # noqa: E402  (string constant for LLM prompts)
+
+# ---------------------------------------------------------------------------
+# v2 API: explicit molecule graphs (curlyarrows.graph), routed electron-pushing
+# arrows (curlyarrows.arrows) and scenes (curlyarrows.scene).  ``curlyarrows.Mechanism``
+# is the v2 scene class; the v1 SMILES/NL spec class is ``curlyarrows.spec.Mechanism``.
+# ---------------------------------------------------------------------------
+try:
+    from .graph import Molecule, Atom, Bond, GraphError  # noqa: E402
+    from .arrows import Arrow, EndpointError  # noqa: E402
+    from .scene import Frame, Mechanism, draw as draw_v2  # noqa: E402
+except ModuleNotFoundError as _e:  # pragma: no cover - only while the v2 modules are being written
+    if _e.name not in ("curlyarrows.graph", "curlyarrows.arrows", "curlyarrows.scene"):
+        raise
+    import warnings as _w
+    _w.warn(f"curlyarrows v2 API unavailable: {_e}", stacklevel=1)
+    Molecule = Frame = Mechanism = ()  # type: ignore[assignment]  # isinstance() against () is always False

curlyarrows/__main__.py

@@ -0,0 +1,4 @@
+"""`python -m curlyarrows ...` == the `curlyarrows` console script."""
+from .cli import main
+
+raise SystemExit(main())