charted

charted 是一个面向 Python 和 AI 智能体的零依赖图表生成库，核心目标是用最简单的方式把数据变成图片：传入一组数字，返回一张图表，不需要 numpy、pandas 或配置文件。它受 mermaid.js 启发，用纯 Python 从数据结构生成可定制的 SVG 图表。

主要能力

• 零运行时依赖：核心库为纯 Python，不依赖 numpy/pandas。PNG 导出和 MCP 服务器属于可选附加功能，会引入各自的依赖，基础库保持纯净。
• 15 种图表类型：Bar、Column、Line、Scatter、Pie、Area、Radar、Box Plot、Histogram、Heatmap、Gantt、Bubble、Combo、Polar Area、Sankey。
• 多系列支持：支持堆叠、并排、分组布局。
• 负值处理：具备正确的零基线计算。
• 输出格式：原生 SVG；PNG 通过可选的 cairosvg 实现（pip install charted[png]）。
• 主题系统：3 个内置预设（light、dark、high-contrast）加自定义主题组合。
• 逐系列样式：通过 SeriesStyle 构建器进行细粒度控制。
• 数据加载：内置 CSV/JSON 解析器。
• Markdown 导出：生成可直接嵌入的 markdown 片段。
• 命令行工具：无需编写 Python 代码即可创建图表。
• Jupyter 支持：图表自动内联渲染。
• 基础 Chart 类：统一 API，可在运行时动态选择图表类型。

使用方式 所有图表类型共享同一套简单接口：传入数据、标签、尺寸和标题。例如：

from charted import BarChart chart = BarChart(data=[1, 2, 3], labels=["A", "B", "C"], title="My Chart") chart.save("chart.svg")

命令行用法（无需写 Python）：

python -m charted --type bar --data "1,2,3" --labels "A,B,C" --title "My Chart" --output chart.svg

--title、--width、--height 在同时传入 --config 文件时会覆盖文件中的同名值。

CSV 格式（默认）：第一列是 x 轴标签，其余每列是一个数据系列。宽表 CSV 可用 --transpose：如果 CSV 是横向布局，每行一个系列、x 值在表头，则传入 --transpose；角落单元格被忽略，表头其余部分成为 x 轴标签，后续每行是以首单元格命名的系列。不加 --transpose 会导致坐标轴颠倒，因此该标志是显式指定而非自动猜测。

MCP 服务器（AI 智能体集成） charted 内置 MCP 服务器，让 AI 智能体（Claude Code、Cursor 等）无需编写 Python 即可生成图表。可用 uvx 免安装运行：

uvx charted[mcp]

该命令会把带 MCP 附加功能的 charted 拉取到临时环境，并通过 stdio 启动服务器。服务器暴露 create_chart、list_chart_types、list_themes、chart_from_csv 四个工具。create_chart 和 chart_from_csv 接受 output_format 参数，可选 svg、html、data_url 或 png；当 output_format="png" 时返回栅格化 PNG 图像，智能体可在聊天界面内联展示图表，而不必转发原始 SVG 标记。mcp 附加功能包含 cairosvg，因此 PNG 输出开箱即用。PNG 栅格化需要 cairo 系统库，在 Debian/Ubuntu 上可用 apt install libcairo2 安装。

Claude 技能 可用一行命令安装 chart Skill。

Sankey 图 节点按 alignment 分配到列，然后经过多次迭代松弛，使相连节点对齐、缎带交叉尽可能少。链接粗细与流量值成比例；每个节点堆叠的宽度之和等于该节点高度。链接以 (source, target, value) 元组或 {"source", "target", "value"} 字典传入；端点可以是节点名称或索引。密集列中的节点标签会在垂直方向错开，避免重叠。alignment 选项控制节点分配到列的方式：justify（默认，类似 d3-sankey）把所有汇点推到最后一列；left 让每个节点保持自身深度；right 按到汇点的距离对齐；center 保留左侧并将源点固定在第一列。对于漏斗/流失数据，应使用 alignment="left"，因为漏斗的流失汇点分布在多个不同深度，默认 justify 会把它们全部拉到同一个高列，压扁漏斗形状。

