arcadia-pycolor 0.8.0

A Python package to distribute Arcadia's color and style guidelines for figures.

arcadia-pycolor

This repo contains a Python package called arcadia_pycolor that provides tools for styling Matplotlib, Seaborn, and Plotly figures to comply with Arcadia's style guide.

Installation

The package is hosted on PyPI and can be installed using pip:

pip install arcadia-pycolor

Usage

Please see the quickstart guide for Matplotlib or Plotly for an introduction to the package, as well as how to use it to style plots.

For detailed documentation about the package and links to example plots, see the documentation README.

Development

Environment setup

We use uv to manage dependencies and packaging. If you don't already have it installed, see the uv installation guide.

Install dependencies (including the development dependencies) and the package itself into a managed virtual environment with a single command:

uv sync

This creates a .venv directory, installs the matching Python version (from .python-version), and installs arcadia_pycolor in editable mode. Prefix commands with uv run (e.g. uv run pytest) to run them inside this environment without activating it.

The Plotly image-export tests require Chrome, which Kaleido (v1+) no longer bundles. If it isn't already installed, run uv run plotly_get_chrome once before running the test suite (see the Plotly quickstart for details).

Testing

We use pytest for testing. The tests are found in the arcadia_pycolor/tests/ subpackage. To run the tests, simply run pytest from the root directory of the repository.

Some of the tests generate plots whose correctness is difficult to validate programmatically. Therefore, when changes are made to the style defaults or to the auto-styling methods in arcadia_pycolor.mpl, it is important to manually inspect these plots to verify that no unintended changes have been introduced. To do so, there is a custom --output-dirpath pytest option that can be used to save the test plots to a local directory. For example, to save the test plots to a directory called test-outputs, run:

pytest --output-dirpath ./test-outputs

The directory passed to --output-dirpath will be created if it does not already exist and will be overwritten if it does exist. The test plots will be saved in this directory as PDF files with the same names as the test functions that generated them. The tests are parametrized by the pre-defined figure sizes in arcadia_pycolor.style_defaults, so there will be one file for each test and each figure size.

Hint: you can use pytest's -k option to filter the tests that are run if you only need to generate certain plots. This can be convenient for faster feedback during development. For example, to run only the tests that generate barplots, run:

pytest -k barplots --output-dirpath ./test-outputs

Updating the Jupyter notebooks

Some of the documentation is in the form of Jupyter notebooks. The inline graphical outputs of these notebooks are part of the documentation, so these notebooks are committed to the repo with their outputs included. It is therefore important to keep the notebook outputs up-to-date by re-running all of the notebooks when changes are made to the package.

Run the following command to execute all the notebooks:

make execute-all-notebooks

This 1) ensures that the notebooks execute without errors and 2) updates their outputs in-place. Then, commit any modified notebooks to the repo.

Updating the documentation site

We use Material for MkDocs to build the documentation site. Everything can be found in the docs/ directory.

You can use the following command to preview your changes as you make them:

make preview-docs

Additionally, this repo has a GitHub Actions workflow for building the documentation site and publishing it to GitHub Pages. It's triggered on pushes to main.

Publishing a new version of the package on PyPI

Publishing the package on PyPI requires that you have API tokens for the test and production PyPI servers. You can find these tokens in your PyPI account settings. Copy .env.copy to .env and add your tokens to this file.

To release a new version of the package on PyPI, its version number must first be incremented.

We use git tags to define versions. When you're ready to release a new version of the package, first create a new git tag. The name of the tag should correspond to the version number, e.g. "v0.1.0". Annotate the tag with a message that describes the release, e.g. "Release version 0.1.0".

Before creating the tag, make sure that your local git repository is on main, is up-to-date, and does not contain uncommitted changes!

git tag -a v0.1.0 -m "Release version 0.1.0"
git push origin v0.1.0

We use semantic versioning in which the versions have the form MAJOR.MINOR.PATCH. See here for more information.

Next, build the package:

make build

You should see an output that looks like this:

Building arcadia-pycolor (0.1.0)
  - Building sdist
  - Built arcadia_pycolor-0.1.0.tar.gz
  - Building wheel

Make sure that the version number matches the one from the git tag that you just created. If it does not, double-check that you created the git tag correctly. If the version number is 0.0.0, this indicates that hatch-vcs is failing to infer any version number at all. Check that your environment is set up with uv sync and that your local checkout includes the git tag (the full git history must be available).

Next, test that you can publish the package to the PyPI test server:

make build-and-test-publish

This command calls uv build to build the package and then uv publish to upload the build artifacts to the test server.

Note: the build artifacts are also written to the dist/ directory.

Check that you can install the package from the test server:

pip install --index-url https://test.pypi.org/simple/ arcadia-pycolor

If everything looks good, build and publish the package to the prod PyPI server:

make build-and-publish

Finally, check that you can install the package from the prod PyPI server:

pip install arcadia-pycolor