semql-erd 0.1.0__tar.gz

semql_erd-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Nikhil Pallamreddy
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

semql_erd-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: semql-erd
+Version: 0.1.0
+Summary: Graphviz ER diagrams from a semql Catalog — cubes as nodes, joins as edges with crow's-foot arrowheads.
+Author: Nikhil Pallamreddy
+Author-email: Nikhil Pallamreddy <nikhil.pallamreddy+git@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Requires-Dist: semql>=0.1.0,<0.2
+Requires-Dist: graphviz>=0.20 ; extra == 'image'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/npalladium/semql
+Project-URL: Repository, https://github.com/npalladium/semql
+Project-URL: Issues, https://github.com/npalladium/semql/issues
+Provides-Extra: image
+Description-Content-Type: text/markdown
+
+# semql-erd
+
+ER-diagram generator for [`semql`](../semql) catalogues. Walks the
+cubes and joins in a `Catalog` and emits a [Graphviz](https://graphviz.org)
+DOT source (and convenience PNG/SVG when the `graphviz` Python bindings
++ system `dot` binary are available).
+
+Useful when:
+- The catalogue is past 10 cubes and reading the YAML/Python isn't
+  enough to see the join shape at a glance.
+- A PR touches a `Join` and the reviewer wants a visual diff of the
+  before / after graph.
+- Onboarding docs need a stable picture of what's in scope.
+
+## Install
+
+```sh
+pip install semql-erd            # DOT source only — no system deps
+pip install "semql-erd[image]"   # + graphviz Python bindings
+                                 #   (also needs the `dot` binary)
+```
+
+## Quick start — DOT source
+
+`render_dot(catalog)` is dependency-free: it produces a DOT-language
+string you can paste into any Graphviz renderer
+([Edotor](https://edotor.net) is a quick web one).
+
+```python
+from semql import Backend, Catalog, Cube, Dimension, Join, Measure
+from semql_erd import render_dot
+
+orders = Cube(
+    name="orders",
+    backend=Backend.POSTGRES,
+    table="orders",
+    alias="o",
+    measures=[Measure(name="revenue", sql="{o}.amount", agg="sum", unit="currency")],
+    dimensions=[Dimension(name="region", sql="{o}.region", type="string")],
+    joins=[Join(to="customers", relationship="many_to_one", on="{o}.cid = {c}.id")],
+)
+customers = Cube(
+    name="customers",
+    backend=Backend.POSTGRES,
+    table="customers",
+    alias="c",
+    dimensions=[Dimension(name="name", sql="{c}.name", type="string")],
+)
+
+print(render_dot(Catalog([orders, customers])))
+```
+
+## Quick start — PNG/SVG
+
+```python
+from semql_erd import render_image
+
+# Requires `pip install "semql-erd[image]"` AND the `dot` binary on PATH.
+render_image(catalog, "catalog.png")  # PNG by default
+render_image(catalog, "catalog.svg", format="svg")
+```
+
+## Conventions
+
+- **Nodes** are cubes. The label is a Graphviz record showing the cube
+  name (+ `display_name` suffix if set), the backend, and three field
+  sections (measures, dimensions, time-dimensions).
+- **Edges** are `Join`s. Arrowhead shape encodes the relationship:
+  - `many_to_one` → `crow` on the from-side, `tee` on the to-side
+  - `one_to_many` → mirror of the above
+  - `one_to_one` → `tee` on both sides
+- **Filtering** mirrors the planner prompt: by default only cubes with
+  `expose_in_prompt=True` (and non-META cubes) appear. Pass
+  `only_exposed=False` for a full graph.
+- **Layout** defaults to `rankdir="LR"` (left-to-right). Pass
+  `rankdir="TB"` for top-to-bottom.
+
+## CLI
+
+```sh
+python -m semql_erd path.to.module:catalog          # prints DOT to stdout
+python -m semql_erd path.to.module:catalog out.svg  # writes a rendered image
+```
+
+## Status
+
+Early development. The DOT format is stable; record-section ordering
+and node ID naming may evolve.

semql_erd-0.1.0/README.md

@@ -0,0 +1,88 @@
+# semql-erd
+
+ER-diagram generator for [`semql`](../semql) catalogues. Walks the
+cubes and joins in a `Catalog` and emits a [Graphviz](https://graphviz.org)
+DOT source (and convenience PNG/SVG when the `graphviz` Python bindings
++ system `dot` binary are available).
+
+Useful when:
+- The catalogue is past 10 cubes and reading the YAML/Python isn't
+  enough to see the join shape at a glance.
+- A PR touches a `Join` and the reviewer wants a visual diff of the
+  before / after graph.
+- Onboarding docs need a stable picture of what's in scope.
+
+## Install
+
+```sh
+pip install semql-erd            # DOT source only — no system deps
+pip install "semql-erd[image]"   # + graphviz Python bindings
+                                 #   (also needs the `dot` binary)
+```
+
+## Quick start — DOT source
+
+`render_dot(catalog)` is dependency-free: it produces a DOT-language
+string you can paste into any Graphviz renderer
+([Edotor](https://edotor.net) is a quick web one).
+
+```python
+from semql import Backend, Catalog, Cube, Dimension, Join, Measure
+from semql_erd import render_dot
+
+orders = Cube(
+    name="orders",
+    backend=Backend.POSTGRES,
+    table="orders",
+    alias="o",
+    measures=[Measure(name="revenue", sql="{o}.amount", agg="sum", unit="currency")],
+    dimensions=[Dimension(name="region", sql="{o}.region", type="string")],
+    joins=[Join(to="customers", relationship="many_to_one", on="{o}.cid = {c}.id")],
+)
+customers = Cube(
+    name="customers",
+    backend=Backend.POSTGRES,
+    table="customers",
+    alias="c",
+    dimensions=[Dimension(name="name", sql="{c}.name", type="string")],
+)
+
+print(render_dot(Catalog([orders, customers])))
+```
+
+## Quick start — PNG/SVG
+
+```python
+from semql_erd import render_image
+
+# Requires `pip install "semql-erd[image]"` AND the `dot` binary on PATH.
+render_image(catalog, "catalog.png")  # PNG by default
+render_image(catalog, "catalog.svg", format="svg")
+```
+
+## Conventions
+
+- **Nodes** are cubes. The label is a Graphviz record showing the cube
+  name (+ `display_name` suffix if set), the backend, and three field
+  sections (measures, dimensions, time-dimensions).
+- **Edges** are `Join`s. Arrowhead shape encodes the relationship:
+  - `many_to_one` → `crow` on the from-side, `tee` on the to-side
+  - `one_to_many` → mirror of the above
+  - `one_to_one` → `tee` on both sides
+- **Filtering** mirrors the planner prompt: by default only cubes with
+  `expose_in_prompt=True` (and non-META cubes) appear. Pass
+  `only_exposed=False` for a full graph.
+- **Layout** defaults to `rankdir="LR"` (left-to-right). Pass
+  `rankdir="TB"` for top-to-bottom.
+
+## CLI
+
+```sh
+python -m semql_erd path.to.module:catalog          # prints DOT to stdout
+python -m semql_erd path.to.module:catalog out.svg  # writes a rendered image
+```
+
+## Status
+
+Early development. The DOT format is stable; record-section ordering
+and node ID naming may evolve.

semql_erd-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "semql-erd"
+version = "0.1.0"
+description = "Graphviz ER diagrams from a semql Catalog — cubes as nodes, joins as edges with crow's-foot arrowheads."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Nikhil Pallamreddy", email = "nikhil.pallamreddy+git@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "semql>=0.1.0,<0.2",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Multimedia :: Graphics",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/npalladium/semql"
+Repository = "https://github.com/npalladium/semql"
+Issues = "https://github.com/npalladium/semql/issues"
+
+[project.optional-dependencies]
+# Required only for ``render_image`` (PNG/SVG output). ``render_dot``
+# (the DOT-source path) has no third-party dependencies.
+image = [
+    "graphviz>=0.20",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+semql = { workspace = true, editable = true }

semql_erd-0.1.0/src/semql_erd/__init__.py

@@ -0,0 +1,14 @@
+"""Graphviz ER-diagram generator for semql Catalogs.
+
+``render_dot(catalog)`` returns a DOT-language string and has no
+third-party dependencies. ``render_image(catalog, path)`` shells out
+to Graphviz via the ``graphviz`` Python bindings — install with
+``pip install "semql-erd[image]"`` and a system ``dot`` binary.
+"""
+
+from __future__ import annotations
+
+from semql_erd.dot import render_dot
+from semql_erd.image import render_image
+
+__all__ = ["render_dot", "render_image"]

semql_erd-0.1.0/src/semql_erd/__main__.py

@@ -0,0 +1,60 @@
+"""CLI: ``python -m semql_erd <module:attr> [out_path]``.
+
+``module:attr`` is a Python import path to a ``Catalog`` instance.
+With no output path, prints DOT to stdout. With an output path,
+renders an image (format inferred from suffix; defaults to PNG).
+
+Example:
+
+    python -m semql_erd my.catalog:CATALOG
+    python -m semql_erd my.catalog:CATALOG catalog.svg
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+from semql import Catalog
+
+from semql_erd.dot import render_dot
+from semql_erd.image import render_image
+
+
+def _load_catalog(spec: str) -> Catalog:
+    if ":" not in spec:
+        raise SystemExit(
+            f"expected '<module>:<attr>', got {spec!r}. Example: 'my_project.catalog:CATALOG'"
+        )
+    module_name, attr = spec.split(":", 1)
+    module = importlib.import_module(module_name)
+    if not hasattr(module, attr):
+        raise SystemExit(f"module {module_name!r} has no attribute {attr!r}.")
+    obj = getattr(module, attr)
+    if not isinstance(obj, Catalog):
+        raise SystemExit(f"{spec} is not a Catalog instance (got {type(obj).__name__}).")
+    return obj
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(argv if argv is not None else sys.argv[1:])
+    if not args or args[0] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    spec = args[0]
+    catalog = _load_catalog(spec)
+
+    if len(args) == 1:
+        sys.stdout.write(render_dot(catalog))
+        return 0
+
+    out = Path(args[1])
+    fmt = out.suffix.lstrip(".") or "png"
+    rendered = render_image(catalog, out, format=fmt)
+    print(f"wrote {rendered}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

semql_erd-0.1.0/src/semql_erd/dot.py

@@ -0,0 +1,152 @@
+"""DOT-source generation for catalogue ER diagrams.
+
+Pure-Python — no third-party imports. ``render_dot(catalog)`` walks
+the cubes and joins and produces a string consumable by any Graphviz
+renderer.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from semql import Catalog
+from semql.model import Cube
+
+RankDir = Literal["LR", "TB", "RL", "BT"]
+
+
+# ---------------------------------------------------------------------------
+# Crow's-foot arrowhead conventions per relationship.
+# ``arrowhead`` is the marker at the target end of the edge; ``arrowtail``
+# is at the source end. We enable ``dir=both`` so both markers render.
+# ---------------------------------------------------------------------------
+
+
+def _relationship_attrs(relationship: str) -> dict[str, str]:
+    if relationship == "many_to_one":
+        return {"arrowtail": "crow", "arrowhead": "tee", "dir": "both"}
+    if relationship == "one_to_many":
+        return {"arrowtail": "tee", "arrowhead": "crow", "dir": "both"}
+    if relationship == "one_to_one":
+        return {"arrowtail": "tee", "arrowhead": "tee", "dir": "both"}
+    return {"arrowhead": "normal"}
+
+
+# ---------------------------------------------------------------------------
+# Escaping for DOT record-shape labels.
+# Record labels use ``|`` as a section separator and ``{`` / ``}`` to group;
+# ``<`` and ``>`` introduce port names. Escape those plus the obvious
+# quote / backslash so a description with apostrophes or pipes doesn't
+# break the layout.
+# ---------------------------------------------------------------------------
+
+
+_RECORD_ESCAPES = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "|": "\\|",
+    "{": "\\{",
+    "}": "\\}",
+    "<": "\\<",
+    ">": "\\>",
+    "\n": "\\n",
+}
+
+
+def _escape_record(text: str) -> str:
+    return "".join(_RECORD_ESCAPES.get(ch, ch) for ch in text)
+
+
+def _cube_label(cube: Cube) -> str:
+    """Build a DOT record-shape label string for ``cube``.
+
+    Layout: header (cube name + optional display_name + backend) on top,
+    measures / dimensions / time-dimensions stacked below, separated by
+    horizontal rules (``|`` between sections)."""
+    header_parts = [cube.name]
+    if cube.display_name:
+        header_parts.append(f"({cube.display_name})")
+    header_parts.append(f"\n[{cube.backend.value}]")
+    header = " ".join(header_parts)
+
+    sections: list[str] = [header]
+    if cube.measures:
+        ms = ", ".join(m.name for m in cube.measures)
+        sections.append(f"measures: {ms}")
+    if cube.dimensions:
+        ds = ", ".join(d.name for d in cube.dimensions)
+        sections.append(f"dimensions: {ds}")
+    if cube.time_dimensions:
+        ts = ", ".join(td.name for td in cube.time_dimensions)
+        sections.append(f"time: {ts}")
+
+    return "{" + "|".join(_escape_record(s) for s in sections) + "}"
+
+
+def _node_id(cube: Cube) -> str:
+    """A safe DOT node identifier — cube names are already restricted
+    to ``[a-z_][a-z0-9_]*`` by the resolver regex, so they need no
+    further escaping."""
+    return cube.name
+
+
+def _cubes_in_scope(catalog: Catalog, *, only_exposed: bool) -> list[Cube]:
+    """Filter the catalogue for rendering. META reflection cubes are
+    always excluded — they're an introspection mechanism, not part of
+    the data model. ``only_exposed=True`` (default) also drops cubes
+    flagged ``expose_in_prompt=False`` so the diagram matches what the
+    planner sees."""
+    from semql import iter_cubes
+
+    return list(iter_cubes(catalog, only_exposed=only_exposed))
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def render_dot(
+    catalog: Catalog,
+    *,
+    only_exposed: bool = True,
+    rankdir: RankDir = "LR",
+    title: str | None = None,
+) -> str:
+    """Render the catalogue as a Graphviz DOT source string.
+
+    ``only_exposed`` (default ``True``) mirrors the planner-prompt
+    filter — only cubes flagged ``expose_in_prompt=True`` appear.
+    ``rankdir`` controls layout direction (LR/TB/RL/BT).
+    ``title`` is an optional graph label rendered at the top.
+    """
+    cubes = _cubes_in_scope(catalog, only_exposed=only_exposed)
+    in_scope: set[str] = {c.name for c in cubes}
+
+    lines: list[str] = ["digraph catalog {"]
+    lines.append(f'  rankdir="{rankdir}";')
+    lines.append('  node [shape=record, fontname="Helvetica", fontsize=10];')
+    lines.append('  edge [fontname="Helvetica", fontsize=9];')
+    if title:
+        lines.append(f'  label="{_escape_record(title)}";')
+        lines.append("  labelloc=t;")
+    lines.append("")
+
+    for cube in cubes:
+        lines.append(f'  {_node_id(cube)} [label="{_cube_label(cube)}"];')
+
+    lines.append("")
+    for cube in cubes:
+        for join in cube.joins:
+            if join.to not in in_scope:
+                # Skip edges that would dangle into filtered-out cubes.
+                continue
+            attrs = _relationship_attrs(join.relationship)
+            attr_str = ", ".join(f'{k}="{v}"' for k, v in attrs.items())
+            lines.append(f"  {_node_id(cube)} -> {join.to} [{attr_str}];")
+
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+__all__ = ["RankDir", "render_dot"]

semql_erd-0.1.0/src/semql_erd/image.py

@@ -0,0 +1,57 @@
+# pyright: reportUnknownVariableType=false, reportUnknownMemberType=false, reportUnknownArgumentType=false
+# ``graphviz`` ships no type stubs; pyright reports every method
+# return as Unknown. The functions wrap it tightly enough that local
+# inference covers the actual contract.
+"""PNG/SVG rendering for catalogue ER diagrams.
+
+Shells out to Graphviz via the optional ``graphviz`` Python bindings.
+Install with ``pip install "semql-erd[image]"`` and a system ``dot``
+binary on PATH. The pure-Python ``render_dot`` path stays usable
+without these.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from semql import Catalog
+
+from semql_erd.dot import RankDir, render_dot
+
+
+def render_image(
+    catalog: Catalog,
+    path: str | Path,
+    *,
+    format: str = "png",
+    only_exposed: bool = True,
+    rankdir: RankDir = "LR",
+    title: str | None = None,
+) -> Path:
+    """Render the catalogue as a PNG / SVG / PDF image at ``path``.
+
+    Calls the system ``dot`` binary via the ``graphviz`` Python
+    bindings. Raises ``ImportError`` if the optional ``image`` extra
+    isn't installed, and ``graphviz.ExecutableNotFound`` (re-raised
+    from the bindings) if the ``dot`` binary isn't on PATH.
+    """
+    try:
+        from graphviz import Source  # type: ignore[import-not-found]
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "render_image requires the ``image`` extra. Install with "
+            "``pip install 'semql-erd[image]'``."
+        ) from exc
+
+    dot_source = render_dot(catalog, only_exposed=only_exposed, rankdir=rankdir, title=title)
+    target = Path(path)
+    # ``graphviz.Source`` writes ``<filename>.<format>``; we want the
+    # exact path the caller asked for, so strip the suffix and pass it
+    # as ``filename`` with ``format=`` matching the requested type.
+    filename = target.with_suffix("")
+    src = Source(dot_source, format=format)
+    rendered = src.render(filename=str(filename), cleanup=True)
+    return Path(rendered)
+
+
+__all__ = ["render_image"]