Getting Started with Charted

A 5-minute guide to creating beautiful SVG charts with zero dependencies.

Installation

pip install charted

Quick Start

Create your first chart in under 30 seconds:

from charted import BarChart

# Simple bar chart
chart = BarChart(data=[120, 180, 210], labels=["Q1", "Q2", "Q3"])
chart.save("sales.svg")

That’s it! You now have a sales.svg file ready to use in presentations, websites, or documentation. Charted supports 14 chart types:

  • BarChart - Horizontal bars (comparing categories)

  • ColumnChart - Vertical bars (time series, distributions)

  • LineChart - Line graphs (trends over time)

  • ScatterChart - Scatter plots (correlations, distributions)

  • PieChart - Pie/doughnut charts (proportions)

  • AreaChart - Filled line charts (cumulative trends)

  • RadarChart - Radar/spider charts (multivariate comparison)

  • BoxPlot - Box-and-whisker plots (distribution summaries)

  • Histogram - Frequency distributions

  • HeatmapChart - Color-coded matrices

  • GanttChart - Project timelines

  • BubbleChart - Scatter plots with a third (size) dimension

  • ComboChart - Mixed column and line series on shared axes

  • PolarAreaChart - Pie variant where slice radius encodes value

Basic Usage

Single Series

from charted import BarChart, ColumnChart, LineChart, PieChart

# Bar chart
bar = BarChart(
    data=[120, 180, 210, 150],
    labels=["Q1", "Q2", "Q3", "Q4"],
    title="Sales by Quarter"
)
bar.save("bar.svg")

# Column chart
column = ColumnChart(
    data=[120, 180, 210, 150],
    labels=["Q1", "Q2", "Q3", "Q4"],
    title="Sales by Quarter"
)
column.save("column.svg")

# Line chart
line = LineChart(
    data=[120, 180, 210, 150],
    labels=["Q1", "Q2", "Q3", "Q4"],
    title="Sales Trend"
)
line.save("line.svg")

# Pie chart
pie = PieChart(
    data=[120, 180, 210, 150],
    labels=["Q1", "Q2", "Q3", "Q4"],
    title="Sales Distribution"
)
pie.save("pie.svg")

Multi-Series

from charted import BarChart, ColumnChart

# Multiple data series
data = [
    [120, 180, 210, 150],  # 2023
    [130, 190, 220, 160],  # 2024
]

bar = BarChart(
    data=data,
    labels=["Q1", "Q2", "Q3", "Q4"],
    title="Sales Comparison",
    series_names=["2023", "2024"]
)
bar.save("multi_bar.svg")

column = ColumnChart(
    data=data,
    labels=["Q1", "Q2", "Q3", "Q4"],
    title="Sales Comparison",
    series_names=["2023", "2024"]
)
column.save("multi_column.svg")

Stacked Charts

from charted import BarChart, ColumnChart

# Stacked bar chart
stacked_bar = BarChart(
    data=[[30, 50, 40], [90, 130, 170]],
    labels=["Q1", "Q2", "Q3"],
    title="Sales by Region",
    series_names=["North", "South"],
    x_stacked=True
)
stacked_bar.save("stacked_bar.svg")

# Stacked column chart
stacked_column = ColumnChart(
    data=[[30, 50, 40], [90, 130, 170]],
    labels=["Q1", "Q2", "Q3"],
    title="Sales by Region",
    series_names=["North", "South"],
    y_stacked=True
)
stacked_column.save("stacked_column.svg")

Loading Data from Files

CSV/TSV Files

from charted import BarChart, load_csv

# Load data from CSV
x, y, labels = load_csv("sales.csv", x_col="Quarter", y_col="Revenue")

# Create chart
chart = BarChart(data=y, labels=x, title=labels[0])
chart.save("sales.svg")

CSV Format Example:

Quarter,Revenue
Q1,120
Q2,180
Q3,210
Q4,150

JSON Files

from charted import BarChart, load_json

# Load data from JSON
x, y, labels = load_json("sales.json")

# Create chart
chart = BarChart(data=y, labels=x, title=labels[0])
chart.save("sales.svg")

JSON Format Examples:

Simple array:

[120, 180, 210, 150]

Array of objects:

[
  {"label": "Q1", "value": 120},
  {"label": "Q2", "value": 180},
  {"label": "Q3", "value": 210},
  {"label": "Q4", "value": 150}
]

Object with data and labels:

{
  "data": [120, 180, 210, 150],
  "labels": ["Q1", "Q2", "Q3", "Q4"],
  "title": "Sales by Quarter"
}

Jupyter Notebook Integration

Charts display inline automatically:

from charted import BarChart

# In Jupyter, this renders inline
chart = BarChart(
    data=[120, 180, 210, 150],
    labels=["Q1", "Q2", "Q3", "Q4"],
    title="Sales by Quarter"
)
chart  # Last expression renders the chart

Markdown Integration

Embed charts in documentation:

from charted import BarChart, chart_to_markdown

# Create and save chart
chart = BarChart(data=[120, 180, 210], labels=["Q1", "Q2", "Q3"])
chart.save("docs/examples/sales.svg")

