[![Code style:
black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)](https://github.com/ambv/black)
[![GitHub Workflow
Status](https://img.shields.io/github/workflow/status/ebenp/figpager/Run%20Tox?style=for-the-badge)](https://github.com/ebenp/figpager/actions)
[![PyPI
version](https://img.shields.io/pypi/v/figpager.svg?style=for-the-badge)](https://pypi.org/project/figpager/)
[![PyPI
pyversions](https://img.shields.io/pypi/pyversions/figpager.svg?style=for-the-badge)](https://pypi.python.org/pypi/figpager/)
[![License:
MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
# figpager
[Matplotlib](http://matplotlib.org) is a graphics library for Python that can save plots with
various backends and single or multiple pages.
FigPager is a wrapper class for those backends.
FigPager is similar to other third party Matplotlib [packages](https://matplotlib.org/thirdpartypackages/index.html)
that allow figure elements to be added such as a title block, border and logo.
One example package is [mpl-template](https://austinorr.github.io/mpl-template/index.html).
The FigPager class reads layout specifications from an .ini file. FigPager
handles drawing boxes, text, images and lines referenced in .ini files on a figure canvas.
The class handles adding subplots, adding new pages in multipage backends and closing the figure.
Example output from tests\test_1.py<img src="https://github.com/ebenp/figpager/blob/main/tests/figpager.png?raw=true">
## Install
Install using pip. figpager has been tested for Python 2.7, Python 3.7 and Python 3.8. See [requirements.txt](https://github.com/ebenp/figpager/blob/master/requirements.txt) for dependencies.
```
pip install figpager
```
## Usage
After install FigPager can be imported from figpager.
```
from figpager import FigPager
```
A FigPager instance is initialized with a paper size of A0-A10, B0-B10, letter,
legal or ledger, the number of plot panels in a row as an integer and the number of plot panels as columns as an integer. 3 rows and 3 columns of panels for a figure of 3x3 is depicted below.
```
fp = FigPager(
"letter",
3,
3,
)
```
Additional keywords provide further functionality.
See the code for all keywords.
```
fp = FigPager(
"letter",
3,
2,
layout="Report",
outfile=.\out.pdf,
orientation="portrait",
height_ratios=[1, 1, 2],
overwrite=True,
transparent=True,
)
```
with blocks are also supported with no need for fp.close()
```
with FigPager("letter", 3, 2, layout="Report", outfile=.\out.pdf,
orientation="portrait", height_ratios=[1, 1, 2],
overwrite=True, transparent=True) as fp:
```
Example layout .ini files can be found in the
package under page_layout.
FigPager has options to add subplots. See the code for all keywords.
```
ax0 = fp.add_subplot()
```
FigPager also has add page options. In backends that don't
support multipage a zero padded number is added as a suffix to the file name.
The example below
specifies the number of rows and columns,
the orientation and height ratios.
See the code for all keywords.
```
fp.add_page(
nrows=3, ncols=2, orientation="portrait", height_ratios=[1, 1, 2]
)
```
FigPager options read from an .ini file can be updated via the instance's config. The syntax is config[section][subsection][option] = value.
```
fp.config['Text']['Document Title']['text']
```
Finally, FigPager instance can be closed following the example below.
```
fp.close()
```
See the test code under tests for example code.
## Development / Testing
Submit issues and PRs through GitHub.
Testing is done with [tox](https://pypi.org/project/tox/). [pytest](https://pypi.org/project/pytest/), [black](https://pypi.org/project/black/) and [isort](https://pypi.org/project/isort/) are run against code.
## License
figpager is released under the MIT license.
See [LICENSE.md](https://github.com/ebenp/figpager/blob/master/LICENSE.md) for details.