Development tools: static linting, type checking, and more

[deltamarnix]

What makes a software library a good package? We want to establish a stable API that doesn't change often. And we want to provide the user a clear insight in what we build and into what they can expect when they use it. Meaning that documentation is key, and source code should be well readable since we're open source.

I was looking to popular packages to keep our code base in shape: https://github.com/ml-tooling/best-of-python-dev. We might not need all of these different types of helpers, but some could be rather useful.

I want to propose to at least use the following packages:

• Linting and formatting with ruff
• Type checking with mypy. Which means that our public API should be type complete, so that it's clear which types of arguments we expect.
• A virtual environment. Flopy might be using conda packages that are not available via pypi. It might be useful to use pixi for package management. If everything can stay within pypi, we might consider using a pipenv or virtualenv. Make it clear for developers how to install and use our package.
• Documentation with sphinx or mkdocs. Deltares decided to move to quarto, but it's not in this best-of list.
• Building with setuptools. Keeping things to the built-in offers might not be a wrong choice in this case, although there are many alternatives.
• Pre-commit hooks. Ensuring that you do some initial checks before you commit. Could be as simple as running ruff.

Let me know if you have any opinions that you want to share. Things that you actually wouldn't want to use.

[wpbonelli]

Flopy might be using conda packages that are not available via pypi

It does not, everything is on pypi. AFAIK one can develop flopy with builtin venv, with conda, with pixi, or otherwise.

IMO it's developer preference which kind of virtual env to use, ideally the package is agnostic to this choice. I just noticed pixi has facilities for managing pyproject.toml. I like the idea of using pixi in CI for the dependency locking too.

Agreed on sticking to a standard setuptools build, and on linting and type checking. I have not used any of the mypy alternatives but mypy seems to be the most popular.

[deltamarnix]

I noticed that one of the pypi dependencies requires MS Build Tools v14. That is something that I don't have when managing with pixi/conda.

[wpbonelli]

which one?

[deltamarnix]

pymetis in the dev environment seems to require more building steps with ms C++

  x dev: error installing/updating PyPI dependencies
  |-> Failed to prepare distributions
  |-> Failed to fetch wheel: pymetis==2023.1.1
  `-> Build backend failed to build wheel through `build_wheel()` with exit code: 1
      --- stdout:
      running bdist_wheel
      running build
      running build_py
      copying pymetis\version.py -> build\lib.win-amd64-cpython-312\pymetis
      copying pymetis\__init__.py -> build\lib.win-amd64-cpython-312\pymetis
      running build_ext
      building 'pymetis._internal' extension
      --- stderr:
      error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://
      visualstudio.microsoft.com/visual-cpp-build-tools/
      ---

[wpbonelli]

Ah that's needed for the model splitter. It's an optional dependency so not a huge worry I think