Metadata-Version: 2.1
Name: shplot
Version: 1.0.0
Summary: Wrapper for Matplotlib.
Home-page: https://github.com/jayanthkoushik/shplot
License: MIT
Keywords: matplotlib,plotting,dataviz
Author: Jayanth Koushik
Author-email: mail@jkoushik.me
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Matplotlib
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
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: Topic :: Utilities
Requires-Dist: corgy (>=9.2,<10.0)
Requires-Dist: matplotlib (>=3.3,<4.0)
Project-URL: Repository, https://github.com/jayanthkoushik/shplot
Description-Content-Type: text/markdown

# shplot

shplot is a Python library wrapper for managing Matplotlib configuration
through profiles, and provides a number of built-in profiles suitable
for different use cases.

## Installation

shplot is available on PyPI, and can be installed with `pip`:

```sh
pip install shplot
```

## Usage

Common use cases are shown here. Refer to the documentation for in-depth
usage. The project repository's `demos/` folder contains illustrations
of the built-in profiles. The demo files can be (re)generated by running
`scripts/plot_demos.py`.

### Create a plot and use it in a context

<!-- cSpell: disable -->

```pycon
>>> from shplot import ShPlot
>>> plot = ShPlot(builtin_profile_name="paper")
>>> with plot.context(nrows=2, ncols=2) as (fig, axs):
...     # `axs` is a 2x2 array.
...     pass
>>> with plot.context(mosaic="AAB\nC.B") as (fig, axs):
...     # `axs` is a dictionary.
...     pass

```

<!-- cSpell: enable -->

### Update Matplotlib settings using a profile

```pycon
>>> from shplot.profiles import ColorProfile
>>> profile = ColorProfile(fg="yellow", bg="black")
>>> profile.config()  # will update `matplotlib.rcParams`

```

### Use a built-in profile with overrides

```pycon
>>> from shplot import ShPlot
>>> from shplot.profiles.builtin import ShPaperProfile
>>> profile = ShPaperProfile(fontname="fira", **{"axes.grid": True})
>>> profile.config()

```

### Create a plot using command line arguments

**`main.py`**

```python
from shplot import ShPlot

plot = ShPlot.parse_from_cmdline()
with plot.context() as (fig, ax):
    ...
```

```
$ python main.py -h
usage: main.py [-h] [--file str] [--shprofile str] [--profile-args key=val,...] [--width
  float] [--aspect float[;float]]

options:
  -h/--help                   show this help message and exit
  --file str                  Plot save file (extension will be added if not provided).
                              (optional)
  --shprofile str             Name of a built-in profile.
                              ({paper/book/web_light/web_dark/presentation} optional)
  --profile-args key=val,...  Arguments for the builtin-profile. Refer to the individual
                              profiles for details. (optional)
  --width float               Plot width, in inches (if greater than 1), or as a fraction of
                              the configured plot width (if less than or equal to 1).
                              (optional)
  --aspect float[;float]      Plot aspect ratio, width/height. When provided as a command
                              line argument, can be passed as a single number or a ratio in
                              the form `<WIDTH>;<HEIGHT>`. (optional)
```

