Update local_uuid configuration, deprecating prior variable

`case_utils.local_uuid` provides a deterministic UUIDv5 generator based
on the execution environment.  Unfortunately, its prior implementation
was not behaving correctly when changing environments - a different
operating system, or working in a different rooted directory, would
cause UUID churn.

The issue turned out to be paths embedding in two manners:
1. The prior implementation assumed work happening somewhere under a
   user-home directory.  This is not always true.
2. The prior implementation did not catch that for a program
   `pip`-installed into a virtual environment in editable mode (or,
   possibly more generally than that), `sys.argv[0]` is the absolute
   path to the installed command in the virtual environment root.
   Hence, changing operating systems from macOS to Linux would change
   `/Users/me` to `/home/me` within the UUID seeding data.

This patch revises the practice from functionally operating in a
Boolean manner ("Was this special string passed?") to passing an
anchoring directory, preferably the repository's Git-root directory.

Usage of the prior variable `DEMO_UUID_REQUESTING_NONRANDOM` is now
deprecated, raising a warning.

A test is also added to confirm new warnings are raised.

A follow-on patch will regenerate Make-managed files.

Signed-off-by: Alex Nelson <alexander.nelson@nist.gov>

Author: ajnelson-nist

case_utils/local_uuid.py

@@ -17,20 +17,91 @@
 
 __version__ = "0.2.0"
 
+import logging
 import os
+import pathlib
 import sys
+import typing
+import warnings
 import uuid
 
-USE_DEMO_UUID: bool = False
+DEMO_UUID_BASE: typing.Optional[str] = None
 
 DEMO_UUID_COUNTER: int = 0
 
+_logger = logging.getLogger(pathlib.Path(__file__).name)
+
 
 def configure() -> None:
-    global USE_DEMO_UUID
+    global DEMO_UUID_BASE
 
     if os.getenv("DEMO_UUID_REQUESTING_NONRANDOM") == "NONRANDOM_REQUESTED":
-        USE_DEMO_UUID = True
+        warnings.warn(
+            "Environment variable DEMO_UUID_REQUESTING_NONRANDOM is deprecated.  See case_utils.local_uuid.demo_uuid for usage notes on its replacement, CASE_DEMO_NONRANDOM_UUID_BASE.  Proceeding with random UUIDs.",
+            DeprecationWarning,
+        )
+        return
+
+    env_base_dir_name = os.getenv("CASE_DEMO_NONRANDOM_UUID_BASE")
+    if env_base_dir_name is None:
+        return
+
+    base_dir_original_path = pathlib.Path(env_base_dir_name)
+    if not base_dir_original_path.exists():
+        warnings.warn(
+            "Environment variable CASE_DEMO_NONRANDOM_UUID_BASE is expected to refer to an existing directory.  Proceeding with random UUIDs."
+        )
+        return
+    if not base_dir_original_path.is_dir():
+        warnings.warn(
+            "Environment variable CASE_DEMO_NONRANDOM_UUID_BASE is expected to refer to a directory.  Proceeding with random UUIDs."
+        )
+        return
+
+    # Component: An emphasis this is an example.
+    demo_uuid_base_parts = ["example.org"]
+
+    # Component: Present working directory, relative to CASE_DEMO_NONRANDOM_UUID_BASE if that environment variable is an ancestor of pwd.
+    base_dir_resolved_path = base_dir_original_path.resolve()
+    srcdir_original_path = pathlib.Path(os.getcwd())
+    srcdir_resolved_path = srcdir_original_path.resolve()
+    # _logger.debug("base_dir_resolved_path = %r.", base_dir_resolved_path)
+    # _logger.debug("srcdir_resolved_path = %r.", srcdir_resolved_path)
+    try:
+        srcdir_relative_path = srcdir_resolved_path.relative_to(base_dir_resolved_path)
+        # _logger.debug("srcdir_relative_path = %r.", srcdir_relative_path)
+        demo_uuid_base_parts.append(str(srcdir_relative_path))
+    except ValueError:
+        # If base_dir is not an ancestor directory of srcdir, default to srcdir.
+        # _logger.debug("PWD is not relative to base path.")
+        demo_uuid_base_parts.append(str(srcdir_resolved_path))
+
+    # Component: Command of argument vector.
+    env_venv_name = os.getenv("VIRTUAL_ENV")
+    if env_venv_name is None:
+        demo_uuid_base_parts.append(sys.argv[0])
+    else:
+        command_original_path = pathlib.Path(sys.argv[0])
+        command_resolved_path = command_original_path.resolve()
+        venv_original_path = pathlib.Path(env_venv_name)
+        venv_resolved_path = venv_original_path.resolve()
+        try:
+            command_relative_path = command_resolved_path.relative_to(
+                venv_resolved_path
+            )
+            # _logger.debug("command_relative_path = %r.", command_relative_path)
+            demo_uuid_base_parts.append(str(command_relative_path))
+        except ValueError:
+            # _logger.debug("Command path is not relative to virtual environment path.")
+            demo_uuid_base_parts.append(str(command_resolved_path))
+
+    if len(sys.argv) > 1:
+        # Component: Arguments of argument vector.
+        demo_uuid_base_parts.extend(sys.argv[1:])
+
+    # _logger.debug("demo_uuid_base_parts = %r.", demo_uuid_base_parts)
+
+    DEMO_UUID_BASE = "/".join(demo_uuid_base_parts)
 
 
 def demo_uuid() -> str:
@@ -39,38 +110,34 @@ def demo_uuid() -> str:
 
     WARNING: This function was developed for use ONLY for reducing (but not eliminating) version-control edits to identifiers in sample data.  It creates UUIDs that are decidedly NOT random, and should remain consistent on repeated calls to the importing script.
 
