Metadata-Version: 2.4
Name: quickploteasy
Version: 0.1.0
Summary: A fluent, chainable wrapper around matplotlib for building modern, publication-ready plots with less boilerplate.
Project-URL: Homepage, https://github.com/naryan/quickplot
Project-URL: Repository, https://github.com/naryan/quickplot
Project-URL: Issues, https://github.com/naryan/quickplot/issues
Project-URL: Changelog, https://github.com/naryan/quickplot/blob/main/CHANGELOG.md
Author: quickploteasy authors
License-Expression: MIT
License-File: LICENSE
License-File: src/quickploteasy/assets/fonts/Inter-LICENSE.txt
Keywords: charts,dataviz,histograms,matplotlib,plotting,raincloud,ridgeline,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: matplotlib>=3.6
Requires-Dist: numpy>=1.23
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pandas>=1.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Description-Content-Type: text/markdown

# quickploteasy

A fluent, chainable wrapper around [matplotlib](https://matplotlib.org/) for
building better-looking plots and histograms with less boilerplate.

```bash
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](https://rsms.me/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:

```python
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](https://docs.astral.sh/uv/):

```bash
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()`.

```python
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](LICENSE). It bundles the
[Inter](https://rsms.me/inter/) typeface, which is licensed separately under the
SIL Open Font License 1.1 (see
[`Inter-LICENSE.txt`](src/quickploteasy/assets/fonts/Inter-LICENSE.txt)).

## Publishing

Packaging and release instructions live in [PUBLISHING.md](PUBLISHING.md).