# Generate markdown
md = chart_to_markdown("docs/examples/sales.svg", title="Sales Chart", width="600px")
print(md)
# Output: ![Sales Chart](docs/examples/sales.svg){width=600px}

Or use data URLs for inline embedding:

from charted import BarChart, chart_to_data_url

# Generate data URL
url = chart_to_data_url("chart.svg")
md = f"![chart]({url})"

Using Chart Methods

The new Chart class methods provide a more convenient API:

from charted import BarChart

# Create chart
chart = BarChart(data=[120, 180, 210], labels=["Q1", "Q2", "Q3"], title="Sales")

# Get markdown with data URL (inline embedding)
md = chart.to_markdown()
print(md)
# Output: ![Sales](data:image/svg+xml,{encoded_svg})

# Get markdown with file path
chart.save("docs/examples/sales.svg")
md = chart.to_markdown(path="docs/examples/sales.svg")
print(md)
# Output: ![Sales](docs/examples/sales.svg)

# Get raw SVG
svg = chart.to_svg()
print(svg[:50])
# Output: <svg xmlns="http://www.w3.org/2000/svg" ...

# HTML representation (for Jupyter/web frameworks)
html = chart._repr_html_()

Using the Base Chart Class

The Chart base class provides a unified API for all chart types:

from charted import Chart, BarChart

# Create a chart using the base class
chart = Chart(
    data=[120, 180, 210, 150],
    labels=["Q1", "Q2", "Q3", "Q4"],
    title="Sales by Quarter",
    chart_type="bar"  # or "column", "line", "scatter", "pie"
)
chart.save("sales.svg")

# Access chart methods
svg = chart.to_svg()
md = chart.to_markdown()
html = chart._repr_html_()

This is useful when you want a consistent interface across different chart types.

Advanced API Usage

Chart Class Methods

The base Chart class provides several useful methods for exporting and embedding:

from charted import BarChart

chart = BarChart(data=[120, 180, 210], labels=["Q1", "Q2", "Q3"], title="Sales")

# Save to file
chart.save("output.svg")

# Get raw SVG string
svg_content = chart.to_svg()

# Get markdown with file reference
md = chart.to_markdown(path="output.svg")
# Output: ![Sales](output.svg)

# Get markdown with inline data URL (no external file needed)
md_inline = chart.to_markdown()
# Output: ![Sales](data:image/svg+xml;base64,PHN2Zy4uLg==)

# Get HTML snippet
html = chart.to_html()
# Output: <figure><svg xmlns="http://www.w3.org/2000/svg" ...>

# Jupyter integration (automatic via _repr_html_)
chart  # In Jupyter notebook, renders the chart inline

Advanced Styling with series_styles

Override styling for individual series or chart elements:

from charted import BarChart, LineChart

# Bar chart with highlighted series
bar = BarChart(
    data=[[120, 180, 210], [130, 190, 220]],
    labels=["Q1", "Q2", "Q3"],
    series_names=["2023", "2024"],
    series_styles=[
        None,  # Use theme default for 2023
        {
            "fill": "#ff6b6b",      # Red fill for 2024
            "stroke_width": 3.0,    # Thicker border
        }
    ]
)

# Line chart with custom markers
line = LineChart(
    data=[120, 180, 210, 150],
    labels=["Q1", "Q2", "Q3", "Q4"],
    series_styles=[
        {
            "marker_shape": "square",  # Square markers instead of circles
            "marker_size": 6.0,        # Larger markers
            "stroke_width": 2.5,       # Thicker line
            "stroke_opacity": 0.8,     # Semi-transparent line
        }
    ]
)

Font Configuration

Charted bundles 8 professional fonts. Configure globally via .chartedrc.toml:

# .chartedrc.toml
font = "Roboto"           # Default font family
font_size = 12            # Body text size (pt)
title_font_size = 16      # Title size (pt)

Available fonts: Helvetica, Arial, Roboto, Inter, Lato, JetBrains Mono, Fira Code, Courier.

Per-chart font override:

chart = BarChart(
    data=[120, 180, 210],
    labels=["Q1", "Q2", "Q3"],
    font_family="JetBrains Mono",  # Override default
    font_size=14
)

CLI Usage

Create charts from the command line without writing Python:

# Basic bar chart from CSV
python -m charted create bar sales.svg --data sales.csv
python -m charted create bar sales.svg --data sales.csv

# Multi-series column chart
python -m charted create column comparison.svg --data sales.csv

# Use short flag
python -m charted create line trend.svg -d trend.csv

# Batch process directory (infers chart type from filename)
python -m charted batch ./data ./output

# Force specific chart type for all files
python -m charted batch ./data ./output --chart-type line

# Use custom config
python -m charted create bar sales.svg --data sales.csv --config .chartedrc.toml

Data Formats:

CSV: first column is labels, remaining columns are data series:

Quarter,Q1,Q2,Q3,Q4
Sales,120,180,210,150
Profit,80,120,140,100

JSON: supports arrays, arrays of objects, or structured objects:

