diff --git a/DEVELOPER.md b/DEVELOPER.md index 5a44c4f..b074df5 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -5,6 +5,7 @@ This document provides guidance to set up a development environment and discusse + - [Requirements](#requirements) - [Installation](#installation) - [Testing](#testing) diff --git a/README.md b/README.md index a6833db..0471626 100644 --- a/README.md +++ b/README.md @@ -7,23 +7,44 @@ [![CI](https://github.com/MODFLOW-USGS/modflow-devtools/actions/workflows/ci.yml/badge.svg)](https://github.com/MODFLOW-USGS/modflow-devtools/actions/workflows/ci.yml) [![Documentation Status](https://readthedocs.org/projects/modflow-devtools/badge/?version=latest)](https://modflow-devtools.readthedocs.io/en/latest/?badge=latest) -Python tools for MODFLOW development and testing. +Python development tools for MODFLOW 6. + +- [Use cases](#use-cases) - [Requirements](#requirements) - [Installation](#installation) -- [Use cases](#use-cases) -- [Quickstart](#quickstart) - [Documentation](#documentation) -- [MODFLOW Resources](#modflow-resources) +## Use cases + +This is a small toolkit for developing MODFLOW 6, FloPy, and related projects. It includes standalone utilities and optional [Pytest](https://github.com/pytest-dev/pytest) extensions. + +Standalone utilities include a very minimal GitHub API client, mainly for retrieving release information and downloading asset, and a `ZipFile` subclass that [preserves file permissions](https://stackoverflow.com/questions/39296101/python-zipfile-removes-execute-permissions-from-binaries) (workaround for [Python #15795](https://bugs.python.org/issue15795)) + +Pytest features include: + +- `--keep ` tempdir fixtures for [each scope](https://docs.pytest.org/en/stable/how-to/fixtures.html#scope-sharing-fixtures-across-classes-modules-packages-or-session) +- a [`--smoke` test](https://en.wikipedia.org/wiki/Smoke_testing_(software)) (abbrev. `-S`) CLI option shortcut +- markers to skip test cases conditional on + - operating system + - Python packages installed + - executables available on the PATH +- test fixtures for example / test models in + - `MODFLOW-USGS/modflow6-examples` + - `MODFLOW-USGS/modflow6-testmodels` + - `MODFLOW-USGS/modflow6-largetestmodels` + ## Requirements -This project requires Python3.8+. Its only core dependencies are `numpy` and `pytest`. +Python3.8+, dependency-free, but pairs well with `pytest` and select plugins, e.g. + +- [`pytest-dotenv`](https://github.com/quiqua/pytest-dotenv) +- [`pytest-xdist`](https://github.com/pytest-dev/pytest-xdist) ## Installation @@ -33,13 +54,7 @@ This project requires Python3.8+. Its only core dependencies are `numpy` and `py pip install modflow-devtools ``` -This package pairs well with a few pytest plugins: - -- `pytest-cases` -- `pytest-dotenv` -- `pytest-xdist` - -These and a few other optional dependencies can be installed with: +Pytest, pytest plugins, and other optional dependencies can be installed with: ```shell pip install "modflow-devtools[test]" @@ -47,41 +62,16 @@ pip install "modflow-devtools[test]" To install from source and set up a development environment please see the [developer documentation](DEVELOPER.md). -## Use cases - -This package contains shared tools for developing and testing MODFLOW 6 and FloPy, including standalone utilities as well as `pytest` fixtures, CLI options, and test cases: - -- utilities for retrieving release information and downloading assets from the GitHub API -- a `ZipFile` subclass that [preserves file permissions](https://stackoverflow.com/questions/39296101/python-zipfile-removes-execute-permissions-from-binaries) (workaround for [Python #15795](https://bugs.python.org/issue15795)) -- a `pytest` CLI option for smoke testing (running a fast subset of cases) -- a minimal `pytest-cases` framework for reusing test functions and data -- a set of keepable `pytest` temporary directory fixtures for each scope -- a set of fixtures to parametrize tests with models from external repos - - `MODFLOW-USGS/modflow6-examples` - - `MODFLOW-USGS/modflow6-testmodels` - - `MODFLOW-USGS/modflow6-largetestmodels` -- a set of `pytest` markers to conditionally skip test cases based on - - operating system - - Python packages installed - - executables available on the path - -## Quickstart - To import `pytest` fixtures in a project consuming `modflow-devtools`, add the following to a `conftest.py` file: ```python pytest_plugins = [ "modflow_devtools.fixtures" ] ``` -**Note**: `pytest` requires this to be a top-level `conftest.py` file. Nested `conftest.py` files may override or extend this package's fixtures. +**Note**: this must be a top-level `conftest.py`, which nested `conftest.py` files may then override or extend. ## Documentation -Usage documentation is available at [modflow-devtools.readthedocs.io](https://modflow-devtools.readthedocs.io/en/latest/). - -## MODFLOW Resources +Docs are available at [modflow-devtools.readthedocs.io](https://modflow-devtools.readthedocs.io/en/latest/). -+ [MODFLOW and Related Programs](https://water.usgs.gov/ogw/modflow/) -+ [Online guide for MODFLOW-2000](https://water.usgs.gov/nrp/gwsoftware/modflow2000/Guide/) -+ [Online guide for MODFLOW-2005](https://water.usgs.gov/ogw/modflow/MODFLOW-2005-Guide/) -+ [Online guide for MODFLOW-NWT](https://water.usgs.gov/ogw/modflow-nwt/MODFLOW-NWT-Guide/) +For more info on MODFLOW 6 see [the USGS overview](https://water.usgs.gov/ogw/modflow/). diff --git a/docs/md/install.md b/docs/md/install.md index 539a83c..473bc1e 100644 --- a/docs/md/install.md +++ b/docs/md/install.md @@ -2,7 +2,7 @@ ## Installing `modflow-devtools` from PyPI -The `modflow-devtools` package is [available on PyPi](https://pypi.org/project/modflow-devtools/) and can be installed with `pip`: +Packages are [available on PyPi](https://pypi.org/project/modflow-devtools/) and can be installed with `pip`: ```shell pip install modflow-devtools diff --git a/pyproject.toml b/pyproject.toml index 46d8cfd..78beab2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -36,10 +36,6 @@ classifiers = [ "Topic :: Scientific/Engineering :: Hydrology" ] requires-python = ">=3.8" -dependencies = [ - "numpy", - "pytest" -] dynamic = ["version"] [project.optional-dependencies] @@ -57,6 +53,8 @@ test = [ "filelock", "meson!=0.63.0", "ninja", + "numpy", + "pytest", "pytest-cases", "pytest-cov", "pytest-dotenv",