Release 0.1.9

HISTORY.md

@@ -1,3 +1,9 @@
+### Version 0.1.9
+
+#### New features
+
+* [feat(set_env)](https://github.com/MODFLOW-USGS/modflow-devtools/commit/53b31cce34d221bade4c842efe3b5ed3034b2742): Add set_env contextmanager utility (#87). Committed by w-bonelli on 2023-07-26.
+
 ### Version 0.1.8
 
 #### New features

docs/conf.py

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

docs/md/doctoc.md

@@ -1,11 +1,46 @@
 # Generating TOCs
 
-The [`doctoc`](https://www.npmjs.com/package/doctoc) tool can be used to automatically generate table of contents sections for markdown files. `doctoc` is distributed with the [Node Package Manager](https://docs.npmjs.com/cli/v7/configuring-npm/install). With Node installed use `npm install -g doctoc` to install `doctoc` globally. Then just run `doctoc <file>`, e.g.:
+The [`doctoc`](https://www.npmjs.com/package/doctoc) tool generates table of contents sections for markdown files.
+
+## Installing Node.js, `npm` and `doctoc``
+
+`doctoc` is distributed with the [Node Package Manager](https://docs.npmjs.com/cli/v7/configuring-npm/install). [Node](https://nodejs.org/en) is a JavaScript runtime environment.
+
+On Ubuntu, Node can be installed with:
+
+```shell
+sudo apt update
+sudo apt install nodejs
+```
+
+On Windows, with [Chocolatey](https://community.chocolatey.org/packages/nodejs):
+
+```shell
+choco install nodejs
+```
+
+Installers and binaries for Windows and macOS are [available for download](https://nodejs.org/en/download).
+
+Once Node is installed, install `doctoc` with:
+
+```shell
+npm install -g doctoc
+```
+
+## Using `doctoc`
+
+Then TOCs can be generated with `doctoc <file>`, e.g.:
 
 ```shell
 doctoc DEVELOPER.md
 ```
 
-This will insert HTML comments surrounding an automatically edited region, scanning for headers and creating an appropriately indented TOC tree.  Subsequent runs are idempotent, updating if the file has changed or leaving it untouched if not.
+This will insert HTML comments surrounding an automatically edited region, in which `doctoc` will create an appropriately indented TOC tree. Subsequent runs are idempotent, scanning for headers and only updating the TOC if the file header structure has changed.
+
+To run `doctoc` for all markdown files in a particular directory (recursive), use `doctoc some/path`.
+
+By default `doctoc` inserts a self-descriptive comment
+
+> **Table of Contents** *generated with DocToc*
 
-To run `doctoc` for all markdown files in a particular directory (recursive), use `doctoc some/path`.
+This can be removed (and other content within the TOC region edited) &mdash; `doctoc` will not overwrite it, only the table.

modflow_devtools/__init__.py

@@ -1,6 +1,6 @@
 __author__ = "Joseph D. Hughes"
-__date__ = "Apr 21, 2023"
-__version__ = "0.1.8"
+__date__ = "Jul 26, 2023"
+__version__ = "0.1.9"
 __maintainer__ = "Joseph D. Hughes"
 __email__ = "[email protected]"
 __status__ = "Production"

modflow_devtools/misc.py

@@ -29,6 +29,39 @@ def set_dir(path: PathLike):
         print(f"Returned to previous directory: {origin}")
 
 
+@contextmanager
+def set_env(*remove, **update):
+    """
+    Temporarily updates the ``os.environ`` dictionary in-place.
+
+    Referenced from https://stackoverflow.com/a/34333710/6514033.
+
+    The ``os.environ`` dictionary is updated in-place so that the modification
+    is sure to work in all situations.
+
+    :param remove: Environment variables to remove.
+    :param update: Dictionary of environment variables and values to add/update.
+    """
+    env = environ
+    update = update or {}
+    remove = remove or []
+
+    # List of environment variables being updated or removed.
+    stomped = (set(update.keys()) | set(remove)) & set(env.keys())
+    # Environment variables and values to restore on exit.
+    update_after = {k: env[k] for k in stomped}
+    # Environment variables and values to remove on exit.
+    remove_after = frozenset(k for k in update if k not in env)
+
+    try:
+        env.update(update)
+        [env.pop(k, None) for k in remove]
+        yield
+    finally:
+        env.update(update_after)
+        [env.pop(k) for k in remove_after]
+
+
 class add_sys_path:
     """
     Context manager for temporarily editing the system path

modflow_devtools/test/test_misc.py

@@ -11,6 +11,7 @@
     get_packages,
     has_package,
     set_dir,
+    set_env,
 )
 
 
@@ -21,6 +22,22 @@ def test_set_dir(tmp_path):
     assert Path(os.getcwd()) != tmp_path
 
 
+def test_set_env(tmp_path):
+    # test adding a variable
+    key = "TEST_ENV"
+    val = "test"
+    assert environ.get(key) is None
+    with set_env(**{key: val}):
+        assert environ.get(key) == val
+    with set_env(TEST_ENV=val):
+        assert environ.get(key) == val
+
+    # test removing a variable
+    with set_env(**{key: val}):
+        with set_env(key):
+            assert environ.get(key) is None
+
+
 _repos_path = environ.get("REPOS_PATH")
 if _repos_path is None:
     _repos_path = Path(__file__).parent.parent.parent.parent
@@ -167,7 +184,7 @@ def test_get_model_paths_largetestmodels():
 def test_get_model_paths_exclude_patterns(models):
     path, expected_count = models
     paths = get_model_paths(path, excluded=["gwt"])
-    assert len(paths) == expected_count
+    assert len(paths) >= expected_count
 
 
 @pytest.mark.skipif(
@@ -210,7 +227,7 @@ def test_get_namefile_paths_largetestmodels():
 def test_get_namefile_paths_exclude_patterns(models):
     path, expected_count = models
     paths = get_namefile_paths(path, excluded=["gwf"])
-    assert len(paths) == expected_count
+    assert len(paths) >= expected_count
 
 
 @pytest.mark.skipif(not any(_example_paths), reason="examples not found")
@@ -225,10 +242,10 @@ def test_get_namefile_paths_select_prefix():
 @pytest.mark.skipif(not any(_example_paths), reason="examples not found")
 def test_get_namefile_paths_select_patterns():
     paths = get_namefile_paths(_examples_path, selected=["gwf"])
-    assert len(paths) == 70
+    assert len(paths) >= 70
 
 
 @pytest.mark.skipif(not any(_example_paths), reason="examples not found")
 def test_get_namefile_paths_select_packages():
     paths = get_namefile_paths(_examples_path, packages=["wel"])
-    assert len(paths) == 43
+    assert len(paths) >= 43

version.txt

@@ -1 +1 @@
-0.1.8
+0.1.9