chartwright 0.2.0__tar.gz → 0.2.1__tar.gz

{chartwright-0.2.0/chartwright.egg-info → chartwright-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chartwright
-Version: 0.2.0
+Version: 0.2.1
 Summary: Build, verify, and maintain Apache Superset dashboards from small spec files.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/debabsah/chartwright

{chartwright-0.2.0 → chartwright-0.2.1}/chartwright/__init__.py

@@ -4,4 +4,4 @@ Typed spec -> deterministic compiler -> guaranteed-correct Superset dashboard.
 The LLM is an untrusted parser at the edge; the guarantee lives in typed code.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{chartwright-0.2.0 → chartwright-0.2.1}/chartwright/compiler.py

@@ -355,20 +355,66 @@ def _chart_params(chart, spec: DashboardSpec, resolution: Resolution) -> dict:
         # (utils/mergeCustomEChartOptions.ts: arrays replace, so never a mixed chart's yAxis).
         p["echart_options"] = json.dumps(p["echart_options"])
 
-    # Bind charts without their own TIME column to the dataset's main temporal
-    # column. The dashboard time filter reaches a chart only through a time
-    # binding; without one the chart silently ignores it while the filter bar
-    # still counts it as filtered (verified live on 6.1.0: full-month total
-    # under a one-week default). The categorical bar's x_axis is not a time
-    # column, so it needs the binding too.
-    timeseries = ("timeseries_line", "timeseries_bar", "timeseries_area",
-                  "timeseries_scatter", "big_number_trend")
-    time_x = t == "mixed" and "time_grain_sqla" in p
-    if t not in timeseries and not time_x and ds.main_dttm_col:
+    # A time range, the chart's own or a dashboard time filter's, reaches a query
+    # only through a time binding; without one the chart silently ignores it while
+    # the filter bar still counts it as filtered.
+    #
+    # The backend applies a query's time_range to the WHERE clause only through
+    # `granularity` (get_sqla_query, superset/models/helpers.py at 4.1.4, 5.0.0 and
+    # 6.1.0), which the frontend sends from granularity_sqla. A chart without a time
+    # axis binds the dataset's main time column there (verified live on 6.1.0: a
+    # full-month total under a one-week dashboard default before the binding). The
+    # categorical bar's x_axis is not a time column, so it needs the binding too.
+    #
+    # A chart drawn on a time axis can't take that binding: with granularity set,
+    # _apply_granularity (superset/common/query_context_factory.py) swaps the x-axis
+    # column for it. Superset's own charts filter the axis with an adhoc
+    # TEMPORAL_RANGE filter instead, applied whatever the granularity, and
+    # _apply_filters sets its value to the query's time_range: the chart's own, or
+    # the dashboard filter's. Without it, these charts returned every row on all
+    # three releases (seen live: a line chart limited to 2004-03-01 : 2005-03-02
+    # still drew 2003 to 2005).
+    axis = time_axis_column(chart, ds)
+    if axis:
+        temporal = _temporal_range_filter(axis, p["time_range"])
+        p["adhoc_filters"] = p["adhoc_filters"] + [temporal]
+        if t == "mixed":
+            p["adhoc_filters_b"] = p["adhoc_filters_b"] + [temporal]
+    elif ds.main_dttm_col:
         p["granularity_sqla"] = ds.main_dttm_col
     return p
 
 
+# Chart types whose x axis is always their time column.
+TIME_AXIS_TYPES = ("timeseries_line", "timeseries_bar", "timeseries_area",
+                   "timeseries_scatter", "big_number_trend")
+
+
+def time_axis_column(chart, ds) -> str | None:
+    """The time column a chart draws its x axis on, or None for a chart without a
+    time axis. The compiler and smoke share it, so the smoke query is filtered the
+    way the chart is."""
+    if chart.type in TIME_AXIS_TYPES:
+        return chart.time_column
+    if chart.type == "mixed" and mixed_time_axis(chart, ds):
+        return chart.x_column
+    return None
+
+
+def _temporal_range_filter(column: str, time_range: str) -> dict:
+    # The shape Explore saves for the "Time range" filter pill (all three releases).
+    # Its comparator matches the chart's time_range: a non-empty time_range, "No
+    # filter" included, overwrites it at query time (_apply_filters), so the two
+    # can't disagree.
+    return {
+        "clause": "WHERE",
+        "expressionType": "SIMPLE",
+        "subject": column,
+        "operator": "TEMPORAL_RANGE",
+        "comparator": time_range,
+    }
+
+
 def mixed_time_axis(chart, ds) -> bool:
     """Whether a mixed chart's x column draws a time axis: the column's reported type
     decides (a column flagged temporal counts), time_grain only when it is unknown.

{chartwright-0.2.0 → chartwright-0.2.1}/chartwright/smoke.py

@@ -17,7 +17,7 @@ import math
 from dataclasses import dataclass
 
 from .client import SupersetClient
-from .compiler import _metric_payload, mixed_time_axis
+from .compiler import _metric_payload, mixed_time_axis, time_axis_column
 from .resolver import Resolution
 from .spec import GRID_HEADER_UNITS, DashboardSpec, grid_units_for_rows
 
@@ -69,6 +69,24 @@ def _filters_payload(chart) -> list[dict]:
     return [{"col": f.column, "op": f.op, "val": f.value} for f in chart.filters]
 
 
+def _with_time_range(q: dict, chart, ds) -> dict:
+    """The chart's own time_range, bound the way the compiled chart binds it: a
+    TEMPORAL_RANGE filter on a time axis (compiler.time_axis_column), else the
+    dataset's main time column as granularity. A chart without a time_range, or
+    without a binding, keeps the unfiltered query."""
+    time_range = getattr(chart, "time_range", None)
+    if not time_range:
+        return q
+    axis = time_axis_column(chart, ds)
+    if axis:
+        q["time_range"] = time_range
+        q["filters"] = q["filters"] + [{"col": axis, "op": "TEMPORAL_RANGE", "val": time_range}]
+    elif ds.main_dttm_col:
+        q["time_range"] = time_range
+        q["granularity"] = ds.main_dttm_col
+    return q
+
+
 def _time_axis(column: str, grain: str | None) -> dict:
     return {
         "columnType": "BASE_AXIS",
@@ -144,7 +162,7 @@ def _mixed_queries(chart, spec: DashboardSpec, ds) -> list[dict]:
         out.append({
             "filters": _filters_payload(chart),
             "extras": {"time_grain_sqla": chart.time_grain or "P1D"},
-            "time_range": chart.time_range or "No filter",
+            "time_range": "No filter",
             "row_limit": chart.row_limit or 1000,
             "columns": [x] + ([series.groupby] if series.groupby else []),
             "metrics": [_metric_payload(m, spec.dashboard.slug, chart.name) for m in series.metrics],
@@ -157,7 +175,8 @@ def smoke_chart(chart, spec: DashboardSpec, resolution: Resolution, client: Supe
     ds = resolution.for_chart(chart.dataset)
     ctx = {
         "datasource": {"id": ds.id, "type": "table"},
-        "queries": _mixed_queries(chart, spec, ds) if chart.type == "mixed" else [_query_for(chart, spec)],
+        "queries": [_with_time_range(q, chart, ds) for q in (
+            _mixed_queries(chart, spec, ds) if chart.type == "mixed" else [_query_for(chart, spec)])],
         "result_format": "json",
         "result_type": "full",
     }

{chartwright-0.2.0 → chartwright-0.2.1/chartwright.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chartwright
-Version: 0.2.0
+Version: 0.2.1
 Summary: Build, verify, and maintain Apache Superset dashboards from small spec files.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/debabsah/chartwright

{chartwright-0.2.0 → chartwright-0.2.1}/chartwright.egg-info/SOURCES.txt

@@ -39,6 +39,7 @@ tests/test_absorb.py
 tests/test_apply_rollback.py
 tests/test_backup_layout.py
 tests/test_calibrate.py
+tests/test_chart_time_range.py
 tests/test_client.py
 tests/test_column_suggestions.py
 tests/test_compiler.py

{chartwright-0.2.0 → chartwright-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chartwright"
-version = "0.2.0"
+version = "0.2.1"
 description = "Build, verify, and maintain Apache Superset dashboards from small spec files."
 license = "Apache-2.0"
 readme = "README.md"

chartwright-0.2.1/tests/test_chart_time_range.py

@@ -0,0 +1,200 @@
+"""A chart's time range, its own `time_range` or a dashboard time filter's,
+reaches its query only through a time binding.
+
+A chart without a time axis binds the dataset's main time column as
+granularity_sqla. A chart drawn on a time axis (timeseries_*, big_number_trend,
+mixed on a time column) gets an adhoc TEMPORAL_RANGE filter on that axis. Before
+that filter (0.2.0), Superset 4.1.4, 5.0.0 and 6.1.0 applied neither the chart's
+time_range nor the dashboard's time filter to those charts (seen live: a line
+chart with time_range "2004-03-01 : 2005-03-02" still drew 2003 to 2005)."""
+
+import io
+import zipfile
+
+import pytest
+import yaml
+
+from chartwright.compiler import compile_bundle
+from chartwright.dashdiff import _normalize
+from chartwright.decompile import decompile_bundle
+from chartwright.smoke import _mixed_queries, _query_for, _with_time_range
+from chartwright.spec import load_spec
+from chartwright.testing import stub_resolution
+
+DS = {"database": "examples", "table": "t"}
+RANGE = "2004-03-01 : 2005-03-02"
+# The charts that take their own time_range.
+RANGED = [
+    {"name": "Line", "type": "timeseries_line", "metrics": ["COUNT(*)"], "time_column": "ts"},
+    {"name": "Bars", "type": "timeseries_bar", "metrics": ["COUNT(*)"], "time_column": "ts"},
+    {"name": "Area", "type": "timeseries_area", "metrics": ["COUNT(*)"], "time_column": "ts"},
+    {"name": "Dots", "type": "timeseries_scatter", "metrics": ["COUNT(*)"], "time_column": "ts"},
+    {"name": "Mixed by month", "type": "mixed", "x_column": "ts", "time_grain": "P1M",
+     "a": {"metrics": ["COUNT(*)"]},
+     "b": {"metrics": ["SUM(amount)"], "kind": "line", "axis": "secondary"}},
+]
+TREND = {"name": "Trend", "type": "big_number_trend", "metric": "COUNT(*)", "time_column": "ts"}
+MIXED_CATEGORY = {"name": "Mixed by region", "type": "mixed", "x_column": "region",
+                  "a": {"metrics": ["COUNT(*)"]},
+                  "b": {"metrics": ["SUM(amount)"], "kind": "line", "axis": "secondary"}}
+AXIS_NAMES = {c["name"] for c in RANGED} | {TREND["name"]}
+NO_AXIS = [
+    {"name": "Total", "type": "big_number_total", "metric": "COUNT(*)"},
+    {"name": "Table", "type": "table", "groupby": ["region"], "metrics": ["COUNT(*)"]},
+    {"name": "Pie", "type": "pie", "metric": "COUNT(*)", "groupby": "region"},
+    {"name": "Pivot", "type": "pivot_table", "rows": ["region"], "columns": [], "metrics": ["COUNT(*)"]},
+    {"name": "Bar", "type": "bar", "x_column": "region", "metrics": ["COUNT(*)"]},
+    MIXED_CATEGORY,
+]
+
+
+def _spec(charts, time_range=None):
+    # Only the charts that have a time_range field take one.
+    takes_range = {"timeseries_line", "timeseries_bar", "timeseries_area", "timeseries_scatter", "mixed"}
+    charts = [{**c, "dataset": DS,
+               **({"time_range": time_range} if time_range and c["type"] in takes_range else {})}
+              for c in charts]
+    return load_spec({
+        "spec_version": "1",
+        "dashboard": {"title": "T", "slug": "sdc-t"},
+        "charts": charts,
+        "layout": {"rows": [[c["name"]] for c in charts]},
+    })
+
+
+def _resolution(spec, main_dttm_col="ts"):
+    res = stub_resolution(spec)
+    for ds in res.datasets.values():
+        ds.main_dttm_col = main_dttm_col
+        ds.column_types.update({"ts": 2, "region": 1})
+    return res
+
+
+def _bundle(spec, res=None):
+    return compile_bundle(spec, res or _resolution(spec))
+
+
+def _params(spec, res=None):
+    zf = zipfile.ZipFile(io.BytesIO(_bundle(spec, res)))
+    return {cy["slice_name"]: cy["params"] for cy in
+            (yaml.safe_load(zf.read(n)) for n in zf.namelist() if "/charts/" in n)}
+
+
+def _temporal(params, key="adhoc_filters"):
+    return [f for f in params.get(key) or [] if f.get("operator") == "TEMPORAL_RANGE"]
+
+
+def _lookup(spec, res):
+    by_uuid = {res.for_chart(c.dataset).uuid: dict(DS, schema=None) for c in spec.charts}
+    return lambda u: by_uuid.get(u)
+
+
+@pytest.mark.parametrize("time_range", [RANGE, None])
+def test_a_time_axis_chart_filters_its_axis_with_its_range(time_range):
+    params = _params(_spec(RANGED, time_range))
+    for name, p in params.items():
+        expected = time_range or "No filter"
+        assert p["time_range"] == expected, name
+        assert _temporal(p) == [{"clause": "WHERE", "expressionType": "SIMPLE", "subject": "ts",
+                                 "operator": "TEMPORAL_RANGE", "comparator": expected}], name
+        assert "granularity_sqla" not in p, name  # it would replace the axis column
+
+
+def test_a_trendline_kpi_filters_its_axis():
+    """big_number_trend has no time_range of its own: the filter carries "No filter",
+    which the dashboard time filter's range overwrites at query time."""
+    p = _params(_spec([TREND]))["Trend"]
+    assert p["time_range"] == "No filter"
+    assert _temporal(p) == [{"clause": "WHERE", "expressionType": "SIMPLE", "subject": "ts",
+                             "operator": "TEMPORAL_RANGE", "comparator": "No filter"}]
+    assert "granularity_sqla" not in p
+
+
+def test_a_mixed_time_chart_filters_both_queries():
+    p = _params(_spec(RANGED, RANGE))["Mixed by month"]
+    assert p["adhoc_filters_b"] == p["adhoc_filters"] and _temporal(p, "adhoc_filters_b")
+
+
+def test_a_mixed_time_chart_without_column_types_follows_its_grain():
+    """The stub resolution reports no column types: a time_grain makes the axis a
+    time axis (mixed_time_axis), and the filter follows it."""
+    spec = _spec(RANGED[-1:], RANGE)
+    p = _params(spec, stub_resolution(spec))["Mixed by month"]
+    assert _temporal(p) and _temporal(p, "adhoc_filters_b")
+
+
+def test_the_range_filter_follows_the_charts_own_filters():
+    chart = {**RANGED[0], "filters": [{"column": "region", "op": "==", "value": "West"}]}
+    p = _params(_spec([chart], RANGE))["Line"]
+    assert [f["operator"] for f in p["adhoc_filters"]] == ["==", "TEMPORAL_RANGE"]
+
+
+@pytest.mark.parametrize("time_range", [RANGE, None])
+def test_a_chart_without_a_time_axis_keeps_the_granularity_binding(time_range):
+    for name, p in _params(_spec(NO_AXIS, time_range)).items():
+        expected = time_range if name == MIXED_CATEGORY["name"] and time_range else "No filter"
+        assert p["time_range"] == expected, name
+        assert p["granularity_sqla"] == "ts", name
+        assert not _temporal(p) and not _temporal(p, "adhoc_filters_b"), name
+
+
+def test_a_dataset_without_a_time_column_binds_nothing_to_a_chart_without_an_axis():
+    spec = _spec(NO_AXIS[:1])
+    p = _params(spec, _resolution(spec, main_dttm_col=None))["Total"]
+    assert "granularity_sqla" not in p and not _temporal(p)
+
+
+def test_compiles_are_deterministic():
+    spec = _spec(RANGED + [TREND] + NO_AXIS, RANGE)
+    assert _bundle(spec) == _bundle(spec)
+
+
+@pytest.mark.parametrize("time_range", [RANGE, None])
+def test_decompile_reads_the_range_back_without_a_chart_filter(time_range):
+    spec = _spec(RANGED + [TREND] + NO_AXIS, time_range)
+    res = _resolution(spec)
+    result = decompile_bundle(_bundle(spec, res), _lookup(spec, res))
+    assert result.losses == [], [loss.as_dict() for loss in result.losses]
+    ranged = {c.name for c in spec.charts if getattr(c, "time_range", None)}
+    for chart in result.spec["charts"]:
+        assert chart.get("time_range") == (time_range if chart["name"] in ranged else None), chart["name"]
+        assert "filters" not in chart, chart["name"]
+    # plan compares exactly this: no drift on an unchanged spec.
+    assert _normalize(load_spec(result.spec)) == _normalize(spec)
+
+
+def test_decompile_keeps_the_charts_own_filters_beside_the_range():
+    chart = {**RANGED[-1], "filters": [{"column": "region", "op": "==", "value": "West"}]}
+    spec = _spec([chart], RANGE)
+    res = _resolution(spec)
+    result = decompile_bundle(_bundle(spec, res), _lookup(spec, res))
+    assert result.losses == [], [loss.as_dict() for loss in result.losses]
+    assert result.spec["charts"][0]["filters"] == [{"column": "region", "op": "==", "value": "West"}]
+    assert _normalize(load_spec(result.spec)) == _normalize(spec)
+
+
+def test_smoke_queries_with_the_charts_range():
+    spec = _spec(RANGED + NO_AXIS, RANGE)
+    res = _resolution(spec)
+    for chart in spec.charts:
+        ds = res.for_chart(chart.dataset)
+        queries = _mixed_queries(chart, spec, ds) if chart.type == "mixed" else [_query_for(chart, spec)]
+        for q in (_with_time_range(q, chart, ds) for q in queries):
+            temporal = [f for f in q["filters"] if f["op"] == "TEMPORAL_RANGE"]
+            if chart.name in AXIS_NAMES:
+                assert q["time_range"] == RANGE, chart.name
+                assert temporal == [{"col": "ts", "op": "TEMPORAL_RANGE", "val": RANGE}], chart.name
+                assert "granularity" not in q, chart.name
+            elif chart.name == MIXED_CATEGORY["name"]:
+                assert q["time_range"] == RANGE and q["granularity"] == "ts" and not temporal
+            else:  # no time_range of its own: the unfiltered query
+                assert q["time_range"] == "No filter" and "granularity" not in q and not temporal
+
+
+def test_smoke_without_a_range_stays_unfiltered():
+    spec = _spec(RANGED[:1] + [TREND] + NO_AXIS[:1])
+    res = _resolution(spec)
+    for chart in spec.charts:
+        q = _with_time_range(_query_for(chart, spec), chart, res.for_chart(chart.dataset))
+        assert q["time_range"] == "No filter" and "granularity" not in q
+        assert not [f for f in q["filters"] if f["op"] == "TEMPORAL_RANGE"]