主题与样式 三个内置预设（light、dark、high-contrast）加自定义主题组合。可通过 chart.style(**kwargs) 应用主题覆盖并返回图表以支持链式调用，例如设置 background_color 或 legend_font_size。resolve_palette(name) 可将内置调色板名称转换为十六进制颜色列表，用于 colors= 参数。内置调色板名称包括 default、viridis、ocean、categorical、rainbow、monochrome、pastel、sunset、forest、inferno 以及色盲安全的 okabe-ito。

其他公开 API

• 自动图表选择：auto(data, **kwargs) 根据数据形状选择图表类型（一维变柱状图或饼图，矩阵变热力图等）并返回图表实例；auto_size(data, width, height) 返回未显式指定尺寸时数据集会缩放到的 (width, height)。
• 从字典或 DataFrame 构建：from_dict({"data": ..., "chart_type": ...}) 从配置字典构建图表；from_dataframe(df) 接受 pandas DataFrame（或未安装 pandas 时的列到列表的普通字典），使用第一个数值列作为数据，索引或第一个字符串列作为标签。
• 内联与 data URL 嵌入：inline_svg(path) 将 SVG 文件读回为字符串，用于嵌入 HTML 或 notebook；chart_to_data_url(path) 返回 URL 编码的 data:image/svg+xml,... URI，可直接放入 <img> 标签或 markdown 图片。
• 保存与恢复配置：chart.to_config() 将图表序列化为 JSON 友好的字典（尺寸、数据、标签、比例尺、参考线、注释等）；Chart.from_config(config, **overrides) 从该字典重建图表，关键字覆盖会合并到顶层，便于只调整一个值而无需重建整个配置。
• HTML 悬停提示：chart.to_html(tooltips=True) 为每个数据标记附加原生 SVG <title>，浏览器无需 JavaScript 即可显示内置悬停提示。仅影响 HTML 输出，to_svg() 和 save() 不变。
• 参考线：传入 reference_lines=[{"value": 50, "axis": "y", "label": "Target"}] 可在某值处绘制带可选标签的水平或垂直线。axis 为 "y" 表示水平线（默认），"x" 表示垂直线。
• 注释：传入 annotations=[...]，使用 LineAnnotation、BoxAnnotation 或 LabelAnnotation 以线条、阴影区域或文本标记图表。
• 对数与时间比例尺：传入 x_scale= 或 y_scale= 为 "log" 表示对数轴，"time" 表示时间轴（接受日期、日期时间或 ISO 日期字符串作为 x 值）。默认是 "linear"。柱状图或柱形图的值轴拒绝使用对数与时间比例尺，因为这些图从零基线填充。

安装与依赖说明

• 库使用（在代码中导入）：使用 uv add 或 pip install 安装。
• CLI 或 MCP 服务器（独立工具，无需项目安装）：可用 uvx 或 pipx。注意：uvx/pipx 安装的包运行在独立隔离环境中，无法导入到项目代码。
• 可选附加功能会添加依赖，核心库保持零依赖。
• PNG 导出：使用 .png 扩展名直接保存为 PNG，需要 cairosvg；若未安装，save() 会抛出带安装说明的 ImportError。

限制与注意事项

• 核心库零依赖，但 PNG 导出和 MCP 服务器为可选附加功能，会引入额外依赖。
• PNG 栅格化需要 cairo 系统库。
• 柱状图/柱形图的值轴不支持对数与时间比例尺。
• 宽表 CSV 需要显式传入 --transpose，否则坐标轴会颠倒。
• 漏斗/流失数据需使用 alignment="left"，否则默认 justify 会压扁漏斗形状。
• uvx/pipx 安装的包无法被项目代码导入。

完整文档包括配置参考。charted 通过 fonts/definitions/ 中的预定义字体度量避免使用 tkinter，可生成新的字体定义。