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

- 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 ":flopy", ":python", etc.
- 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,4 +1,4 @@
-"""Test scripts."""
+"""Test get-modflow utility."""
 import sys
 import urllib
 from urllib.error import HTTPError
@@ -11,7 +11,7 @@
 )
 from flaky import flaky
 
-from flopy.utils import get_modflow_main
+from flopy.utils import get_modflow
 
 flopy_dir = get_project_root_path(__file__)
 get_modflow_script = flopy_dir / "flopy" / "utils" / "get_modflow.py"
@@ -139,7 +139,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}")
@@ -182,7 +182,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,24 @@ 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())
+
+# Or use an auto-select option
+flopy.utils.get_modflow(":flopy")
 ```
+
+## 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, special values can be specified starting with the colon character. Use a single `:` to interactively select an option of paths.
+
+Other auto-select options are only available if the current user can write files (some may require `sudo` for Linux or macOS):
+ - `:prev` - if this utility was run by FloPy more than once, the first option will be the previously used `bindir` path selection
+ - `:flopy` - special option that will create and install programs for FloPy
+ - `:python` - use Python's bin (or Scripts) directory
+ - `:local` - use `$HOME/.local/bin`
+ - `:system` - use `/usr/local/bin`
+ - `:windowsapps` - use `%LOCALAPPDATA%\Microsoft\WindowsApps`

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,