bezel-charts 0.1.0__tar.gz

bezel_charts-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.DS_Store
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+python/dist/

bezel_charts-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog (Python package)
+
+## 0.1.0 (unreleased)
+
+First release of the Python companion to Bezel Charts.
+
+- `bc.spark()` and `bc.line()` take a pandas DataFrame or Series, a NumPy array, a dict or a plain list, and return a `Chart` that shows up in Jupyter, saves as an `.svg` file and converts to an SVG string.
+- `bc.to_svg()` and `bc.render()` mirror the JavaScript functions of the same names and take the same options, in snake_case, kebab-case or camelCase.
+- The output matches the web components byte for byte, checked against fixtures generated from the JavaScript on every pull request.
+- Zero dependencies. Python 3.10 or newer.

bezel_charts-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaz Moghaddam, https://shazmoghaddam.github.io, https://linkedin.com/in/shazmoghaddam, London.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bezel_charts-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: bezel-charts
+Version: 0.1.0
+Summary: Polished SVG charts from pandas DataFrames and Python lists, drawn exactly like the Bezel Charts web components. Zero dependencies.
+Project-URL: Homepage, https://shazmoghaddam.github.io/bezel-charts/site/
+Project-URL: Documentation, https://github.com/ShazMoghaddam/bezel-charts/tree/main/python#readme
+Project-URL: Repository, https://github.com/ShazMoghaddam/bezel-charts
+Project-URL: Issues, https://github.com/ShazMoghaddam/bezel-charts/issues
+Project-URL: Changelog, https://github.com/ShazMoghaddam/bezel-charts/blob/main/python/CHANGELOG.md
+Author: Shaz Moghaddam
+License-Expression: MIT
+License-File: LICENSE
+Keywords: charts,data-visualization,jupyter,line-chart,pandas,readme,sparkline,svg
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Provides-Extra: test
+Requires-Dist: numpy>=1.26; extra == 'test'
+Requires-Dist: pandas>=2; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Bezel Charts for Python
+
+**Polished SVG charts straight from a pandas DataFrame.**
+
+The Python companion to [Bezel Charts](https://github.com/ShazMoghaddam/bezel-charts). Pass in a DataFrame, a Series, a NumPy array or a plain list and get back a finished chart tile that shows up in Jupyter, saves as an `.svg` for a README, and drops into reports and slides. Zero dependencies.
+
+![A line chart of revenue against costs from January to September, with a launch note in May](https://raw.githubusercontent.com/ShazMoghaddam/bezel-charts/main/python/docs/line.svg)
+
+![A dark sparkline tile showing monthly revenue of £79k, up £37k since the start](https://raw.githubusercontent.com/ShazMoghaddam/bezel-charts/main/python/docs/spark.svg)
+
+- **Identical to the web components.** The renderers are a line-by-line port of the JavaScript ones, and the test suite checks they draw the same SVG, byte for byte.
+- **pandas friendly.** Pick columns with `x=` and `y=`. Dates, indexes and column names become labels and legends.
+- **Made for READMEs.** Every chart is a self-contained SVG with no scripts and no fonts to load, so GitHub shows it.
+- **No dependencies.** pandas and NumPy work when you have them, and are never required.
+
+## Install
+
+```sh
+pip install bezel-charts
+```
+
+Python 3.10 or newer.
+
+## Quick start
+
+```python
+import pandas as pd
+import bezel_charts as bc
+
+df = pd.DataFrame({
+    "month": pd.date_range("2026-01-01", periods=9, freq="MS"),
+    "Revenue": [42, 48, 45, 53, 61, 58, 66, 72, 79],
+    "Costs": [30, 31, 35, 34, 36, 41, 40, 43, 44],
+})
+
+bc.line(df, x="month", x_format="%b", heading="Revenue vs costs",
+        prefix="£", suffix="k", notes={"May": "Launch"}, theme="light")
+```
+
+In a notebook the chart appears as the cell's output. Anywhere else:
+
+```python
+chart = bc.spark(df["Revenue"], heading="Monthly revenue", prefix="£", suffix="k")
+chart.save("docs/revenue.svg")   # write an .svg file
+svg = str(chart)                 # or use the SVG string directly
+```
+
+Then in your README:
+
+```md
+![Monthly revenue](docs/revenue.svg)
+```
+
+## Charts in this release
+
+| Function | What it draws |
+| --- | --- |
+| `bc.spark(data)` | A sparkline with the latest value and the change since the start. |
+| `bc.line(data)` | A line chart with one or more series, a value axis, labels and a legend. |
+
+The other eight (bars and grouped bars, scatter with a trend line, rings, donut, gauge, progress and heatmap) are coming in the next releases. `bc.types` lists what's available.
+
+## Your data
+
+| You pass | You get |
+| --- | --- |
+| A list, tuple or NumPy array | One series. |
+| A pandas Series | One series, with the index as labels unless it's the default 0, 1, 2. |
+| A DataFrame | `y="col"` or `y=["a", "b"]` picks the series (by default every numeric column), `x="col"` the labels (by default the index). |
+| A dict like `{"Team A": [...], "Team B": [...]}` | One series per key, named in the legend. |
+| A list of lists | One series per inner list. |
+
+Dates become `2026-03-01`, or anything you like with `x_format="%b %Y"`. Missing values are drawn as 0, like the browser version, with a warning so they never go unnoticed. Call `.dropna()` or `.fillna()` first if you'd rather handle them yourself.
+
+## Options
+
+Every option from the [web components](https://github.com/ShazMoghaddam/bezel-charts#options-for-every-chart) works as a keyword argument. Use snake_case: `show-values` becomes `show_values=True`.
+
+| Option | Example | What it does |
+| --- | --- | --- |
+| `heading` | `heading="Sales"` | Small title at the top. |
+| `prefix`, `suffix` | `prefix="£"`, `suffix=" kWh"` | Around every number. |
+| `decimals` | `decimals=1` | Fixed decimal places. |
+| `compact` | `compact=True` | 15,500 becomes 15.5k. |
+| `stat` | `stat="average"` | Headline number: `last`, `total`, `average`, `max`, `min` or `none`. |
+| `delta`, `delta_label` | `delta="inverse"` | Change since the start. `inverse` makes a fall the good direction. |
+| `goal`, `goal_label` | `goal=50, goal_label="Target"` | A dashed target line. |
+| `notes` | `notes={"May": "Launch"}` | Notes on points, keyed by label or position. |
+| `show_values` | `show_values=True` | A label on every point. |
+| `straight` | `straight=True` | Straight segments instead of curves. |
+| `zero` | `zero=True` | Start the axis at zero (line). |
+| `labels`, `series` | `labels=["Q1", "Q2"]` | Set labels and series names by hand. |
+| `color` | `color=["#ff6600", "#0066ff"]` | Series colours. |
+| `theme` | `theme="light"` | `dark` (the default) or `light`. |
+| `width`, `height` | `width=560` | Size in pixels. The tile grows to fit its heading and headline. |
+| `frame`, `corners`, `background` | `frame="none"` | Drop the bezel, change the corner radius or the tile colour. |
+
+Numbers are formatted for `en-GB` by default (`1.5m`, `2bn`), or `lang="en-US"` for `1.5M`, `2B`. Other locales fall back to `en-GB` for now, with a warning.
+
+## Lower level
+
+`bc.to_svg(type, **options)` returns the static SVG string and `bc.render(type, **options)` returns it with the hover targets the browser uses. Both take the same options as the JavaScript functions of the same names, and accept a dict too:
+
+```python
+bc.to_svg("line", {"values": "1,2,3|3,2,1", "series": "A,B", "show-values": ""})
+```
+
+## How it stays in step with the JavaScript
+
+`scripts/py-fixtures.mjs` in the main repository runs the real JavaScript charts over a wide set of inputs (empty data, single values, negatives, huge and tiny numbers, notes, goals, both themes) and saves the SVG they draw. The Python tests render the same inputs and check the output is identical. CI regenerates the fixtures on every pull request, so a change to one version that isn't made to the other fails the build.
+
+## Development
+
+```sh
+git clone https://github.com/ShazMoghaddam/bezel-charts.git
+cd bezel-charts/python
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+After changing a JavaScript chart, run `npm run fixtures` from the repository root and commit `python/tests/fixtures`.
+
+## Licence
+
+[MIT](https://github.com/ShazMoghaddam/bezel-charts/blob/main/LICENSE). Designed and built by [Shaz Moghaddam](https://shazmoghaddam.github.io), London.

bezel_charts-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Bezel Charts for Python
+
+**Polished SVG charts straight from a pandas DataFrame.**
+
+The Python companion to [Bezel Charts](https://github.com/ShazMoghaddam/bezel-charts). Pass in a DataFrame, a Series, a NumPy array or a plain list and get back a finished chart tile that shows up in Jupyter, saves as an `.svg` for a README, and drops into reports and slides. Zero dependencies.
+
+![A line chart of revenue against costs from January to September, with a launch note in May](https://raw.githubusercontent.com/ShazMoghaddam/bezel-charts/main/python/docs/line.svg)
+
+![A dark sparkline tile showing monthly revenue of £79k, up £37k since the start](https://raw.githubusercontent.com/ShazMoghaddam/bezel-charts/main/python/docs/spark.svg)
+
+- **Identical to the web components.** The renderers are a line-by-line port of the JavaScript ones, and the test suite checks they draw the same SVG, byte for byte.
+- **pandas friendly.** Pick columns with `x=` and `y=`. Dates, indexes and column names become labels and legends.
+- **Made for READMEs.** Every chart is a self-contained SVG with no scripts and no fonts to load, so GitHub shows it.
+- **No dependencies.** pandas and NumPy work when you have them, and are never required.
+
+## Install
+
+```sh
+pip install bezel-charts
+```
+
+Python 3.10 or newer.
+
+## Quick start
+
+```python
+import pandas as pd
+import bezel_charts as bc
+
+df = pd.DataFrame({
+    "month": pd.date_range("2026-01-01", periods=9, freq="MS"),
+    "Revenue": [42, 48, 45, 53, 61, 58, 66, 72, 79],
+    "Costs": [30, 31, 35, 34, 36, 41, 40, 43, 44],
+})
+
+bc.line(df, x="month", x_format="%b", heading="Revenue vs costs",
+        prefix="£", suffix="k", notes={"May": "Launch"}, theme="light")
+```
+
+In a notebook the chart appears as the cell's output. Anywhere else:
+
+```python
+chart = bc.spark(df["Revenue"], heading="Monthly revenue", prefix="£", suffix="k")
+chart.save("docs/revenue.svg")   # write an .svg file
+svg = str(chart)                 # or use the SVG string directly
+```
+
+Then in your README:
+
+```md
+![Monthly revenue](docs/revenue.svg)
+```
+
+## Charts in this release
+
+| Function | What it draws |
+| --- | --- |
+| `bc.spark(data)` | A sparkline with the latest value and the change since the start. |
+| `bc.line(data)` | A line chart with one or more series, a value axis, labels and a legend. |
+
+The other eight (bars and grouped bars, scatter with a trend line, rings, donut, gauge, progress and heatmap) are coming in the next releases. `bc.types` lists what's available.
+
+## Your data
+
+| You pass | You get |
+| --- | --- |
+| A list, tuple or NumPy array | One series. |
+| A pandas Series | One series, with the index as labels unless it's the default 0, 1, 2. |
+| A DataFrame | `y="col"` or `y=["a", "b"]` picks the series (by default every numeric column), `x="col"` the labels (by default the index). |
+| A dict like `{"Team A": [...], "Team B": [...]}` | One series per key, named in the legend. |
+| A list of lists | One series per inner list. |
+
+Dates become `2026-03-01`, or anything you like with `x_format="%b %Y"`. Missing values are drawn as 0, like the browser version, with a warning so they never go unnoticed. Call `.dropna()` or `.fillna()` first if you'd rather handle them yourself.
+
+## Options
+
+Every option from the [web components](https://github.com/ShazMoghaddam/bezel-charts#options-for-every-chart) works as a keyword argument. Use snake_case: `show-values` becomes `show_values=True`.
+
+| Option | Example | What it does |
+| --- | --- | --- |
+| `heading` | `heading="Sales"` | Small title at the top. |
+| `prefix`, `suffix` | `prefix="£"`, `suffix=" kWh"` | Around every number. |
+| `decimals` | `decimals=1` | Fixed decimal places. |
+| `compact` | `compact=True` | 15,500 becomes 15.5k. |
+| `stat` | `stat="average"` | Headline number: `last`, `total`, `average`, `max`, `min` or `none`. |
+| `delta`, `delta_label` | `delta="inverse"` | Change since the start. `inverse` makes a fall the good direction. |
+| `goal`, `goal_label` | `goal=50, goal_label="Target"` | A dashed target line. |
+| `notes` | `notes={"May": "Launch"}` | Notes on points, keyed by label or position. |
+| `show_values` | `show_values=True` | A label on every point. |
+| `straight` | `straight=True` | Straight segments instead of curves. |
+| `zero` | `zero=True` | Start the axis at zero (line). |
+| `labels`, `series` | `labels=["Q1", "Q2"]` | Set labels and series names by hand. |
+| `color` | `color=["#ff6600", "#0066ff"]` | Series colours. |
+| `theme` | `theme="light"` | `dark` (the default) or `light`. |
+| `width`, `height` | `width=560` | Size in pixels. The tile grows to fit its heading and headline. |
+| `frame`, `corners`, `background` | `frame="none"` | Drop the bezel, change the corner radius or the tile colour. |
+
+Numbers are formatted for `en-GB` by default (`1.5m`, `2bn`), or `lang="en-US"` for `1.5M`, `2B`. Other locales fall back to `en-GB` for now, with a warning.
+
+## Lower level
+
+`bc.to_svg(type, **options)` returns the static SVG string and `bc.render(type, **options)` returns it with the hover targets the browser uses. Both take the same options as the JavaScript functions of the same names, and accept a dict too:
+
+```python
+bc.to_svg("line", {"values": "1,2,3|3,2,1", "series": "A,B", "show-values": ""})
+```
+
+## How it stays in step with the JavaScript
+
+`scripts/py-fixtures.mjs` in the main repository runs the real JavaScript charts over a wide set of inputs (empty data, single values, negatives, huge and tiny numbers, notes, goals, both themes) and saves the SVG they draw. The Python tests render the same inputs and check the output is identical. CI regenerates the fixtures on every pull request, so a change to one version that isn't made to the other fails the build.
+
+## Development
+
+```sh
+git clone https://github.com/ShazMoghaddam/bezel-charts.git
+cd bezel-charts/python
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+After changing a JavaScript chart, run `npm run fixtures` from the repository root and commit `python/tests/fixtures`.
+
+## Licence
+
+[MIT](https://github.com/ShazMoghaddam/bezel-charts/blob/main/LICENSE). Designed and built by [Shaz Moghaddam](https://shazmoghaddam.github.io), London.

bezel_charts-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bezel-charts"
+dynamic = ["version"]
+description = "Polished SVG charts from pandas DataFrames and Python lists, drawn exactly like the Bezel Charts web components. Zero dependencies."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Shaz Moghaddam" }]
+keywords = ["charts", "svg", "sparkline", "pandas", "jupyter", "data-visualization", "readme", "line-chart"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Jupyter",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Visualization",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pandas>=2", "numpy>=1.26"]
+
+[project.urls]
+Homepage = "https://shazmoghaddam.github.io/bezel-charts/site/"
+Documentation = "https://github.com/ShazMoghaddam/bezel-charts/tree/main/python#readme"
+Repository = "https://github.com/ShazMoghaddam/bezel-charts"
+Issues = "https://github.com/ShazMoghaddam/bezel-charts/issues"
+Changelog = "https://github.com/ShazMoghaddam/bezel-charts/blob/main/python/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/bezel_charts/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bezel_charts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

bezel_charts-0.1.0/src/bezel_charts/__init__.py

@@ -0,0 +1,120 @@
+"""Bezel Charts for Python.
+
+Polished SVG charts from pandas DataFrames, NumPy arrays and plain lists, drawn
+exactly like the Bezel Charts web components. Zero dependencies.
+
+    import bezel_charts as bc
+
+    bc.line(df, x="month", y=["sales", "costs"], heading="Sales", prefix="£")
+    bc.spark([4, 6, 5, 8, 9], heading="Signups").save("signups.svg")
+
+Created by Shaz Moghaddam, London. https://shazmoghaddam.github.io
+"""
+
+from __future__ import annotations
+
+import re
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+from . import _data
+from ._render import ALL_TYPES
+from ._render import render as _render
+from ._render import to_svg as _to_svg
+from ._tile import THEMES as themes
+from .charts import TYPES
+
+__version__ = "0.1.0"
+__all__ = ["Chart", "line", "render", "spark", "themes", "to_svg", "types", "__version__"]
+
+#: Chart types available in this release. The rest of the ten follow in later releases.
+types = list(TYPES)
+
+
+def render(type: str, options: dict | None = None, **kwargs: Any) -> str:
+    """Renders a chart to an SVG string with hover targets, the same as render() in JavaScript.
+
+    Options use the HTML attribute names in snake_case, kebab-case or camelCase:
+    ``show_values``, ``show-values`` and ``showValues`` all work.
+    """
+    return _render(type, {**(options or {}), **kwargs})
+
+
+def to_svg(type: str, options: dict | None = None, **kwargs: Any) -> str:
+    """Renders a clean static SVG, the same as toSVG() in JavaScript."""
+    return _to_svg(type, {**(options or {}), **kwargs})
+
+
+class Chart:
+    """A rendered chart. Shows itself in Jupyter, and converts to an SVG string with str()."""
+
+    def __init__(self, type: str, options: dict):
+        self.type = type
+        self.options = dict(options)
+        self.svg = _to_svg(type, self.options)
+        m = re.search(r'width="(\d+)" height="(\d+)"', self.svg)
+        self.width, self.height = (int(m.group(1)), int(m.group(2))) if m else (0, 0)
+
+    def __str__(self) -> str:
+        return self.svg
+
+    def __repr__(self) -> str:
+        return f"<bezel_charts.Chart {self.type} {self.width}x{self.height}>"
+
+    def _repr_svg_(self) -> str:
+        return self.svg
+
+    def save(self, path: str | PathLike) -> Path:
+        """Writes the chart as an .svg file and returns its path."""
+        p = Path(path)
+        if p.suffix.lower() != ".svg":
+            p = p.with_suffix(".svg") if p.suffix else p.with_name(p.name + ".svg")
+        p.write_text(self.svg, encoding="utf-8")
+        return p
+
+
+def _options(options: dict, values, names, lbls) -> dict:
+    out = dict(options)
+    if values is not None:
+        out["values"] = values
+    if names and "series" not in out:
+        out["series"] = names
+    if lbls and "labels" not in out:
+        out["labels"] = lbls
+    if "notes" in out:
+        out["notes"] = _data.notes(out["notes"])
+    return out
+
+
+def spark(data: Any = None, *, x: Any = None, y: Any = None, x_format: str | None = None, **options: Any) -> Chart:
+    """A sparkline: one series, its latest value and the change since the start.
+
+    ``data`` can be a list, a NumPy array, a pandas Series, or a DataFrame with ``y=`` naming the column.
+    Labels come from ``x=`` (a column), a non-default index, or ``labels=``. They show up in notes.
+    """
+    if data is None:
+        return Chart("spark", _options(options, None, None, None))
+    values, _, lbls = _data.prepare(data, x, y, x_format, single=True)
+    return Chart("spark", _options(options, values[0], None, lbls))
+
+
+def line(data: Any = None, *, x: Any = None, y: Any = None, x_format: str | None = None, **options: Any) -> Chart:
+    """A line chart with one or more series, a value axis and labels along the bottom.
+
+    ``data`` can be a DataFrame (``x=`` for labels, ``y=`` for one column or a list of them; by default
+    every numeric column), a Series, a dict of name to values, a list of lists, or a single list.
+    Dates are written as YYYY-MM-DD unless you pass ``x_format`` (for example ``"%b %Y"``).
+    """
+    if data is None:
+        return Chart("line", _options(options, None, None, None))
+    values, names, lbls = _data.prepare(data, x, y, x_format)
+    return Chart("line", _options(options, values, names, lbls))
+
+
+def __getattr__(name: str):
+    if name in ALL_TYPES:
+        raise AttributeError(
+            f"bezel_charts.{name}() is coming in a later release. Available now: {', '.join(types)}."
+        )
+    raise AttributeError(f"module 'bezel_charts' has no attribute {name!r}")

bezel_charts-0.1.0/src/bezel_charts/_data.py

@@ -0,0 +1,163 @@
+"""Turns pandas, NumPy and plain Python data into the options the renderers read.
+
+pandas and NumPy are never imported. Objects are recognised by what they can do
+(a .columns attribute, a .tolist() method), so the package stays dependency free.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+from collections.abc import Mapping
+
+from ._js import is_num, js_str, to_string
+
+
+def _is_frame(obj) -> bool:
+    return hasattr(obj, "columns") and hasattr(obj, "dtypes") and hasattr(obj, "__getitem__")
+
+
+def _is_series(obj) -> bool:
+    return hasattr(obj, "index") and hasattr(obj, "tolist") and not _is_frame(obj) and hasattr(obj, "name")
+
+
+def _to_list(obj) -> list:
+    if hasattr(obj, "tolist") and not isinstance(obj, str):
+        out = obj.tolist()
+        return out if isinstance(out, list) else [out]
+    if isinstance(obj, (str, bytes)):
+        raise TypeError("bezel_charts: pass numbers as a list, Series or array, not a string.")
+    return list(obj)
+
+
+def _is_default_index(index) -> bool:
+    return type(index).__name__ == "RangeIndex"
+
+
+def _number(v) -> float:
+    if hasattr(v, "item") and not isinstance(v, (list, tuple)):
+        try:
+            v = v.item()
+        except (TypeError, ValueError):
+            pass
+    if v is None or isinstance(v, bool):
+        return float("nan") if v is None else float(v)
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return float("nan")
+
+
+def numbers(seq, what: str = "values") -> list:
+    """Floats, with missing values drawn as 0 like the browser version, plus a warning."""
+    out, missing = [], 0
+    for v in _to_list(seq):
+        n = _number(v)
+        if not math.isfinite(n):
+            missing += 1
+            n = 0.0
+        out.append(n)
+    if missing:
+        warnings.warn(
+            f"bezel_charts: {missing} missing or non-numeric {what} drawn as 0. "
+            "Use .dropna() or .fillna() first if that is not what you want.",
+            stacklevel=4,
+        )
+    return out
+
+
+def label(v, x_format: str | None = None) -> str:
+    """A tidy text label: dates without midnight times, 2026.0 as 2026, missing as blank."""
+    if hasattr(v, "item") and not hasattr(v, "strftime"):
+        try:
+            v = v.item()
+        except (TypeError, ValueError):
+            pass
+    if v is None or (isinstance(v, float) and v != v):
+        return ""
+    if hasattr(v, "strftime"):
+        if type(v).__name__ == "NaTType":
+            return ""
+        if x_format:
+            return v.strftime(x_format)
+        if any(getattr(v, part, 0) for part in ("hour", "minute", "second")):
+            return v.strftime("%Y-%m-%d %H:%M")
+        return v.strftime("%Y-%m-%d") if hasattr(v, "day") else str(v)
+    if is_num(v):
+        return js_str(v)
+    return to_string(v)
+
+
+def labels(seq, x_format: str | None = None) -> list:
+    return [label(v, x_format) for v in _to_list(seq)]
+
+
+def notes(value):
+    """Accepts {"Mar": "Launch", 4: "Peak"} or [(key, text), ...] as well as the "key:text;..." string."""
+    if value is None or isinstance(value, str):
+        return value
+    items = value.items() if isinstance(value, Mapping) else value
+    parts = []
+    for key, text in items:
+        key_s, text_s = label(key), to_string(text)
+        if ":" in key_s or ";" in key_s or ";" in text_s:
+            raise ValueError(
+                f"bezel_charts: note {key_s!r}: {text_s!r} cannot contain ';', and its key cannot contain ':'."
+            )
+        parts.append(f"{key_s}:{text_s}")
+    return ";".join(parts)
+
+
+def _numeric_columns(df, exclude) -> list:
+    cols = []
+    for col, dtype in zip(df.columns, df.dtypes):
+        if col != exclude and getattr(dtype, "kind", "") in "iuf":
+            cols.append(col)
+    return cols
+
+
+def prepare(data, x=None, y=None, x_format=None, single=False):
+    """Returns (series values, series names or None, labels or None) for any supported input."""
+    if _is_frame(data):
+        if x is not None and x not in data.columns:
+            raise KeyError(f"bezel_charts: column {x!r} not found. Columns: {list(data.columns)}")
+        if y is None:
+            ys = _numeric_columns(data, x)
+            if not ys:
+                raise ValueError("bezel_charts: no numeric columns to plot. Pick one with y='column'.")
+        else:
+            ys = [y] if isinstance(y, (str, int)) or not hasattr(y, "__iter__") else list(y)
+        for col in ys:
+            if col not in data.columns:
+                raise KeyError(f"bezel_charts: column {col!r} not found. Columns: {list(data.columns)}")
+        if single and len(ys) > 1:
+            raise ValueError(f"bezel_charts: a sparkline draws one column. Choose one with y=, from {ys}.")
+        values = [numbers(data[col], f"values in {col!r}") for col in ys]
+        if x is not None:
+            lbls = labels(data[x], x_format)
+        elif not _is_default_index(data.index):
+            lbls = labels(data.index, x_format)
+        else:
+            lbls = None
+        names = [label(c) for c in ys] if len(ys) > 1 else None
+        return values, names, lbls
+
+    if x is not None or y is not None:
+        raise TypeError("bezel_charts: x= and y= pick DataFrame columns. For lists, pass labels= instead.")
+
+    if _is_series(data):
+        lbls = None if _is_default_index(data.index) else labels(data.index, x_format)
+        return [numbers(data)], None, lbls
+
+    if isinstance(data, Mapping):
+        if single and len(data) > 1:
+            raise ValueError("bezel_charts: a sparkline draws one series. Pass a single list.")
+        names = [label(k) for k in data]
+        return [numbers(v, f"values in {k!r}") for k, v in data.items()], names, None
+
+    rows = _to_list(data)
+    if rows and all(hasattr(r, "__iter__") and not isinstance(r, str) for r in rows):
+        if single and len(rows) > 1:
+            raise ValueError("bezel_charts: a sparkline draws one series. Pass a single list.")
+        return [numbers(r) for r in rows], None, None
+    return [numbers(rows)], None, None