refactor(get-modflow): add option to have flopy bindir on PATH

- With "import flopy" append a local flopy bindir to the the PATH
- Add simple install instructions to documentation
- Write metadata history for get-modflow
- Change bindir "?" option to ":"
- Add other bindir auto-select options ":1" and ":flopy"
- Add examples at the bottom with --help option
- If get-modflow encounters HTTP error 503, retry (up to 3 times)
- Rename "flopy.utils.get_modflow_main" to "flopy.utils.get_modflow"
  and "flopy.utils.get_modflow" to "flopy.utils.get_modflow_module"
- Rename "test_scripts.py" to "test_get_modflow.py"

.docs/introduction.rst

@@ -58,6 +58,14 @@ To install the bleeding edge version of FloPy from the git repository type:
 
     pip install git+https://github.com/modflowpy/flopy.git
 
+After FloPy is installed, MODFLOW and related programs can be installed using the command:
+
+.. code-block:: bash
+
+    get-modflow :flopy
+
+See documentation `get_modflow.md <https://github.com/modflowpy/flopy/blob/develop/docs/get_modflow.md>`_
+for more information.
 
 
 FloPy Resources

README.md

@@ -39,6 +39,12 @@ or
 
 The release candidate version can also be installed from the git repository using the instructions provided [below](#relcand).
 
+After FloPy is installed, MODFLOW and related programs can be installed using the command:
+
+    get-modflow :flopy
+
+See documentation [get_modflow.md](https://github.com/modflowpy/flopy/blob/develop/docs/get_modflow.md) for more information.
+
 
 Documentation
 -----------------------------------------------

autotest/test_scripts.py → autotest/test_get_modflow.py

@@ -1,12 +1,12 @@
-"""Test scripts."""
+"""Test get-modflow utility."""
 import sys
 import urllib
 from urllib.error import HTTPError
 
 import pytest
 from flaky import flaky
 
-from flopy.utils import get_modflow_main
+from flopy.utils import get_modflow
 from autotest.conftest import (
     get_project_root_path,
     requires_github,
@@ -132,7 +132,7 @@ def test_get_nightly_script(tmp_path, downloads_dir):
 @requires_github
 def test_get_modflow(tmpdir):
     try:
-        get_modflow_main(tmpdir)
+        get_modflow(tmpdir)
     except HTTPError as err:
         if err.code == 403:
             pytest.skip(f"GitHub {rate_limit_msg}")
@@ -175,7 +175,7 @@ def test_get_modflow(tmpdir):
 @requires_github
 def test_get_nightly(tmpdir):
     try:
-        get_modflow_main(tmpdir, repo="modflow6-nightly-build")
+        get_modflow(tmpdir, repo="modflow6-nightly-build")
     except urllib.error.HTTPError as err:
         if err.code == 403:
             pytest.skip(f"GitHub {rate_limit_msg}")

docs/get_modflow.md

@@ -36,7 +36,15 @@ from pathlib import Path
 import flopy
 
 bindir = Path("/tmp/bin")
-bindir.mkdir()
-flopy.utils.get_modflow_main(bindir)
+bindir.mkdir(exist_ok=True)
+flopy.utils.get_modflow(bindir)
 list(bindir.iterdir())
 ```
+
+## Where to install?
+
+A required `bindir` parameter must be supplied to the utility, which specifies where to install the programs. This can be any existing directory, usually which is on the users' PATH environment variable. To assist the user, a special value can be specified starting with the colon character, `:`. These are:
+
+ - `:` lets a user interactively choose a selection of path options. If this utility was run by FloPy more than once, the first option will be the previously used `bindir` path selection.
+ - `:1` (or other number) auto-selects from a selection of common paths, where (e.g.) `1` refers to the first option. Note that the first option may change to prefer a previously selected `bindir` option.
+ - `:flopy` special option that will create and install programs for FloPy.

flopy/mbase.py

@@ -9,6 +9,7 @@
 import os
 import queue as Queue
 import shutil
+import sys
 import threading
 import warnings
 from datetime import datetime
@@ -21,6 +22,13 @@
 from .discretization.grid import Grid
 from .version import __version__
 
+# Prepend flopy appdir bin directory to PATH to work with "get-modflow :flopy"
+if sys.platform.startswith("win"):
+    flopy_bin = os.path.expandvars(r"%LOCALAPPDATA%\flopy\bin")
+else:
+    flopy_bin = os.path.join(os.path.expanduser("~"), ".local/share/flopy/bin")
+os.environ["PATH"] = flopy_bin + os.path.pathsep + os.environ.get("PATH", "")
+
 ## Global variables
 # Multiplier for individual array elements in integer and real arrays read by
 # MODFLOW's U2DREL, U1DREL and U2DINT.

flopy/utils/__init__.py

@@ -21,6 +21,7 @@
 
     """
 from .utl_import import import_optional_dependency  # isort:skip
+from . import get_modflow as get_modflow_module
 from .binaryfile import (
     BinaryHeader,
     CellBudgetFile,
@@ -31,7 +32,8 @@
 from .check import check
 from .flopy_io import read_fixed_var, write_fixed_var
 from .formattedfile import FormattedHeadFile
-from .get_modflow import run_main as get_modflow_main
+
+get_modflow = get_modflow_module.run_main
 from .gridintersect import GridIntersect, ModflowGridIndices
 from .mflistfile import (
     Mf6ListBudget,