Use poetry for dependency management and build tooling

[keithchev]

Overview

This PR introduces poetry for dependency management and build tooling. The purpose of this is to allow us to publish the arcadia-pycolor package to PyPI so that it is pip-installable using pip install arcadia-pycolor.

This involves the following changes:

• update pyproject.toml according to the poetry docs and remove setup.py.
• move dependencies from setup.py and the conda env files into the appropriate sections of pyproject.toml and remove the env files.
• specify a minimum rather than an exact version for all dependencies, as the package needs to support a range of python and matplotlib versions. For now, I picked a minimum of python 3.9 (released in Oct 2020) and matplotlib 3.7 (released in Feb 2023).
• add a poetry lockfile for consistent dev envs (this won't be used when end users pip-install the package).
• add an env file to store API tokens for the PyPI servers.
• add makefile commands to build and publish the package.
• bump the version of the package (for now, I bumped from 0.3.1 to 0.4.0).

Drive-by changes

• remove the old README and the notebook README.ipynb from which it was derived. This was for a few reasons: I wanted to update the README directly with instructions about developing and publishing the package; the notebook included dependencies that are not used by the package itself; it looks like the notebook will be replaced by the new usage_examples.ipynb notebook.
• add caching and a step to run the tests in the existing CI workflow.

Testing

All of this was done manually.

• I tested that the package can be built and published to the PyPI test server.
• I tested that the package can be installed by pip from a local wheel and from the test server.
• I tested that the pip-installed package can be imported without errors and the color swatches work.
• I checked that the mplstyles/ directory is included in the builds.

[review-notebook-app[bot]]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[keithchev]

Should I be using poetry to manage my dev environment dependencies instead of conda? Could someone point me to their favorite resources for making that transition/ what the caveats are?

Do you mean for apc or in general? For apc, I added instructions in the readme that should be easy to follow (I hope). For most projects, I think conda is fine. IMO poetry is only worth using for projects that are python packages that we need to build and release, as it provides build tooling (the poetry build and poetry publish commands) that makes this easier. Its strict dependency management (the lockfiles) is also nice, but conda env files come close enough. Plus many projects have dependencies that are only on conda-forge or bioconda, and poetry won't work for those.

I actually intended usage_examples.ipynb to just be a temporary document I'm using to illustrate the API in detail (and test its functionality in Jupyter notebooks), with the hope that actual demonstration / walkthrough of the API for a user will live somewhere else, such as in the README. Not sure what the best place for that might be, but a mkdocstrings Markdown page might be the easiest. I'd argue that we should have at least a small handful of usage examples in the README in addition to the installation instructions. But in any case, I'm fine with deleting all these files for now to declutter the repo.

Agree re the mkdocs solution and having examples in the README. But we should find a way to avoid making README.md an artifact that has to be generated from a notebook, just because this is a bit messy and hard to maintain.