Merge pull request #97 from MODFLOW-USGS/v0.3.0

Release 0.3.0

DEVELOPER.md

@@ -5,6 +5,7 @@ This document provides guidance to set up a development environment and discusse
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Testing](#testing)

HISTORY.md

@@ -1,3 +1,10 @@
+### Version 0.3.0
+
+#### Refactoring
+
+* [refactor(dependencies)](https://github.com/MODFLOW-USGS/modflow-devtools/commit/72e29e14e74c2b874cba89b1eb1563e1b4e6d0a0): Remove them, update readme (#95). Committed by w-bonelli on 2023-08-04.
+* [refactor(download_and_unzip)](https://github.com/MODFLOW-USGS/modflow-devtools/commit/c1bdb3cf7cdd988df9f3ae8d67de7496f1603c38): Return path to extract locn (#96). Committed by w-bonelli on 2023-08-04.
+
 ### Version 0.2.0
 
 #### New features

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.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+
+- [Use cases](#use-cases)
 - [Requirements](#requirements)
 - [Installation](#installation)
-- [Use cases](#use-cases)
-- [Quickstart](#quickstart)
 - [Documentation](#documentation)
-- [MODFLOW Resources](#modflow-resources)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+## 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 assets, 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 <path>` 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,55 +54,24 @@ 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]"
 ```
 
 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/).

docs/conf.py

@@ -8,7 +8,7 @@
 
 project = "modflow-devtools"
 author = "MODFLOW Team"
-release = "0.2.0"
+release = "0.3.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/md/download.md

@@ -77,3 +77,5 @@ from modflow_devtools.download import download_and_unzip
 url = f"https://github.com/MODFLOW-USGS/modflow6/releases/download/6.4.1/mf6.4.1_linux.zip"
 download_and_unzip(url, "~/Downloads", delete_zip=True, verbose=True)
 ```
+
+The function's return value is the `Path` the archive was extracted to.

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

modflow_devtools/__init__.py

@@ -1,6 +1,6 @@
 __author__ = "Joseph D. Hughes"
-__date__ = "Jul 26, 2023"
-__version__ = "0.2.0"
+__date__ = "Aug 04, 2023"
+__version__ = "0.3.0"
 __maintainer__ = "Joseph D. Hughes"
 __email__ = "[email protected]"
 __status__ = "Production"

modflow_devtools/download.py

@@ -438,7 +438,7 @@ def download_and_unzip(
     delete_zip=True,
     retries=3,
     verbose=False,
-):
+) -> Path:
     """
     Download and unzip a zip file from a URL.
     The filename must be the last element in the URL.
@@ -455,6 +455,11 @@ def download_and_unzip(
         The maximum number of retries for each request
     verbose : bool
         Whether to show verbose output
+
+    Returns
+    -------
+    Path
+        The path to the directory where the zip file was unzipped
     """
 
     path = Path(path if path else os.getcwd())
@@ -544,3 +549,5 @@ def download_and_unzip(
 
     if verbose:
         print(f"Done downloading and extracting {file_path.name} to {path}")
+
+    return path

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",

version.txt

@@ -1 +1 @@
-0.2.0
+0.3.0