Chart methods

Chart methods & global config

Every Chart object returned by SeraPlot supports the same fluent API. Set defaults once with sp.config() and tweak per chart with chainable methods. All methods return a new Chart, so chaining is always safe.

Fluent APIGlobal + per-chart override60+ chart typesDoc-as-code: every card below is generated from the Rust source

1Global config 2Themes 3Chart methods 4Magic properties 5Annotations (cross-chart) 6Composers (Grid + Slideshow)

Global config

Set defaults once. Every chart created afterwards inherits this configuration automatically.

💾Persist aliases across sessions

sp.config.add_alias("bar", "barchart")
sp.config.add_alias("line", "linechart")
sp.config.save()  # writes to ~/.seraplot/config.json

import seraplot as sp  # aliases are auto-loaded from ~/.seraplot/config.json

Themes

Curated presets that combine palette, background and gridlines.

Theme	Mood
`"dark"`	High-contrast dark dashboard
`"light"`	Soft pastel light backdrop
`"scientific"`	Publication-style monochrome
`"apple"`	Glassy iOS-inspired palette
`"notion"`	Calm Notion-style neutrals
`"minimal"`	Bare lines, no chrome
`"neon"`	Vibrant cyberpunk neons

sp.config(theme=...)global

Apply a theme globally to all charts created after this call. Combine with any other config keys.

sp.config(theme="dark", gridlines=True, font="Inter")
chart = sp.bar("Sales", labels=["Q1","Q2","Q3"], values=[120,180,150])
chart.show()

Tip: Call sp.reset_theme() to return to the framework default at any point.

Chart methods

Generated from #[sera_doc] in the Rust source

Every card below is generated straight from the #[sera_doc(...)] annotation on the matching Rust method — name, parameters and description always match the actual implementation.

Magic properties

.html propertyread-only

Read the full HTML payload as a string.

src = chart.html

len(chart) → intproperty

Returns the size of the HTML payload in bytes.

print(len(chart))

bool(chart) → boolproperty

True when the chart has rendered output.

if chart:
    chart.show()

Annotations (cross-chart)

SVG overlays inherited by every plot

annotations=[...] (kwarg)newglobal

Pass a list of annotation dicts to any chart builder. Coordinates default to fractional canvas space (0.0–1.0); set "frac": false to use raw pixels. Supported kind: "hline", "vline", "line", "arrow", "rect", "text".

chart = sp.line(
    "Sales", labels=months, values=sales,
    annotations=[
        {"kind":"hline", "y":0.5, "color":"#22c55e", "dash":"6 4", "text":"Target"},
        {"kind":"vline", "x":0.62, "color":"#f59e0b", "text":"Launch"},
        {"kind":"rect",  "x":0.05, "y":0.65, "x2":0.40, "y2":0.92,
                         "color":"#6366f1", "fill":"#6366f1", "opacity":0.10},
        {"kind":"arrow", "x":0.45, "y":0.30, "x2":0.85, "y2":0.18, "color":"#ef4444"},
        {"kind":"text",  "x":0.46, "y":0.28, "text":"Outlier", "color":"#ef4444"},
    ],
)

Annotation fields

Every annotation accepts the same shape:

Field	Type	Default	Description
`kind`	str	required	`hline` / `vline` / `line` / `arrow` / `rect` / `text`
`x`, `y`	float	0.5	Anchor point (frac of canvas if `frac=True`, pixels otherwise)
`x2`, `y2`	float	1.0	End point for line / arrow / rect
`color`	str	`"#ef4444"`	Stroke / text color (CSS)
`fill`	str	`"none"`	Fill color (rect only)
`stroke_width`	float	1.5	Stroke width
`dash`	str	`""`	SVG dash array, e.g. `"6 4"`
`opacity`	float	1.0	0.0 - 1.0
`text`	str	None	Optional label rendered next to the primitive
`font_size`	float	11.0	Label font size
`frac`	bool	true	Coordinate space: fractional (0-1) or pixel

Tip: Annotations apply uniformly to every 2D and 3D chart through the apply_annotations() hook - no per-chart wiring required.

Composers (Grid + Slideshow)

Group charts into stories

⊞

sp.grid() alias: sp.build_grid

Compose any number of pre-built charts into a responsive CSS-grid, each chart isolated in its own iframe.

chartslist[Chart]Charts to arrange

colsint = 3Number of columns

gapint = 16Gap between cells in px

bg_colorstrGrid background

titlestr = ""Optional header title

cell_heightint | NoneOverride each cell height

bar  = sp.bar("Sales", labels=["Q1","Q2","Q3","Q4"], values=[120,180,150,210])
line = sp.line("Trend", labels=months, values=sales)
pie  = sp.pie("Mix", labels=["A","B","C"], values=[40,35,25])
sp.grid([bar, line, pie], cols=3, gap=14, title="Dashboard").show()

▶

sp.build_slideshow() navigable HTML carousel

Build a navigable HTML carousel with prev / next buttons and an auto-advance progress bar — tell a story without a slide deck.

chartslist[Chart]Ordered slide list

interval_msint = 2500Auto-advance delay in ms

titlestr = ""Carousel title

widthint = 900Output width in px

heightint = 520Output height in px

slides = [sp.bar(f"Slide {i+1}", labels=["A","B"], values=[i, i+1]) for i in range(4)]
sp.build_slideshow(slides, interval_ms=2200, title="Quarterly Story").show()

Méthodes & configuration globale

Tout objet Chart renvoyé par SeraPlot expose la même API fluide. Définis les valeurs par défaut une fois avec sp.config(), ajuste chart par chart avec des méthodes chaînées. Toutes les méthodes retournent un nouveau Chart : le chaînage est toujours sûr.