[120, 180, 210, 150]

[{"label": "Q1", "value": 120}, {"label": "Q2", "value": 180}]

{"data": [120, 180], "labels": ["Q1", "Q2"], "title": "Sales"}

Batch Filename Pattern:

Files should contain chart type keywords (bar, column, line, pie, scatter) in the filename. The batch command infers chart type from the filename, or you can override with --chart-type.

HTML Embedding

Charts are SVG, so they embed directly in HTML:

<!-- Direct include -->
<figure>
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 400">
    <!-- chart content -->
  </svg>
  <figcaption>Sales by Quarter</figcaption>
</figure>

<!-- Responsive with CSS -->
<style>
  figure chart {
    width: 100%;
    height: auto;
  }
</style>

<!-- Inline data URL for single-file HTML -->
<img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmci...">

Markdown Documentation

Embed charts in READMEs and docs:

from charted import BarChart, chart_to_markdown

chart = BarChart(data=[120, 180, 210], labels=["Q1", "Q2", "Q3"])
chart.save("docs/sales.svg")

# Simple reference
md = chart_to_markdown("docs/sales.svg", title="Sales Chart")
# ![Sales Chart](docs/sales.svg)

# With dimensions
md = chart_to_markdown("docs/sales.svg", title="Sales", width="100%", max_width="600px")
# ![Sales](docs/sales.svg){width=100% max-width=600px}

Error Handling

Charted provides custom exceptions for common issues:

from charted import BarChart
from charted.utils.exceptions import ChartError, DataLoadError

try:
    chart = BarChart(data=[], labels=[])  # Empty data
except ChartError as e:
    print(f"Chart error: {e}")

try:
    from charted import load_csv
    x, y, labels = load_csv("nonexistent.csv")
except DataLoadError as e:
    print(f"Data load error: {e}")

Customization

Themes

from charted import BarChart
from charted.utils.themes import Theme

# Use built-in theme
chart = BarChart(
    data=[120, 180, 210],
    labels=["Q1", "Q2", "Q3"],
    theme=Theme.DARK  # or Theme.LIGHT, Theme.COLORFUL
)
chart.save("dark_theme.svg")

# Custom theme
custom_theme = Theme(
    background_color="#ffffff",
    text_color="#333333",
    grid_color="#eeeeee",
    primary_color="#3498db",
    secondary_color="#2ecc71"
)
chart = BarChart(
    data=[120, 180, 210],
    labels=["Q1", "Q2", "Q3"],
    theme=custom_theme
)
chart.save("custom_theme.svg")

Dimensions

from charted import BarChart

# Custom size
chart = BarChart(
    data=[120, 180, 210],
    labels=["Q1", "Q2", "Q3"],
    width=800,
    height=400
)
chart.save("wide_chart.svg")

Colors

from charted import BarChart

# Custom colors
chart = BarChart(
    data=[120, 180, 210],
    labels=["Q1", "Q2", "Q3"],
    theme=Theme(
        primary_color="#e74c3c",
        secondary_color="#f39c12"
    )
)
chart.save("custom_colors.svg")

CLI Usage

Charted also has a command-line interface:

Next Steps

  • API Reference - Complete documentation for all chart classes

  • Themes - Learn about theme customization

  • Configuration - Configure charted for your project

Common Patterns

Percentages (Pie Chart)

from charted import PieChart

# Proportions that sum to 100%
pie = PieChart(
    data=[40, 35, 15, 10],
    labels=["Product A", "Product B", "Product C", "Product D"],
    title="Market Share"
)
pie.save("market_share.svg")

Time Series (Line Chart)

from charted import LineChart

# Time-based data
line = LineChart(
    data=[120, 135, 150, 165, 180, 195],
    labels=["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
    title="Monthly Growth"
)
line.save("growth.svg")

Comparison (Column Chart)

from charted import ColumnChart

# Side-by-side comparison
data = [
    [120, 180, 210],  # 2023
    [130, 190, 220],  # 2024
]

column = ColumnChart(
    data=data,
    labels=["Q1", "Q2", "Q3"],
    title="Year-over-Year Comparison",
    series_names=["2023", "2024"]
)
column.save("comparison.svg")

Troubleshooting

No data error

# ❌ Wrong - empty data
chart = BarChart(data=[], labels=[])

# ✅ Right - provide data
chart = BarChart(data=[1, 2, 3], labels=["A", "B", "C"])

Invalid CSV columns

# ❌ Wrong - column doesn't exist
x, y, labels = load_csv("data.csv", x_col="quarter", y_col="revenue")

# ✅ Right - use exact column names
x, y, labels = load_csv("data.csv", x_col="Quarter", y_col="Revenue")

Chart doesn’t display in Jupyter

# ✅ Make sure charted is installed
pip install charted

# ✅ Use the chart object as the last line
chart = BarChart(data=[1, 2, 3], labels=["A", "B", "C"])
chart  # This renders inline

Support

  • Documentation: https://charted.readthedocs.io

  • GitHub: https://github.com/peepecat/charted

  • Issues: https://github.com/peepecat/charted/issues