fjader 0.2.0__py3-none-any.whl

fjader/__init__.py

@@ -0,0 +1,98 @@
+"""Fjader — GPU-accelerated data visualization for Python.
+
+Phase 1: Spec generation. Produces JSON specs consumed by the Fjader
+JavaScript renderer.
+
+Usage:
+    import fjader as fj
+
+    chart = fj.dot(table='penguins', x='bill_length', y='bill_depth', fill='species')
+    chart.to_dict()
+
+    # Overlay (two marks, one chart)
+    overlay = fj.dot(table='t', x='a', y='b') * fj.line(table='t', x='a', y='b')
+
+    # Layout (two charts side by side)
+    layout = fj.dot(table='t', x='a', y='b') + fj.bar_y(table='t', x='species', y='count()')
+
+    # Chart-level config
+    fj.plot(fj.dot(table='t', x='a', y='b'), width=600, x_label='X')
+"""
+
+from ._version import __version__
+
+# Mark factory functions
+from .marks import dot, bar_x, bar_y, line, area_y, area_x, rect, rect_x, rect_y, text
+
+# Chart container
+from .plot import plot
+
+# Interactors
+from .interactors import interval_x, interval_y, interval_2d, toggle, derived_interval
+
+# Layout helpers
+from .layout import hconcat, vconcat
+
+# Transforms
+from .transforms import (
+    filter,
+    having,
+    limit,
+    orderby,
+    topN,
+    stack_y,
+    stack_x,
+    normalize,
+    dodge,
+)
+
+# Field spec helpers
+from .fields import count, sum, avg, min_, max_, median, bin, window, sql_expr
+
+# Data helpers
+from .data import sql
+
+# Display helpers
+from ._display import show
+
+# Spec import
+from ._from_spec import from_spec
+
+# Lazy submodule access — import only when accessed (avoids hard dep on streamlit)
+import importlib as _importlib
+
+def __getattr__(name: str):
+    if name == "streamlit":
+        return _importlib.import_module("._streamlit", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+# Types (for type annotations in user code)
+from ._types import ColorScheme, CurveType, ScaleType, SortConfig, TextAnchor, LineAnchor
+from .fields import FieldSpec
+
+__all__ = [
+    "__version__",
+    # Marks
+    "dot", "bar_x", "bar_y", "line", "area_y", "area_x",
+    "rect", "rect_x", "rect_y", "text",
+    # Chart
+    "plot",
+    # Interactors
+    "interval_x", "interval_y", "interval_2d", "toggle", "derived_interval",
+    # Layout
+    "hconcat", "vconcat",
+    # Transforms
+    "filter", "having", "limit", "orderby",
+    "topN", "stack_y", "stack_x", "normalize", "dodge",
+    # Fields
+    "count", "sum", "avg", "min_", "max_", "median", "bin", "window", "sql_expr",
+    # Data
+    "sql",
+    # Display
+    "show",
+    # Spec import
+    "from_spec",
+    # Types
+    "FieldSpec", "ColorScheme", "CurveType", "ScaleType",
+    "SortConfig", "TextAnchor", "LineAnchor",
+]

fjader/_accessor.py

@@ -0,0 +1,74 @@
+"""Shared DataFrame accessor for Fjader.
+
+Provides ``df.fj.dot(x='a', y='b')`` syntax for quick exploration.
+Returns anywidget instances that auto-display in Jupyter and Marimo,
+and support composition via ``*`` (overlay), ``+`` (layout), and ``.opts()``.
+
+Registration is done by importing the appropriate module::
+
+    import fjader.pandas as fj   # registers .fj on pandas DataFrames
+    import fjader.polars as fj   # registers .fj on polars DataFrames
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import marks as _marks
+from ._display import show
+
+
+class FjaderAccessor:
+    """DataFrame accessor — ``df.fj.dot(x='a', y='b', fill='species')``."""
+
+    def __init__(self, df: Any) -> None:
+        self._df = df
+
+    def _call(self, factory: Any, **kwargs: Any) -> Any:
+        for key in ("data", "table"):
+            if key in kwargs:
+                raise TypeError(
+                    f"Cannot pass '{key}' through the .fj accessor — "
+                    f"data is implicitly the DataFrame itself."
+                )
+        return show(factory(data=self._df, **kwargs))
+
+    def dot(self, **kwargs: Any) -> Any:
+        """Scatter/dot mark. See ``fj.dot()`` for parameters."""
+        return self._call(_marks.dot, **kwargs)
+
+    def bar_x(self, **kwargs: Any) -> Any:
+        """Horizontal bar mark. See ``fj.bar_x()`` for parameters."""
+        return self._call(_marks.bar_x, **kwargs)
+
+    def bar_y(self, **kwargs: Any) -> Any:
+        """Vertical bar mark. See ``fj.bar_y()`` for parameters."""
+        return self._call(_marks.bar_y, **kwargs)
+
+    def line(self, **kwargs: Any) -> Any:
+        """Line mark. See ``fj.line()`` for parameters."""
+        return self._call(_marks.line, **kwargs)
+
+    def area_y(self, **kwargs: Any) -> Any:
+        """Vertical area mark. See ``fj.area_y()`` for parameters."""
+        return self._call(_marks.area_y, **kwargs)
+
+    def area_x(self, **kwargs: Any) -> Any:
+        """Horizontal area mark. See ``fj.area_x()`` for parameters."""
+        return self._call(_marks.area_x, **kwargs)
+
+    def rect(self, **kwargs: Any) -> Any:
+        """Rectangle mark. See ``fj.rect()`` for parameters."""
+        return self._call(_marks.rect, **kwargs)
+
+    def rect_x(self, **kwargs: Any) -> Any:
+        """Horizontal rect mark. See ``fj.rect_x()`` for parameters."""
+        return self._call(_marks.rect_x, **kwargs)
+
+    def rect_y(self, **kwargs: Any) -> Any:
+        """Vertical rect mark. See ``fj.rect_y()`` for parameters."""
+        return self._call(_marks.rect_y, **kwargs)
+
+    def text(self, **kwargs: Any) -> Any:
+        """Text mark. See ``fj.text()`` for parameters."""
+        return self._call(_marks.text, **kwargs)

fjader/_convert.py

@@ -0,0 +1,36 @@
+"""snake_case to camelCase conversion and serialization helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def to_camel_case(name: str) -> str:
+    """Convert snake_case to camelCase.
+
+    stroke_width -> strokeWidth
+    fill_opacity -> fillOpacity
+    preferred_x_scale_type -> preferredXScaleType
+    """
+    parts = name.split("_")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def serialize_value(value: Any) -> Any:
+    """Recursively serialize a value for JSON output."""
+    if value is None:
+        return None
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (list, tuple)):
+        return [serialize_value(v) for v in value]
+    if isinstance(value, dict):
+        return {to_camel_case(k): serialize_value(v) for k, v in value.items()}
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    raise TypeError(f"Cannot serialize {type(value).__name__}: {value!r}")
+
+
+def clean_dict(d: dict[str, Any]) -> dict[str, Any]:
+    """Remove keys whose values are None (unset optional props)."""
+    return {k: v for k, v in d.items() if v is not None}