API fluideGlobal + override par chart60+ types de graphiquesDoc-as-code : chaque carte ci-dessous vient du code Rust

1Configuration globale 2Thèmes 3Méthodes de Chart 4Propriétés magiques 5Annotations (transversales) 6Composers (Grid + Slideshow)

Configuration globale

Définis les défauts une fois. Tous les graphiques créés ensuite héritent automatiquement de cette configuration.

💾Persister les aliases entre les sessions

sp.config.add_alias("bar", "barchart")
sp.config.add_alias("line", "linechart")
sp.config.save()  # écrit dans ~/.seraplot/config.json

import seraplot as sp  # les aliases sont rechargés automatiquement

Thèmes

Préréglages combinant palette, fond et grille.

Thème	Ambiance
`"dark"`	Tableau de bord sombre haut contraste
`"light"`	Fond clair pastel doux
`"scientific"`	Style publication monochrome
`"apple"`	Palette inspirée iOS, glassy
`"notion"`	Neutres calmes type Notion
`"minimal"`	Lignes pures, sans décoration
`"neon"`	Néons cyberpunk vibrants

sp.config(theme=...)global

Applique un thème à tous les graphiques créés après cet appel. Combinable avec n'importe quelle autre clé config.

sp.config(theme="dark", gridlines=True, font="Inter")
chart = sp.bar("Ventes", labels=["Q1","Q2","Q3"], values=[120,180,150])
chart.show()

Astuce : Appelle sp.reset_theme() pour revenir au thème par défaut du framework.

Méthodes de Chart

Générées depuis #[sera_doc] dans le code Rust

Chaque carte ci-dessous est générée directement depuis l'annotation #[sera_doc(...)] de la méthode Rust correspondante — nom, paramètres et description correspondent toujours à l'implémentation réelle.

Propriétés magiques

.html propertylecture seule

Lit le HTML complet sous forme de chaîne.

src = chart.html

len(chart) → intproperty

Renvoie la taille du HTML en octets.

print(len(chart))

bool(chart) → boolproperty

True si le chart a un rendu.

if chart:
    chart.show()

Annotations (transversales)

Surcouches SVG héritées par tous les plots

annotations=[...] (kwarg)nouveauglobal

Passe une liste de dicts à n'importe quel builder. Coordonnées fractionnaires par défaut (0.0–1.0) ; mets "frac": false pour des pixels. Valeurs de kind : "hline", "vline", "line", "arrow", "rect", "text".

chart = sp.line(
    "Ventes", labels=mois, values=ventes,
    annotations=[
        {"kind":"hline", "y":0.5, "color":"#22c55e", "dash":"6 4", "text":"Cible"},
        {"kind":"vline", "x":0.62, "color":"#f59e0b", "text":"Lancement"},
        {"kind":"rect",  "x":0.05, "y":0.65, "x2":0.40, "y2":0.92,
                         "color":"#6366f1", "fill":"#6366f1", "opacity":0.10},
        {"kind":"arrow", "x":0.45, "y":0.30, "x2":0.85, "y2":0.18, "color":"#ef4444"},
        {"kind":"text",  "x":0.46, "y":0.28, "text":"Outlier", "color":"#ef4444"},
    ],
)

Champs d'annotation

Toutes les annotations partagent la même structure :

Champ	Type	Défaut	Description
`kind`	str	requis	`hline` / `vline` / `line` / `arrow` / `rect` / `text`
`x`, `y`	float	0.5	Point d'ancrage (frac du canvas si `frac=True`, pixels sinon)
`x2`, `y2`	float	1.0	Point final pour line / arrow / rect
`color`	str	`"#ef4444"`	Couleur de trait / texte (CSS)
`fill`	str	`"none"`	Couleur de remplissage (rect uniquement)
`stroke_width`	float	1.5	Épaisseur du trait
`dash`	str	`""`	SVG dash array, ex. `"6 4"`
`opacity`	float	1.0	0.0 - 1.0
`text`	str	None	Étiquette optionnelle à côté du primitif
`font_size`	float	11.0	Taille de la police de l'étiquette
`frac`	bool	true	Espace de coordonnées : fractionnaire (0-1) ou pixel

Astuce : les annotations s'appliquent uniformément à tous les charts 2D et 3D via le hook apply_annotations() — aucun branchement par chart requis.

Composers (Grid + Slideshow)

Regroupe des charts en histoires

⊞

sp.grid() alias : sp.build_grid

Assemble N charts déjà construits dans une grille CSS responsive, chaque chart isolé dans son iframe.

chartslist[Chart]Charts à disposer

colsint = 3Nombre de colonnes

gapint = 16Espacement en px

bg_colorstrFond de la grille

titlestr = ""Titre en en-tête

cell_heightint | NoneHauteur de chaque cellule

bar  = sp.bar("Ventes-Q", labels=["Q1","Q2","Q3","Q4"], values=[120,180,150,210])
line = sp.line("Tendance", labels=mois, values=ventes)
pie  = sp.pie("Mix", labels=["A","B","C"], values=[40,35,25])
sp.grid([bar, line, pie], cols=3, gap=14, title="Tableau de bord").show()

▶

sp.build_slideshow() carrousel HTML navigable

Construit un carrousel HTML avec boutons précédent / suivant et barre de progression — parfait pour raconter une histoire.

chartslist[Chart]Slides dans l'ordre

interval_msint = 2500Délai d'avancement auto (ms)

titlestr = ""Titre du carrousel

widthint = 900Largeur en px

heightint = 520Hauteur en px

slides = [sp.bar(f"Slide {i+1}", labels=["A","B"], values=[i, i+1]) for i in range(4)]
sp.build_slideshow(slides, interval_ms=2200, title="Histoire trimestrielle").show()

Keyboard shortcuts

SeraPlot Documentation