Adopt PyPA packaging guidelines

[wigging]

The Python Packaging Authority (PyPA) provides guidelines for developing Python packages. Their current approach to developing a Python package is outlined here. The overall structure is

packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│   └── my_example_package/
│       ├── __init__.py
│       └── example.py
└── tests/

which uses a pyproject.toml for build configuration and other setup. The src/ directory is where the source code for the package lives. A big advantage of this approach is that it ensures tests are run on the installed code. See this article for more details about this approach.

[lbianchi-lbl]

Thanks for bringing this up. Broadly speaking, I'd be in favor of this (with the caveat that the tests should reside within the package rather than in the top-level tests directory, as per my comments on #810), although I think it makes sense to separate it in two parts:

1. Adopting the src layout, i.e. moving the watertap package directory to src/watertap (and make the corresponding changes to setup.py)
2. Moving to PEP517-compatible build process (i.e. pyproject.toml)

For (1) I think it should be possible to do it without too much strife (although I still wouldn't call it an urgent thing to do):

• We already have tests that run on non-editable installations (so we shouldn't have any case of e.g. data files that have not been registered correctly
• The only thing I anticipate could break is some of the code that relies on the fact that, in an editable installation, the repository root is the parent of the directory corresponding to the watertap package, but these should not be widespread and likely easy to fix

For (2), I think we should plan on doing that at some point in the future, but not anytime soon:

• My recent research on PEP517 build systems led me to think that it'd be wiser for us to wait a bit until the "dust has settled" and the ecosystem is more stable
• I'm thinking especially of support for PEP660, without which editable installations (that I'd consider a critical component of our developer workflow) simply do not work at all in PEP517-land
• We're also planning on making some changes in the short term that are still based on setup.py, and I think these have the priority (as they address a more concrete need for the project at this point in time)

[wigging]

The following files are currently in the watertap repository: setup.py, pytest.ini, and pyproject.toml. So related to my original comment of adopting a modern packaging structure, the pyproject.toml would clean up the project as it would allow you to remove the setup.py and pytest.ini files.