fjader/_data.py

@@ -0,0 +1,86 @@
+"""DataFrame → Arrow IPC serialization + content-hash deduplication.
+
+Uses narwhals for DataFrame-library-agnostic handling. Accepts pandas,
+polars, cudf, modin, etc.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import weakref
+from typing import Any
+
+
+# Module-level cache: weakref to df object → (hash, ipc_bytes).
+# Uses weak references so cache entries are evicted when the DataFrame
+# is garbage-collected, preventing unbounded memory growth in long sessions.
+_hash_cache: dict[int, tuple[weakref.ref, str, bytes]] = {}
+
+
+def _cleanup_ref(obj_id: int) -> None:
+    """Remove cache entry when the DataFrame is garbage-collected."""
+    _hash_cache.pop(obj_id, None)
+
+
+def df_to_arrow_ipc(df: Any) -> bytes:
+    """Convert a DataFrame to Arrow IPC stream bytes.
+
+    Library-agnostic via narwhals. Polars uses native IPC writer (no pyarrow
+    needed); pandas and others go through narwhals → pyarrow IPC.
+    """
+    # Polars: native IPC stream writer — zero-copy, no pyarrow needed
+    # Must use write_ipc_stream (not write_ipc) because DuckDB-WASM's
+    # insertArrowFromIPCStream expects Arrow IPC stream format, not file format.
+    if hasattr(df, "write_ipc_stream"):
+        buf = io.BytesIO()
+        df.write_ipc_stream(buf)
+        return buf.getvalue()
+
+    # Pandas/others: convert to Arrow via narwhals → pyarrow IPC
+    import narwhals as nw
+
+    try:
+        import pyarrow as pa
+        import pyarrow.ipc as ipc
+    except ImportError as e:
+        raise ImportError(
+            "fjader needs pyarrow for pandas and other non-polars DataFrames. "
+            "Install with: pip install 'fjader[pyarrow]'"
+        ) from e
+
+    nf = nw.from_native(df, eager_only=True)
+    table = nf.to_arrow()
+    sink = pa.BufferOutputStream()
+    writer = ipc.new_stream(sink, table.schema)
+    writer.write_table(table)
+    writer.close()
+    return sink.getvalue().to_pybytes()
+
+
+def content_hash(data: bytes) -> str:
+    """SHA-256 hex prefix for deduplication."""
+    return hashlib.sha256(data).hexdigest()[:16]
+
+
+def df_to_ipc_cached(df: Any) -> tuple[str, bytes]:
+    """Serialize DataFrame to Arrow IPC with caching by object identity.
+
+    The same DataFrame object serialized multiple times reuses cached bytes.
+    Cache entries are automatically evicted when the DataFrame is garbage-collected.
+
+    Returns (content_hash, ipc_bytes).
+    """
+    obj_id = id(df)
+    cached = _hash_cache.get(obj_id)
+    if cached is not None:
+        ref, h, ipc_bytes = cached
+        # Verify the weakref is still alive (same object, not reused id)
+        if ref() is df:
+            return h, ipc_bytes
+
+    ipc_bytes = df_to_arrow_ipc(df)
+    h = content_hash(ipc_bytes)
+    ref = weakref.ref(df, lambda _: _cleanup_ref(obj_id))
+    _hash_cache[obj_id] = (ref, h, ipc_bytes)
+    return h, ipc_bytes

fjader/_display.py

@@ -0,0 +1,97 @@
+"""Display wiring: Mark/Plot/Layout → FjaderWidget."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol, runtime_checkable
+
+from ._data import df_to_ipc_cached
+
+
+@runtime_checkable
+class Displayable(Protocol):
+    """Protocol for objects that can be rendered as Fjader widgets."""
+
+    def _to_full_spec(self) -> tuple[dict[str, Any], dict[str, Any]]: ...
+
+
+def _serialize_dataframes(
+    dataframes: dict[str, Any],
+) -> tuple[list[dict[str, Any]], bytes]:
+    """Serialize DataFrames to a manifest + concatenated Arrow IPC blob.
+
+    Returns (manifest, blob) where manifest is a list of
+    {name, hash, offset, length} dicts and blob is the concatenated IPC bytes.
+    """
+    manifest: list[dict[str, Any]] = []
+    chunks: list[bytes] = []
+    offset = 0
+
+    for table_name, df in dataframes.items():
+        h, ipc_bytes = df_to_ipc_cached(df)
+        length = len(ipc_bytes)
+        manifest.append({
+            "name": table_name,
+            "hash": h,
+            "offset": offset,
+            "length": length,
+        })
+        chunks.append(ipc_bytes)
+        offset += length
+
+    return manifest, b"".join(chunks)
+
+
+_DEFAULT_WIDGET_HEIGHT = 400
+_LAYOUT_GAP = 8  # matches .fjader-vconcat/.fjader-hconcat { gap: 8px }
+
+
+def _inject_default_height(spec: dict[str, Any], height: int) -> None:
+    """Set height on all plot specs and compute total container height.
+
+    Without an explicit pixel height, PlotFromSpec falls back to
+    ``aspect-ratio: 4/3`` which doesn't size correctly inside
+    anywidget containers in marimo / Jupyter.
+
+    Also computes ``_containerHeight`` — the exact pixel height the
+    anywidget ``el`` needs so that vconcat layouts aren't clipped.
+    """
+    if "plot" in spec:
+        spec["plot"].setdefault("height", height)
+        spec["_containerHeight"] = spec["plot"]["height"]
+    elif "vconcat" in spec:
+        for item in spec["vconcat"]:
+            item.setdefault("height", height)
+        heights = [item["height"] for item in spec["vconcat"]]
+        spec["_containerHeight"] = sum(heights) + (len(heights) - 1) * _LAYOUT_GAP
+    elif "hconcat" in spec:
+        for item in spec["hconcat"]:
+            item.setdefault("height", height)
+        heights = [item["height"] for item in spec["hconcat"]]
+        spec["_containerHeight"] = max(heights) if heights else height
+
+
+def make_widget(obj: Displayable) -> Any:
+    """Convert Mark/Plot/Overlay/Layout to a renderable FjaderWidget."""
+    from ._widget import FjaderWidget
+
+    spec_dict, dataframes = obj._to_full_spec()
+    _inject_default_height(spec_dict, _DEFAULT_WIDGET_HEIGHT)
+    manifest, blob = _serialize_dataframes(dataframes)
+
+    return FjaderWidget(
+        spec=json.dumps(spec_dict),
+        data_manifest=json.dumps(manifest),
+        data_blob=blob,
+        _source=obj,
+    )
+
+
+def show(obj: Displayable) -> Any:
+    """Display a Fjader object in a Jupyter notebook.
+
+    Convenience function — equivalent to calling ``make_widget(obj)``
+    and displaying it. In most cases you can just let the ``_repr_mimebundle_``
+    protocol handle display automatically.
+    """
+    return make_widget(obj)