-    To prevent accidental non-random UUID usage, an environment variable must be set to an uncommon string, hard-coded in this function.
+    To prevent accidental non-random UUID usage, an environment variable must be set to a string provided by the caller.  The variable's required value is the path to some directory.  The variable's recommended value is the equivalent of the Make variable "top_srcdir" - that is, the root directory of the containing Git repository, some parent of the current process's current working directory.
     """
+    global DEMO_UUID_BASE
     global DEMO_UUID_COUNTER
 
-    if os.getenv("DEMO_UUID_REQUESTING_NONRANDOM") != "NONRANDOM_REQUESTED":
-        raise EnvironmentError(
-            "demo_uuid() called without DEMO_UUID_REQUESTING_NONRANDOM in environment."
+    if os.getenv("CASE_DEMO_NONRANDOM_UUID_BASE") is None:
+        raise ValueError(
+            "demo_uuid() called without CASE_DEMO_NONRANDOM_UUID_BASE in environment."
         )
 
-    # Component: An emphasis this is an example.
-    parts = ["example.org"]
+    if DEMO_UUID_BASE is None:
+        raise ValueError("demo_uuid() called with DEMO_UUID_BASE unset.")
+
+    parts = [DEMO_UUID_BASE]
 
     # Component: Incrementing counter.
     DEMO_UUID_COUNTER += 1
     parts.append(str(DEMO_UUID_COUNTER))
 
-    # Component: Present working directory, replacing $HOME with '~'.
-    env_HOME: str = os.getenv("HOME", "/nonexistent")
-    parts.append(os.getcwd().replace(env_HOME, "~"))
-
-    # Component: Argument vector.
-    parts.extend(sys.argv)
-
     return str(uuid.uuid5(uuid.NAMESPACE_URL, "/".join(parts)))
 
 
 def local_uuid() -> str:
     """
     Generate either a UUID4, or if requested via environment configuration, a non-random demo UUID.
     """
-    global USE_DEMO_UUID
-    if USE_DEMO_UUID:
-        return demo_uuid()
-    else:
+    global DEMO_UUID_BASE
+    if DEMO_UUID_BASE is None:
         return str(uuid.uuid4())
+    else:
+        return demo_uuid()

tests/case_utils/case_file/Makefile

@@ -114,7 +114,7 @@ sample.txt.json: \
   $(top_srcdir)/case_utils/namespace.py \
   sample.txt-nocompact.json
 	rm -f $@ _$@ __$@
-	export DEMO_UUID_REQUESTING_NONRANDOM=NONRANDOM_REQUESTED \
+	export CASE_DEMO_NONRANDOM_UUID_BASE="$(top_srcdir)" \
 	  && source $(tests_srcdir)/venv/bin/activate \
 	    && case_file \
 	      --debug \
@@ -147,7 +147,7 @@ sample.txt.ttl: \
   $(top_srcdir)/case_utils/namespace.py \
   sample.txt.done.log
 	rm -f _$@ __$@
-	export DEMO_UUID_REQUESTING_NONRANDOM=NONRANDOM_REQUESTED \
+	export CASE_DEMO_NONRANDOM_UUID_BASE="$(top_srcdir)" \
 	  && source $(tests_srcdir)/venv/bin/activate \
 	    && case_file \
 	      --debug \
@@ -171,7 +171,7 @@ sample.txt-disable_hashes.ttl: \
   $(top_srcdir)/case_utils/namespace.py \
   sample.txt.done.log
 	rm -f _$@ __$@
-	export DEMO_UUID_REQUESTING_NONRANDOM=NONRANDOM_REQUESTED \
+	export CASE_DEMO_NONRANDOM_UUID_BASE="$(top_srcdir)" \
 	  && source $(tests_srcdir)/venv/bin/activate \
 	    && case_file \
 	      --debug \
@@ -197,7 +197,7 @@ sample.txt-nocompact.json: \
   $(top_srcdir)/case_utils/namespace.py \
   sample.txt.done.log
 	rm -f _$@
-	export DEMO_UUID_REQUESTING_NONRANDOM=NONRANDOM_REQUESTED \
+	export CASE_DEMO_NONRANDOM_UUID_BASE="$(top_srcdir)" \
 	  && source $(tests_srcdir)/venv/bin/activate \
 	    && case_file \
 	      --debug \

tests/case_utils/test_local_uuid.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+
+# This software was developed at the National Institute of Standards
+# and Technology by employees of the Federal Government in the course
+# of their official duties. Pursuant to title 17 Section 105 of the
+# United States Code this software is not subject to copyright
+# protection and is in the public domain. NIST assumes no
+# responsibility whatsoever for its use by other parties, and makes
+# no guarantees, expressed or implied, about its quality,
+# reliability, or any other characteristic.
+#
+# We would appreciate acknowledgement if the software is used.
+
+import os
+
+import pytest
+
+import case_utils.local_uuid
+
+
+def test_local_uuid_deprecation(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("DEMO_UUID_REQUESTING_NONRANDOM", "NONRANDOM_REQUESTED")
+    with pytest.warns(DeprecationWarning):
+        case_utils.local_uuid.configure()
+
+
+def test_local_uuid_nondirectory(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CASE_DEMO_NONRANDOM_UUID_BASE", "/dev/null")
+    with pytest.warns(UserWarning):
+        case_utils.local_uuid.configure()
+
+
+def test_local_uuid_nonexistent(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CASE_DEMO_NONRANDOM_UUID_BASE", "/dev/nonexistent")
+    with pytest.warns(UserWarning):
+        case_utils.local_uuid.configure()