Switch to PIP_RUN_RETENTION_STRATEGY from mode

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

conftest.py

@@ -6,7 +6,7 @@
 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

newsfragments/84.feature.rst

@@ -0,0 +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.

pip_run/deps.py

@@ -8,6 +8,7 @@
 import pathlib
 import types
 import importlib
+import warnings
 
 import packaging.requirements
 from jaraco.context import suppress
@@ -53,9 +54,19 @@ def __bool__(self):
         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):

tests/test_deps.py

@@ -31,7 +31,7 @@ def test_not_installed_args(self):
         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 @@ def test_only_options_passes(self):
             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)