Repository: jaraco/pip-run

Issue:
Consider renaming PIP_RUN_MODE
In #82, I'm considering renaming the variable name "mode". The name is too general - doesn't convey its specific purpose.

Here are some alternatives I'm considering:

- _target_: building on the name of the parameter used by pip
- _install target_: incorporating the name of the command and parameter used by pip
- _env_: inspired by the name of the "environment"
- _environment_: full spelling of above
- _retention_: captures the concept around persisting or not
- _strategy_ suffix: any of the above with "strategy" appended

I'm liking PIP_RUN_ENVIRONMENT_STRATEGY and PIP_RUN_RETENTION_STRATEGY best.

Discussion:

Patch:
diff --git a/README.rst b/README.rst
index 74d20d6..caa565b 100644
--- a/README.rst
+++ b/README.rst
@@ -347,27 +347,26 @@ For specifics, see `pip_run.run()
 Environment Persistence
 =======================
 
-``pip-run`` honors the ``PIP_RUN_MODE`` variable. If unset or
-set to ``ephemeral``, dependencies are installed to an ephemeral
-temporary directory on each invocation (and deleted after).
-Setting this variable to ``persist`` will instead create or re-use
-a directory in the user's cache, only installing the dependencies if
-the directory doesn't already exist. A separate cache is maintained
-for each combination of requirements specified.
-
-``persist`` mode can greatly improve startup performance at the
-expense of staleness and accumulated cruft.
-
-Without ``PIP_RUN_MODE=persist`` (or with ``=ephemeral``), ``pip-run`` will
-re-install dependencies every time a script runs, silently adding to the
-startup time while dependencies are installed into an ephemeral environment,
-depending on how many dependencies there are and whether the dependencies have
-been previously downloaded to the local pip cache. Use ``pip-run -v ...`` to
-see the installation activity.
+``pip-run`` honors the ``PIP_RUN_RETENTION_STRATEGY`` variable. If unset or
+set to ``destroy``, dependencies are installed to a temporary directory on
+each invocation (and deleted after). Setting this variable to ``persist`` will
+instead create or re-use a directory in the user's cache, only installing the
+dependencies if the directory doesn't already exist. A separate cache is
+maintained for each combination of requirements specified.
+
+``persist`` strategy can greatly improve startup performance at the expense of
+staleness and accumulated cruft.
+
+Without ``PIP_RUN_RETENTION_STRATEGY=persist`` (or with ``=destroy``),
+``pip-run`` will re-install dependencies every time a script runs, silently
+adding to the startup time while dependencies are installed into an ephemeral
+environment, depending on how many dependencies there are and whether the
+dependencies have been previously downloaded to the local pip cache. Use
+``pip-run -v ...`` to see the installation activity.
 
 The location of the cache can be revealed with this command::
 
-    py -c 'import importlib; print(importlib.import_module("pip_run.mode.persist").paths.user_cache_path)'
+    py -c 'import importlib; print(importlib.import_module("pip_run.retention.persist").paths.user_cache_path)'
 
 
 Limitations
diff --git a/newsfragments/84.feature.rst b/newsfragments/84.feature.rst
new file mode 100644
index 0000000..91a1925
--- /dev/null
+++ b/newsfragments/84.feature.rst
@@ -0,0 +1,1 @@
+Renamed PIP_RUN_MODE variable to PIP_RUN_RETENTION_STRATEGY. Also renamed the default value of 'ephemeral' to 'destroy'. If PIP_RUN_MODE is used, a warning is emitted.
diff --git a/pip_run/deps.py b/pip_run/deps.py
index b6cad31..48e9eaa 100644
--- a/pip_run/deps.py
+++ b/pip_run/deps.py
@@ -8,6 +8,7 @@ import argparse
 import pathlib
 import types
 import importlib
+import warnings
 
 import packaging.requirements
 from jaraco.context import suppress
@@ -53,9 +54,19 @@ class Install(types.SimpleNamespace):
         return bool(self.requirement or self.package)
 
 
-def mode():
-    mode = os.environ.get('PIP_RUN_MODE', 'ephemeral')
-    return importlib.import_module(f'.mode.{mode}', package=__package__)
+def _mode_compat():
+    if mode := os.environ.get('PIP_RUN_MODE'):  # pragma: no cover
+        warnings.warn(
+            'PIP_RUN_MODE is deprecated. Use PIP_RUN_RETENTION_STRATEGY instead.',
+        )
+        return mode.replace('ephemeral', 'destroy')
+
+
+def retention_strategy():
+    strategy = (
+        os.environ.get('PIP_RUN_RETENTION_STRATEGY') or _mode_compat() or 'destroy'
+    )
+    return importlib.import_module(f'.retention.{strategy}', package=__package__)
 
 
 @suppress(FileNotFoundError)
@@ -82,7 +93,7 @@ def empty(path):
 
 @contextlib.contextmanager
 def load(*args):
-    with mode().context(args) as target:
+    with retention_strategy().context(args) as target:
         cmd = (sys.executable, '-m', 'pip', 'install', '-t', sp(target)) + args
         env = dict(os.environ, PIP_QUIET="1")
         if Install.parse(args) and empty(target):


Test patch:
diff --git a/conftest.py b/conftest.py
index a24218a..817bcc8 100644
--- a/conftest.py
+++ b/conftest.py
@@ -6,7 +6,7 @@ import textwrap
 import jaraco.path
 import pytest
 
-import pip_run.mode.persist
+import pip_run.retention.persist
 
 
 collect_ignore = ['examples']
@@ -48,12 +48,12 @@ def alt_cache_dir(monkeypatch_session, tmp_path_factory):
     class Paths:
         user_cache_path = alt_cache
 
-    monkeypatch_session.setattr(pip_run.mode.persist, 'paths', Paths)
+    monkeypatch_session.setattr(pip_run.retention.persist, 'paths', Paths)
 
 
-@pytest.fixture(params=['persist', 'ephemeral'])
-def run_mode(monkeypatch, request):
-    monkeypatch.setenv('PIP_RUN_MODE', request.param)
+@pytest.fixture(params=['persist', 'destroy'])
+def retention_strategy(monkeypatch, request):
+    monkeypatch.setenv('PIP_RUN_RETENTION_STRATEGY', request.param)
 
 
 @pytest.fixture
diff --git a/pip_run/mode/__init__.py b/pip_run/retention/__init__.py
similarity index 100%
rename from pip_run/mode/__init__.py
rename to pip_run/retention/__init__.py
diff --git a/pip_run/mode/ephemeral.py b/pip_run/retention/destroy.py
similarity index 100%
rename from pip_run/mode/ephemeral.py
rename to pip_run/retention/destroy.py
diff --git a/pip_run/mode/persist.py b/pip_run/retention/persist.py
similarity index 100%
rename from pip_run/mode/persist.py
rename to pip_run/retention/persist.py
diff --git a/tests/test_deps.py b/tests/test_deps.py
index 34afd9f..15dd767 100644
--- a/tests/test_deps.py
+++ b/tests/test_deps.py
@@ -31,7 +31,7 @@ class TestInstallCheck:
         assert list(filtered) == expected
 
 
-@pytest.mark.usefixtures('run_mode')
+@pytest.mark.usefixtures('retention_strategy')
 class TestLoad:
     def test_no_args_passes(self):
         """
@@ -50,9 +50,8 @@ class TestLoad:
             pass
 
 
-@pytest.mark.usefixtures('run_mode')
-def test_target_mode_context():
+@pytest.mark.usefixtures('retention_strategy')
+def test_target_retention_context():
     """Verify a target exists or can be created."""
-    mode = deps.mode()
-    with mode.context([]) as target:
+    with deps.retention_strategy().context([]) as target:
         target.mkdir(exist_ok=True)