Metadata-Version: 2.4
Name: spytial_diagramming
Version: 1.14.3
Summary: sPyTial: Spatial Python visualization with declarative constraints
Author: Siddhartha Prasad
License: MIT
Project-URL: Homepage, https://github.com/sidprasad/spytial
Project-URL: Documentation, https://sidprasad.github.io/spytial/
Project-URL: Repository, https://github.com/sidprasad/spytial
Project-URL: Issues, https://github.com/sidprasad/spytial/issues
Keywords: visualization,diagrams,spatial,constraints,data-structures
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: ipython>=8.0.0
Provides-Extra: headless
Requires-Dist: selenium>=4.0.0; extra == "headless"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: jsonschema>=4.0.0; extra == "dev"
Provides-Extra: e2e
Requires-Dist: playwright>=1.40; extra == "e2e"
Provides-Extra: suggest-search
Requires-Dist: hypothesis>=6.0.0; extra == "suggest-search"
Provides-Extra: suggest-llm
Requires-Dist: llm>=0.23; python_version >= "3.10" and extra == "suggest-llm"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Dynamic: license-file

# sPyTial: Lightweight Diagrams for Structured Python Data

[![PyPI version](https://img.shields.io/pypi/v/spytial-diagramming.svg)](https://pypi.org/project/spytial-diagramming/)
[![Python versions](https://img.shields.io/pypi/pyversions/spytial-diagramming.svg)](https://pypi.org/project/spytial-diagramming/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/sidprasad/spytial/actions/workflows/ci.yml/badge.svg)](https://github.com/sidprasad/spytial/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://sidprasad.github.io/spytial/)

```bash
pip install spytial-diagramming
```

**Docs:** https://sidprasad.github.io/spytial/ — start with [Getting Started](https://sidprasad.github.io/spytial/getting-started/) for install, badges, and your first diagram.

---

Sometimes you just want to see your data.

You're working with a tree, a graph, a recursive object — maybe an AST, a neural network, or a symbolic term. You don't need an interactive dashboard or a production-grade visualization system. You just need a diagram that lays it out clearly so you can understand what's going on.

That's what `sPyTial` is for. It is designed for developers, educators, and researchers who work with structured data and need to make that structure visible — to themselves or to others — with minimal effort.

## Why spatial layout

Spatial arrangement helps people understand structure: when elements are grouped, aligned, and oriented meaningfully, patterns and errors become easier to see. `sPyTial` gives you that layout **by default** — the diagram reflects how the parts are connected, not how they happen to be stored.

You get:
- a **box-and-arrow diagram** that shows the shape of your data
- a layout driven by declarative constraints (`orientation`, `align`, `cyclic`, `group`)
- a tool that flags when a constraint can't be satisfied

## Quick start

```python
import spytial

data = {
    "name": "root",
    "children": [
        {"value": 1},
        {"value": 2},
        {"value": 3},
    ],
}

# Opens in a browser tab, or inline in a Jupyter notebook.
spytial.diagram(data)

# Or save to a file:
spytial.diagram(data, method="file")
```

Not sure where to start with a class of your own? `from spytial.suggest import suggest` then `suggest(MyClass)` reads the class and scaffolds a starting set of layout directives you can edit — see [Suggesting Specs](https://sidprasad.github.io/spytial/suggest/).

For stepping through sequences of states, custom relationalizers, and annotation-driven layouts, see the [docs](https://sidprasad.github.io/spytial/).

## Related projects

- **[`spytial-clrs`](https://github.com/sidprasad/spytial-clrs)** — a Jupyter notebook collection that implements the data structures from the CLRS algorithms textbook (Cormen, Leiserson, Rivest, Stein) using sPyTial: heaps, linked lists, hash tables, BST / red-black / B / van Emde Boas trees, disjoint-set forests, graphs with MST and SCC views, and more. The best place to see sPyTial on realistic structures.
- **[`spytial-core`](https://github.com/sidprasad/spytial-core)** — the browser-side rendering engine sPyTial uses under the hood. Shared across all sPyTial language hosts (Python, Rust, Pyret, Lean).

## License

MIT — see [LICENSE](LICENSE).


## Browser assets and offline use

The Python package includes its pinned spytial-core browser JS and CSS. Normal
`diagram(..., method="browser")` and `method="file"` outputs are self-contained;
`edit()` serves these assets through its existing local server. The evaluator,
sequence viewer, and standalone editor follow the same delivery policy.

Notebook output and the Pyodide playground use pinned CDN URLs by default, keeping
saved notebook cells small. Set `SPYTIAL_ASSETS=embedded` for offline notebook use,
or `SPYTIAL_ASSETS=cdn` to opt into CDN delivery for every output. The default is
`SPYTIAL_ASSETS=auto`. Explicit file exports embed the assets even under Pyodide.
For example, before generating a notebook output:

```python
import os
os.environ["SPYTIAL_ASSETS"] = "embedded"
```

Embedded output includes several megabytes of JavaScript per page; saved notebook
outputs use isolated `srcdoc` iframes to avoid data-URL size limits. CDN output requires network access on a
cold load. Vendoring removes that network dependency for local output, but each
new page still initializes JavaScript and computes its layout. Offline pages use
locally available fonts instead of requesting the default Google Font. Explicit
remote resources in your own spec (such as image URLs) still need a connection.

Maintainers: run `./update-spytial-core.sh` to update **all** vendored core assets,
or `./update-spytial-core.sh --version 6.6.0` to select or repair an exact release.
`./update-spytial-core.sh --check` verifies hashes and the complete file inventory
offline. See [the vendoring instructions](spytial/_vendor/browser/README.md) for
offline tarballs and wheel verification.