{chartwright-0.2.0 → chartwright-0.2.1}/tests/test_compiler.py

@@ -30,7 +30,11 @@ def test_compile_is_byte_stable():
 def test_golden_bytes():
     """The whole guarantee in one assert. Regenerate deliberately with:
     .venv/bin/python -c "from tests.test_compiler import regen; regen()"
-    and review the diff."""
+    and review the diff.
+
+    Last regenerated for 0.2.1: "Sales Over Time" gained the TEMPORAL_RANGE adhoc
+    filter on its time axis, so its own and the dashboard's time range apply
+    (tests/test_chart_time_range.py). Every other member is byte-identical."""
     assert GOLDEN.exists(), "golden missing; run regen() and commit the result"
     assert _bundle() == GOLDEN.read_bytes()
 

{chartwright-0.2.0 → chartwright-0.2.1}/tests/test_mixed_chart.py

@@ -66,7 +66,9 @@ def test_compile_time_axis_mixed():
     assert (p["seriesType"], p["seriesTypeB"]) == ("bar", "line")
     assert (p["yAxisIndex"], p["yAxisIndexB"]) == (0, 1)
     assert p["y_axis_format"] == "SMART_NUMBER" and p["y_axis_format_secondary"] == ".3f"
-    assert p["adhoc_filters"] == p["adhoc_filters_b"] and len(p["adhoc_filters"]) == 1
+    # The chart's own filter, then the time-range filter on its axis (0.2.1).
+    assert p["adhoc_filters"] == p["adhoc_filters_b"] and len(p["adhoc_filters"]) == 2
+    assert p["adhoc_filters"][1]["operator"] == "TEMPORAL_RANGE"
     assert p["groupby"] == [] and p["groupby_b"] == []