quickploteasy 0.1.0

A fluent, chainable wrapper around matplotlib for building modern, publication-ready plots with less boilerplate.

quickploteasy

A fluent, chainable wrapper around matplotlib for building better-looking plots and histograms with less boilerplate.

pip install quickploteasy

quickploteasy aims for charts that look like a senior analyst made them — minimalist, decluttered, and finished by default. It ships the modern Inter typeface, wraps every plot in an editorial headline / subtitle / source frame, and styles the marks themselves: bars get rounded tops and bold value labels (and drop the redundant y-axis when every bar is labelled), one bar or series can carry the accent while the rest recede to gray, line/area charts are directly labelled at their end instead of via a legend, box plots come filled with a colourblind-checked palette, and area charts fade out with a gradient. The palette and chrome are the validated reference instance from a data-viz design method, stepped separately for light and dark surfaces.

Instead of juggling fig, ax = plt.subplots(), styling calls, and label setters, you describe a plot as a single readable chain:

import quickploteasy as qp

(qp.plot()
   .bar(regions, sales, highlight="max")     # gray context, accent on the peak
   .labels(
       title="The West region led the quarter",
       subtitle="Net sales by region ($M)",
       source="Source: internal figures",
   )
   .save("sales.png"))

Install (development)

This project uses a src/ layout and pyproject.toml. With uv:

uv sync --extra dev      # create a venv and install deps + dev tools
uv run pytest            # run the test suite
uv run ruff check .      # lint

API at a glance

Start a chain with qp.plot(data). data can be an array-like, a dict, or a pandas DataFrame (reference columns by name).

Conventional forms

Method	Description
.hist(data=None, bins="auto", kde=False)	Histogram; kde=True overlays a smooth density curve
.line(x=None, y=None, fill=False)	Line plot; fill=True adds a gradient area
.area(x=None, y=None)	Line with a gradient area fill (shorthand for line(fill=True))
.scatter(x, y)	Scatter plot
.bar(x, y, values=True, highlight=None)	Bar chart; highlight takes an index / "max" / "min" to accent one bar
.box(data=None, group_labels=None)	Filled box plot with readable group labels

Modern forms (the reason to reach for quickploteasy)

Method	Description
.lollipop(x, y, highlight=None)	A lighter bar chart — stem + dot, great for many categories
.ridgeline(groups, labels=None)	Overlapping density "mountains" to compare a distribution across groups
.raincloud(data, group_labels=None)	Half-violin + jittered raw points + slim box — the modern box-plot replacement

Overlaying multiple series (e.g. two .hist() calls) automatically advances through the palette so each series gets a distinct hue. A labelled line/area series is labelled directly at its end point; other labelled marks get a legend.

Text & styling

.title(text) (headline), .subtitle(text), .source(text) (footnote), .xlabel(text), .ylabel(text), .labels(title=, subtitle=, x=, y=, source=), .xlim(lo, hi), .ylim(lo, hi), .grid(bool), .legend(), .theme(name)

Finishing

.save(path), .show(), .render() (returns the underlying (fig, ax) for escape-hatch customization), .close()

Themes

Built-in themes: light (default), dark, minimal. Each theme bundles a categorical palette (colourblind-checked, stepped for its surface) with chrome roles — surface, primary/secondary ink, hairline grid, soft baseline. Themes are applied locally per-figure via rc_context, so they never mutate your global matplotlib state. List them with qp.themes().

qp.plot(data, theme="dark")   # set at construction (preferred)
qp.plot(data).hist().theme("dark")  # or switch in the chain

Status

Early alpha (0.1.0). The fluent core is in place; more chart types, faceting, and a pandas-first convenience layer are on the roadmap.

License

quickploteasy is released under the MIT License. It bundles the Inter typeface, which is licensed separately under the SIL Open Font License 1.1 (see Inter-LICENSE.txt).

Publishing

Packaging and release instructions live in PUBLISHING.md.