fjader/_from_spec.py

@@ -0,0 +1,131 @@
+"""Render a Fjader chart from a raw JSON spec (e.g. exported from the palette)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+class SpecPlot:
+    """Wraps a raw FjaderSpec dict for rendering in Jupyter or Streamlit.
+
+    Created by :func:`from_spec`. Implements the ``Displayable`` protocol
+    so it can be passed to ``fj.show()``, ``fj.streamlit.render()``, or
+    displayed directly in Jupyter/Marimo.
+    """
+
+    def __init__(
+        self,
+        spec: dict[str, Any],
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        self._spec = spec
+        self._dataframes = data or {}
+
+    def _to_full_spec(self) -> tuple[dict[str, Any], dict[str, Any]]:
+        return self._spec, self._dataframes
+
+    def to_dict(self) -> dict[str, Any]:
+        return self._spec
+
+    def to_json(self, **kwargs: Any) -> str:
+        return json.dumps(self._spec, **kwargs)
+
+    def _repr_mimebundle_(self, **kwargs: Any) -> Any:
+        from ._display import make_widget
+
+        return make_widget(self)._repr_mimebundle_(**kwargs)
+
+
+def _normalize_spec(spec: dict[str, Any]) -> dict[str, Any]:
+    """Wrap a bare PlotSpec in a FjaderSpec if needed.
+
+    The palette exports bare PlotSpec (``{"marks": [...]}``) without
+    the outer ``{"plot": ...}`` wrapper. The renderer expects the full form.
+    """
+    if "plot" in spec or "hconcat" in spec or "vconcat" in spec:
+        return spec
+    # Bare PlotSpec — wrap it
+    return {"plot": spec}
+
+
+def from_spec(
+    spec: dict[str, Any] | str,
+    data: dict[str, Any] | None = None,
+) -> SpecPlot:
+    """Create a renderable chart from a raw JSON spec.
+
+    Use this to render specs exported from the Fjader command palette
+    (Cmd+E), or any hand-written spec dict.
+
+    Args:
+        spec: A FjaderSpec dict or JSON string. Accepts both the full form
+            (``{"plot": {"marks": [...]}}``) and the bare PlotSpec form
+            (``{"marks": [...]}``) exported by the palette.
+        data: Optional dict mapping table names to DataFrames. Required when
+            the spec references tables backed by in-memory data rather than
+            file URLs. Example: ``{"flights": df}``.
+
+    Returns:
+        A ``SpecPlot`` object that can be displayed in Jupyter, passed to
+        ``fj.show()``, or rendered with ``fj.streamlit.render()``.
+
+    Examples::
+
+        # Paste a spec exported from the palette
+        chart = fj.from_spec({
+            "marks": [{
+                "mark": "dot",
+                "table": "penguins",
+                "x": "bill_length",
+                "y": "bill_depth",
+                "fill": "species"
+            }]
+        }, data={"penguins": df})
+
+        # Full FjaderSpec with file-based data sources
+        chart = fj.from_spec({
+            "data": {"flights": {"url": "flights.parquet", "type": "parquet"}},
+            "plot": {
+                "marks": [{"mark": "barY", "table": "flights", "x": "carrier", "y": "count()"}]
+            }
+        })
+    """
+    if isinstance(spec, str):
+        spec = json.loads(spec)
+
+    spec = _normalize_spec(spec)
+
+    # Wire up DataFrames: assign hash-based table names matching what the
+    # marks reference, so the serialization pipeline can ship them as Arrow IPC.
+    dataframes: dict[str, Any] = {}
+    if data:
+        from ._data import df_to_ipc_cached
+
+        for table_name, df in data.items():
+            h, _ = df_to_ipc_cached(df)
+            hashed_name = f"_df_{h}"
+            # Rewrite table references in the spec so marks point to the
+            # hashed name that the widget data-loading pipeline expects.
+            _rewrite_table_refs(spec, table_name, hashed_name)
+            dataframes[hashed_name] = df
+
+    return SpecPlot(spec, dataframes)
+
+
+def _rewrite_table_refs(spec: dict[str, Any], old: str, new: str) -> None:
+    """Replace ``table: old`` with ``table: new`` in all marks."""
+    for plot_spec in _iter_plot_specs(spec):
+        for mark in plot_spec.get("marks", []):
+            if mark.get("table") == old:
+                mark["table"] = new
+
+
+def _iter_plot_specs(spec: dict[str, Any]):
+    """Yield all PlotSpec dicts from a FjaderSpec."""
+    if "plot" in spec:
+        yield spec["plot"]
+    for item in spec.get("hconcat", []):
+        yield item
+    for item in spec.get("vconcat", []):
+        yield item

fjader/_streamlit.py

@@ -0,0 +1,137 @@
+"""Native Streamlit custom component for Fjader.
+
+Usage::
+
+    import streamlit as st
+    import fjader as fj
+    import polars as pl
+
+    df = pl.DataFrame({"x": range(50), "y": [i**0.5 for i in range(50)]})
+    fj.streamlit.render(fj.dot(data=df, x="x", y="y"))
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import narwhals as nw
+
+from ._data import df_to_ipc_cached
+from ._display import Displayable
+
+try:
+    import streamlit.components.v1 as components
+except ImportError as e:
+    raise ImportError(
+        "Fjader Streamlit support requires streamlit. "
+        "Install with: pip install 'fjader[streamlit]'"
+    ) from e
+
+_FRONTEND_DIR = os.path.join(os.path.dirname(__file__), "streamlit_frontend")
+if not os.path.isfile(os.path.join(_FRONTEND_DIR, "index.html")):
+    raise ImportError(
+        "fjader's Streamlit bundle is missing. In a source checkout, build it with "
+        "`npm run build:all` from the repository root."
+    )
+_component = components.declare_component("fjader", path=_FRONTEND_DIR)
+
+
+def _to_pandas(df: Any) -> Any:
+    """Convert any DataFrame to pandas for Streamlit's native Arrow serialization."""
+    return nw.from_native(df, eager_only=True).to_pandas()
+
+
+def render(
+    obj: Displayable,
+    height: int = 500,
+    key: str | None = None,
+) -> Any:
+    """Render a Fjader chart in a Streamlit app.
+
+    Args:
+        obj: A Fjader mark, plot, or layout object.
+        height: Component height in pixels.
+        key: Streamlit component key for state management.
+
+    Returns:
+        The component value (None unless selections are implemented).
+    """
+    spec_dict, dataframes = obj._to_full_spec()
+
+    # Inject heights into the spec and compute the actual iframe height.
+    iframe_height = _inject_height(spec_dict, height)
+
+    manifest: list[dict[str, str]] = []
+    table_args: dict[str, Any] = {}
+
+    for i, (table_name, df) in enumerate(dataframes.items()):
+        h, _ = df_to_ipc_cached(df)
+        arg_key = f"_df_{i}"
+        table_args[arg_key] = _to_pandas(df)
+        manifest.append({"name": table_name, "hash": h, "arg": arg_key})
+
+    return _component(
+        spec=json.dumps(spec_dict),
+        data_manifest=json.dumps(manifest),
+        height=iframe_height,
+        key=key,
+        default=None,
+        **table_args,
+    )
+
+
+_VCONCAT_GAP = 8  # matches CSS gap in LayoutFromSpec.svelte
+
+
+def _is_layout(item: dict[str, Any]) -> bool:
+    """True if the item is a nested layout (has hconcat or vconcat key)."""
+    return "hconcat" in item or "vconcat" in item
+
+
+def _inject_height(spec: dict[str, Any], height: int) -> int:
+    """Set height on plot specs and return the iframe height to use.
+
+    For a single plot, uses ``height`` as the default.
+    For vconcat: if all items have explicit heights the iframe expands to fit;
+    otherwise the remaining space from ``height`` is split among unset items.
+    For hconcat: each item gets the full ``height`` (CSS flex splits width).
+    Nested layouts are handled recursively.
+    """
+    if "plot" in spec:
+        spec["plot"].setdefault("height", height)
+        return height
+
+    items = spec.get("vconcat", [])
+    if items:
+        unset = [item for item in items if not _is_layout(item) and "height" not in item]
+        explicit_total = 0
+        for item in items:
+            if _is_layout(item):
+                # Recurse: nested layout gets remaining height budget, returns its own.
+                explicit_total += _inject_height(item, height)
+            elif "height" in item:
+                explicit_total += item["height"]
+        total_gap = _VCONCAT_GAP * (len(items) - 1)
+
+        if not unset:
+            return explicit_total + total_gap
+        remaining = height - explicit_total - total_gap
+        per_item = max(remaining // len(unset), 50)
+        for item in unset:
+            item["height"] = per_item
+        return height
+
+    items = spec.get("hconcat", [])
+    if items:
+        max_h = 0
+        for item in items:
+            if _is_layout(item):
+                max_h = max(max_h, _inject_height(item, height))
+            else:
+                item.setdefault("height", height)
+                max_h = max(max_h, item.get("height", height))
+        return max_h
+
+    return height