Metadata-Version: 2.5
Name: query-viz
Version: 0.1.0
Summary: Render tabular query results (list-of-dict rows) as chart images. Rows in, PNG out: no agent framework, no cloud SDK.
Project-URL: Source, https://github.com/sakura-sky/query-viz
Project-URL: Issues, https://github.com/sakura-sky/query-viz/issues
Project-URL: Changelog, https://github.com/sakura-sky/query-viz/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/sakura-sky/query-viz/blob/main/SECURITY.md
Author: Sakura Sky Engineering
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,chart,dataframe,matplotlib,png,sql,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: matplotlib<4,>=3.7
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.13; extra == 'dev'
Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# query-viz

**Render tabular query results as chart images.** Rows in, PNG out.

`query-viz` does one thing: it turns a list of row dicts (exactly what a data
warehouse driver such as BigQuery, Snowflake or Postgres hands back) into a chart
image. No agent framework, no cloud SDK, no DataFrame requirement. That makes it
a clean building block for an LLM agent tool, a report generator, or any
pipeline that has already fetched data and wants a picture of it.

```python
from query_viz import render_chart

png = render_chart(
    rows=[
        {"month": "Jan", "signups": 120},
        {"month": "Feb", "signups": 155},
        {"month": "Mar", "signups": 143},
    ],
    chart_type="bar",     # bar | line | pie | scatter
    x="month",
    y="signups",
    title="Signups by month",
)

with open("signups.png", "wb") as fh:
    fh.write(png)
```

## Why a library

It was extracted from an ADK marketing agent's "chart this query" tool. The
*rendering* is pure and reusable; the agent-specific parts (running a guarded
query, uploading the image to Drive) stay in the agent as a thin wrapper. Same
split as [`sql-guard`](https://github.com/sakura-sky/sql-guard): the reusable
engine is a library, the framework glue is not.

## API

```python
render_chart(
    rows,                     # Sequence[Mapping[str, Any]]
    *,
    chart_type,               # "bar" | "line" | "pie" | "scatter"
    x,                        # category / x-axis column (pie slice labels)
    y=None,                   # numeric value column (required for every type)
    title="",
    dpi=120,
    figsize=(10.0, 6.0),
    palette=None,             # brand colours, applied in order
    color_map=None,           # permanent category-to-colour pins
    color_overrides=None,     # one-off pins for this chart; beat color_map
) -> bytes                    # PNG image bytes
```

- `bar`, `line`, `scatter` need both `x` and `y`.
- `pie` uses `x` for slice labels and `y` for slice sizes.
- Non-numeric `y` values coerce to `0.0` rather than erroring, so a stray
  `None` won't sink a whole chart.
- Raises `ChartError` (a `ValueError`) for an unsupported type, empty rows, or a
  missing column.
- Colour pins are keyed by the category value for `bar` and `pie`, and by the
  `y` column name for `line` and `scatter`, which draw a single series.

## Design notes

- **Headless.** Forces matplotlib's `Agg` backend, so it renders on a server
  with no display.
- **Pure.** No I/O, no globals: deterministic given its inputs, and safe to
  call from a worker thread (`asyncio.to_thread`).
- **Typed.** Ships `py.typed`.

## Install

```bash
pip install query-viz
```

The distribution is named `query-viz`; the import package is `query_viz`. Only
dependency is `matplotlib`.

## License

Apache-2.0. See [LICENSE](https://github.com/sakura-sky/query-viz/blob/main/LICENSE).
