pydepinject 0.0.3.dev0__tar.gz → 0.0.5.dev0__tar.gz

{pydepinject-0.0.3.dev0/src/pydepinject.egg-info → pydepinject-0.0.5.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydepinject
-Version: 0.0.3.dev0
+Version: 0.0.5.dev0
 Summary: A package to dynamically inject requirements into a virtual environment.
 Author: pydepinject
 License-Expression: MIT
@@ -17,10 +17,10 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: packaging>=23.0
+Requires-Dist: packaging>=24.0
 Requires-Dist: typing-extensions>=4.4.0
 Provides-Extra: lint
 Requires-Dist: isort; extra == "lint"
@@ -64,9 +64,11 @@ from pydepinject import requires
 def my_function():
     import requests
     import numpy as np
+
     print(requests.__version__)
     print(np.__version__)
 
+
 my_function()
 ```
 
@@ -81,6 +83,7 @@ from pydepinject import requires
 with requires("requests", "numpy"):
     import requests
     import numpy as np
+
     print(requests.__version__)
     print(np.__version__)
 ```
@@ -93,30 +96,38 @@ The `requires` can create a virtual environment with a specific name:
 @requires("requests", venv_name="myenv")
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests", venv_name="myenv"):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 
 
 # The virtual environment name can also be set as PYDEPINJECT_VENV_NAME environment variable
 import os
+
 os.environ["PYDEPINJECT_VENV_NAME"] = "myenv"
 
+
 @requires("requests")
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests"):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 ```
 
@@ -130,13 +141,16 @@ The `requires` can create named virtual environments and reuse them across multi
 @requires("requests", venv_name="myenv", ephemeral=False)
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests", venv_name="myenv", ephemeral=False):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 ```
 
@@ -148,8 +162,10 @@ The `requires` can automatically delete ephemeral virtual environments after use
 @requires("requests", venv_name="myenv", ephemeral=True)
 def my_function():
     import requests
+
     print(requests.__version__)
 
+
 my_function()
 ```
 
@@ -160,12 +176,15 @@ If you need to ensure a completely clean environment, you can force its recreati
 ```python
 from pydepinject import requires
 
+
 # This will delete the "my-clean-env" venv if it exists and create it from scratch
 @requires("requests", venv_name="my-clean-env", recreate=True)
 def my_function():
     import requests
+
     print(requests.__version__)
 
+
 my_function()
 ```
 
@@ -199,16 +218,20 @@ You can forward extra arguments to the underlying installer (pip or uv pip) via
 ```python
 from pydepinject import requires
 
+
 @requires(
     "requests",
     install_args=(
-        "--index-url", "https://pypi.myorg/simple",
-        "--upgrade-strategy", "eager",
+        "--index-url",
+        "https://pypi.myorg/simple",
+        "--upgrade-strategy",
+        "eager",
     ),
     venv_backend="venv",
 )
 def my_function():
     import requests
+
     print(requests.__version__)
 ```
 
@@ -243,6 +266,84 @@ This helps with debugging and reproducibility.
 
 These variables provide a convenient way to standardize behavior in CI/CD pipelines or development environments.
 
+## Where venvs are stored and cleaning them up
+
+Each managed environment is a plain virtual environment directory under a single
+root. By default that root is `<system-temp-dir>/pydepinject/venvs` (overridable
+with `PYDEPINJECT_VENV_ROOT`), and each venv is a subdirectory named either after
+your `venv_name` or a content hash derived from the requirement set, Python
+version, and backend.
+
+Because the default root lives under the OS temporary directory, the operating
+system usually reclaims it for you — temp-file cleaners and reboots clear stale
+entries — so in the common case there is **nothing to clean up manually**.
+
+For finer control:
+
+- **Avoid persistence per call**: pass `ephemeral=True` so the venv is deleted as
+  soon as the decorated function or `with` block finishes.
+- **Prune a persistent root you manage**: the venvs are just directories, so
+  `rm -rf "$PYDEPINJECT_VENV_ROOT"` removes everything, or delete individual
+  subdirectories to reclaim space selectively.
+- **Script age-based cleanup**: each venv contains `.pydepinject-*.json` metadata
+  files recording the install timestamp (and the packages installed), which you
+  can use to find and remove environments older than a chosen age.
+
+## Limitations and thread-safety
+
+`pydepinject` works by mutating **process-global interpreter state** for the
+duration of the managed scope (the decorated call or `with` block). When a
+requirement is not already importable, it:
+
+- inserts the venv's `site-packages` at the front of `sys.path`,
+- prepends to the `PYTHONPATH` and `PATH` environment variables,
+- evicts conflicting entries from `sys.modules` so fresh imports resolve to the venv.
+
+The original `sys.path`, environment variables, and `sys.modules` state are
+restored when the scope exits. If every requested package is already satisfied in
+the current environment, **no global state is changed at all** — activation is a
+no-op fast path.
+
+Because this state is global to the interpreter, please keep the following in mind:
+
+- **Not thread-safe and not safe under `asyncio`/concurrent use.** Two managed
+  scopes active at the same time in different threads (or interleaved coroutines)
+  will race on `sys.path`, the environment variables, and `sys.modules`, and can
+  corrupt each other's save/restore. Use `pydepinject` from a single thread of
+  control. If you need dependencies isolated across concurrent workers, give each
+  worker its own **process**.
+- **Already-imported modules are handled best-effort.** If a package was already
+  imported earlier in the process from a different location, swapping it for the
+  venv's copy within the scope cannot be guaranteed — code holding a reference to
+  the previously imported module keeps using it.
+- **It mutates the running interpreter, by design.** This makes it ideal for
+  scripts, notebooks, plugins, and ad-hoc tooling, but it is **not** a substitute
+  for a properly provisioned environment or a lockfile in a production
+  application. For those, prefer real environment/dependency management.
+
+## When NOT to use this
+
+`pydepinject` is built for **scripts, notebooks, plugins, and ad-hoc tooling or
+CI glue** — cases where "make sure X is importable, install it if not" is the
+whole job. It is the wrong tool, and you should reach for a real
+environment plus a lockfile (`uv`, `pip-tools`, Poetry, etc.) instead, when:
+
+- You are building a **deployable application or service** where dependency
+  reproducibility matters.
+- Your code runs under **threads, `asyncio`, or parallel workers** — activation
+  mutates global interpreter state and is not safe to interleave (see
+  [Limitations and thread-safety](#limitations-and-thread-safety); give each
+  worker its own process).
+- You need **pinned, audited, reproducible** dependency sets across machines and
+  CI runs.
+- Packages are **already imported** earlier in the process and must be swapped
+  mid-run — `pydepinject` can only do this best-effort.
+- You run a **long-lived production process** where persistent venvs accumulating
+  under the temp root would be a problem.
+
+For the mechanics behind these caveats, see
+[Limitations and thread-safety](#limitations-and-thread-safety) above.
+
 ## Unit Tests
 
 Unit tests are provided to verify the functionality of the `requires`. The tests use `pytest` and cover various scenarios including decorator usage, context manager usage, ephemeral environments, and more.

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0}/README.md

@@ -31,9 +31,11 @@ from pydepinject import requires
 def my_function():
     import requests
     import numpy as np
+
     print(requests.__version__)
     print(np.__version__)
 
+
 my_function()
 ```
 
@@ -48,6 +50,7 @@ from pydepinject import requires
 with requires("requests", "numpy"):
     import requests
     import numpy as np
+
     print(requests.__version__)
     print(np.__version__)
 ```
@@ -60,30 +63,38 @@ The `requires` can create a virtual environment with a specific name:
 @requires("requests", venv_name="myenv")
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests", venv_name="myenv"):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 
 
 # The virtual environment name can also be set as PYDEPINJECT_VENV_NAME environment variable
 import os
+
 os.environ["PYDEPINJECT_VENV_NAME"] = "myenv"
 
+
 @requires("requests")
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests"):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 ```
 
@@ -97,13 +108,16 @@ The `requires` can create named virtual environments and reuse them across multi
 @requires("requests", venv_name="myenv", ephemeral=False)
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests", venv_name="myenv", ephemeral=False):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 ```
 
@@ -115,8 +129,10 @@ The `requires` can automatically delete ephemeral virtual environments after use
 @requires("requests", venv_name="myenv", ephemeral=True)
 def my_function():
     import requests
+
     print(requests.__version__)
 
+
 my_function()
 ```
 
@@ -127,12 +143,15 @@ If you need to ensure a completely clean environment, you can force its recreati
 ```python
 from pydepinject import requires
 
+
 # This will delete the "my-clean-env" venv if it exists and create it from scratch
 @requires("requests", venv_name="my-clean-env", recreate=True)
 def my_function():
     import requests
+
     print(requests.__version__)
 
+
 my_function()
 ```
 
@@ -166,16 +185,20 @@ You can forward extra arguments to the underlying installer (pip or uv pip) via
 ```python
 from pydepinject import requires
 
+
 @requires(
     "requests",
     install_args=(
-        "--index-url", "https://pypi.myorg/simple",
-        "--upgrade-strategy", "eager",
+        "--index-url",
+        "https://pypi.myorg/simple",
+        "--upgrade-strategy",
+        "eager",
     ),
     venv_backend="venv",
 )
 def my_function():
     import requests
+
     print(requests.__version__)
 ```
 
@@ -210,6 +233,84 @@ This helps with debugging and reproducibility.
 
 These variables provide a convenient way to standardize behavior in CI/CD pipelines or development environments.
 
+## Where venvs are stored and cleaning them up
+
+Each managed environment is a plain virtual environment directory under a single
+root. By default that root is `<system-temp-dir>/pydepinject/venvs` (overridable
+with `PYDEPINJECT_VENV_ROOT`), and each venv is a subdirectory named either after
+your `venv_name` or a content hash derived from the requirement set, Python
+version, and backend.
+
+Because the default root lives under the OS temporary directory, the operating
+system usually reclaims it for you — temp-file cleaners and reboots clear stale
+entries — so in the common case there is **nothing to clean up manually**.
+
+For finer control:
+
+- **Avoid persistence per call**: pass `ephemeral=True` so the venv is deleted as
+  soon as the decorated function or `with` block finishes.
+- **Prune a persistent root you manage**: the venvs are just directories, so
+  `rm -rf "$PYDEPINJECT_VENV_ROOT"` removes everything, or delete individual
+  subdirectories to reclaim space selectively.
+- **Script age-based cleanup**: each venv contains `.pydepinject-*.json` metadata
+  files recording the install timestamp (and the packages installed), which you
+  can use to find and remove environments older than a chosen age.
+
+## Limitations and thread-safety
+
+`pydepinject` works by mutating **process-global interpreter state** for the
+duration of the managed scope (the decorated call or `with` block). When a
+requirement is not already importable, it:
+
+- inserts the venv's `site-packages` at the front of `sys.path`,
+- prepends to the `PYTHONPATH` and `PATH` environment variables,
+- evicts conflicting entries from `sys.modules` so fresh imports resolve to the venv.
+
+The original `sys.path`, environment variables, and `sys.modules` state are
+restored when the scope exits. If every requested package is already satisfied in
+the current environment, **no global state is changed at all** — activation is a
+no-op fast path.
+
+Because this state is global to the interpreter, please keep the following in mind:
+
+- **Not thread-safe and not safe under `asyncio`/concurrent use.** Two managed
+  scopes active at the same time in different threads (or interleaved coroutines)
+  will race on `sys.path`, the environment variables, and `sys.modules`, and can
+  corrupt each other's save/restore. Use `pydepinject` from a single thread of
+  control. If you need dependencies isolated across concurrent workers, give each
+  worker its own **process**.
+- **Already-imported modules are handled best-effort.** If a package was already
+  imported earlier in the process from a different location, swapping it for the
+  venv's copy within the scope cannot be guaranteed — code holding a reference to
+  the previously imported module keeps using it.
+- **It mutates the running interpreter, by design.** This makes it ideal for
+  scripts, notebooks, plugins, and ad-hoc tooling, but it is **not** a substitute
+  for a properly provisioned environment or a lockfile in a production
+  application. For those, prefer real environment/dependency management.
+
+## When NOT to use this
+
+`pydepinject` is built for **scripts, notebooks, plugins, and ad-hoc tooling or
+CI glue** — cases where "make sure X is importable, install it if not" is the
+whole job. It is the wrong tool, and you should reach for a real
+environment plus a lockfile (`uv`, `pip-tools`, Poetry, etc.) instead, when:
+
+- You are building a **deployable application or service** where dependency
+  reproducibility matters.
+- Your code runs under **threads, `asyncio`, or parallel workers** — activation
+  mutates global interpreter state and is not safe to interleave (see
+  [Limitations and thread-safety](#limitations-and-thread-safety); give each
+  worker its own process).
+- You need **pinned, audited, reproducible** dependency sets across machines and
+  CI runs.
+- Packages are **already imported** earlier in the process and must be swapped
+  mid-run — `pydepinject` can only do this best-effort.
+- You run a **long-lived production process** where persistent venvs accumulating
+  under the temp root would be a problem.
+
+For the mechanics behind these caveats, see
+[Limitations and thread-safety](#limitations-and-thread-safety) above.
+
 ## Unit Tests
 
 Unit tests are provided to verify the functionality of the `requires`. The tests use `pytest` and cover various scenarios including decorator usage, context manager usage, ephemeral environments, and more.

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0}/pyproject.toml

@@ -14,9 +14,9 @@ authors = [
 ]
 license = "MIT"
 keywords = ["virtualenv", "requirements", "dependency management"]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
-    "packaging>=23.0",
+    "packaging>=24.0",
     "typing-extensions>=4.4.0",
 ]
 classifiers = [
@@ -54,11 +54,9 @@ packages = ["pydepinject"]
 [tool.setuptools.dynamic]
 version = {attr = "pydepinject.VERSION"}
 
-[tool.pytest]
+[tool.pytest.ini_options]
 log_cli = true
 log_level = "DEBUG"
-
-[tool.pytest.ini_options]
 pythonpath = "src"
 testpaths = ["tests"]
 addopts = "--durations=10 -n auto"
@@ -98,6 +96,7 @@ ignore = [
     "PLW2901",
     "RET503",
     "RUF005",
+    "RUF067",
     "S404",
     "S603",
     "SLF001",
@@ -137,7 +136,6 @@ reportImplicitStringConcatenation = true
 reportImportCycles = true
 reportMissingSuperCall = false
 reportPropertyTypeMismatch = true
-reportShadowedImports = true
 reportUninitializedInstanceVariable = true
 reportUnnecessaryTypeIgnoreComment = false  # reportMissingImports for tomllib is valid python<3.11.
 reportUnusedCallResult = false

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0}/src/pydepinject/__init__.py

@@ -23,7 +23,7 @@ from .backends import VenvBackendRegistry
 P = typing.ParamSpec("P")
 R = typing.TypeVar("R")
 
-VERSION = "0.0.3dev0"
+VERSION = "0.0.5dev0"
 __version__ = VERSION
 
 logger = logging.getLogger(__name__)
@@ -221,7 +221,7 @@ class RequirementManager:
             extra_args=list(self._install_args) if self._install_args else None,
         )
         # Write metadata file for traceability
-        timestamp = int(datetime.datetime.now(tz=datetime.timezone.utc).timestamp())
+        timestamp = int(datetime.datetime.now(tz=datetime.UTC).timestamp())
         meta_filepath = self.venv_path / f".pydepinject-{timestamp}.json"
         try:
             meta = {
@@ -234,7 +234,7 @@ class RequirementManager:
                 "platform": sys.platform,
                 "packages": list(self.packages),
                 "install_args": list(self._install_args),
-                "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+                "timestamp": datetime.datetime.now(datetime.UTC).isoformat(),
             }
             meta_filepath.write_text(json.dumps(meta, indent=2))
             logger.debug("Wrote venv metadata to: %s", meta_filepath)
@@ -278,8 +278,29 @@ class RequirementManager:
         self.original_path = os.environ.get("PATH", "")
         self.original_syspath = sys.path.copy()
 
+        # Once we start mutating global interpreter state, any failure (of any
+        # exception type) must restore it before propagating; otherwise the host
+        # process is left with a polluted sys.path/PATH/PYTHONPATH.
+        try:
+            return self._mutate_and_install()
+        except BaseException:
+            logger.exception("Failed to activate venv %s", self.venv_path)
+            self._deactivate_venv()
+            raise
+
+    def _mutate_and_install(self):
+        """Mutate interpreter state to point at the venv and install packages.
+
+        Assumes ``original_*`` state has already been captured by the caller so
+        that a failure here can be rolled back.
+        """
         self._create_virtualenv()
 
+        # Mark activated before mutating any global state, so an interrupt in the
+        # middle of the mutations below still triggers a full restore via
+        # _deactivate_venv (which is gated on this flag).
+        self._activated = True
+
         bin_dir = _bin_dir(self.venv_path)
         venv_site_packages = _site_packages_dir(self.venv_path)
         os.environ["PYTHONPATH"] = str(venv_site_packages) + (
@@ -287,7 +308,6 @@ class RequirementManager:
         )
         os.environ["PATH"] = str(bin_dir) + os.pathsep + self.original_path
         sys.path.insert(0, str(venv_site_packages))
-        self._activated = True
         if is_requirements_satisfied(*self.packages):
             logger.debug(
                 "Requirements %s already satisfied within %s",
@@ -301,6 +321,7 @@ class RequirementManager:
             logger.debug(
                 "Purged modules from venv %s: %s", self.venv_path, purged_modules
             )
+        return self
 
     def _deactivate_venv(self):
         if not self._activated:
@@ -316,13 +337,9 @@ class RequirementManager:
             shutil.rmtree(self.venv_path)
 
     def __enter__(self):
-        try:
-            self._activate_venv()
-        except RuntimeError:
-            logger.exception("Failed to activate venv: %s")
-            if self.ephemeral:
-                self._deactivate_venv()
-            raise
+        # _activate_venv restores global state and cleans up on any failure, so
+        # we simply let the original exception propagate.
+        self._activate_venv()
         return self
 
     def __exit__(
@@ -336,13 +353,7 @@ class RequirementManager:
 
     def __call__(self, func: Callable[P, R] | None = None) -> Callable[P, R] | None:
         if func is None:
-            try:
-                self._activate_venv()
-            except RuntimeError:
-                logger.exception("Failed to activate venv: %s")
-                if self.ephemeral:
-                    self._deactivate_venv()
-                raise
+            self._activate_venv()
             return None
 
         @functools.wraps(func)

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0}/src/pydepinject/backends.py

@@ -38,6 +38,27 @@ def _venv_python(venv_path: pathlib.Path) -> pathlib.Path:
     return _bin_dir(venv_path) / name
 
 
+def _tail(output: str, *, max_lines: int = 20, max_chars: int = 4000) -> str:
+    """Return the trailing portion of command output for an error message.
+
+    Installers print the actual failure at the end of their output, so the tail
+    is the diagnostic part. The full output is logged separately; this keeps the
+    exception message readable.
+    """
+    output = output.strip()
+    if not output:
+        return "(no output captured)"
+    lines = output.splitlines()
+    truncated = len(lines) > max_lines
+    text = "\n".join(lines[-max_lines:])
+    if len(text) > max_chars:
+        text = text[-max_chars:]
+        truncated = True
+    if truncated:
+        text = f"(truncated; see logs for full output)\n{text}"
+    return text
+
+
 class VenvBackend:
     """Abstract base class for virtual environment backends."""
 
@@ -70,17 +91,36 @@ class VenvBackend:
         """Check if the backend is supported on the current system."""
 
     def _run_command(self, cmd: list[str]) -> None:  # noqa: PLR6301
-        """Run a command in the virtual environment."""
-        logger.debug("Running command: %s", " ".join(cmd))
-        try:
-            subprocess.check_call(cmd, stdout=subprocess.DEVNULL)
-        except subprocess.CalledProcessError as e:
-            logger.exception(
-                "Command failed with exit code %d: %s", e.returncode, " ".join(cmd)
+        """Run a command in the virtual environment.
+
+        Output is captured (stdout and stderr merged) and stays quiet on success.
+        On failure the full output is logged and a trailing excerpt is included in
+        the raised ``RuntimeError`` for debuggability.
+        """
+        cmd_str = " ".join(cmd)
+        logger.debug("Running command: %s", cmd_str)
+        result = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            check=False,
+        )
+        output = result.stdout or ""
+        if result.returncode != 0:
+            logger.error(
+                "Command failed with exit code %d: %s\nOutput:\n%s",
+                result.returncode,
+                cmd_str,
+                output,
             )
-            raise RuntimeError(
-                f"Command failed with exit code {e.returncode}: {' '.join(cmd)}"
-            ) from e
+            message = "\n".join([
+                f"Command failed with exit code {result.returncode}: {cmd_str}",
+                "Output:",
+                _tail(output),
+            ])
+            raise RuntimeError(message)
+        logger.debug("Command output:\n%s", output)
 
 
 class VenvBackendRegistry:

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0/src/pydepinject.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydepinject
-Version: 0.0.3.dev0
+Version: 0.0.5.dev0
 Summary: A package to dynamically inject requirements into a virtual environment.
 Author: pydepinject
 License-Expression: MIT
@@ -17,10 +17,10 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: packaging>=23.0
+Requires-Dist: packaging>=24.0
 Requires-Dist: typing-extensions>=4.4.0
 Provides-Extra: lint
 Requires-Dist: isort; extra == "lint"
@@ -64,9 +64,11 @@ from pydepinject import requires
 def my_function():
     import requests
     import numpy as np
+
     print(requests.__version__)
     print(np.__version__)
 
+
 my_function()
 ```
 
@@ -81,6 +83,7 @@ from pydepinject import requires
 with requires("requests", "numpy"):
     import requests
     import numpy as np
+
     print(requests.__version__)
     print(np.__version__)
 ```
@@ -93,30 +96,38 @@ The `requires` can create a virtual environment with a specific name:
 @requires("requests", venv_name="myenv")
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests", venv_name="myenv"):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 
 
 # The virtual environment name can also be set as PYDEPINJECT_VENV_NAME environment variable
 import os
+
 os.environ["PYDEPINJECT_VENV_NAME"] = "myenv"
 
+
 @requires("requests")
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests"):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 ```
 
@@ -130,13 +141,16 @@ The `requires` can create named virtual environments and reuse them across multi
 @requires("requests", venv_name="myenv", ephemeral=False)
 def my_function():
     import requests
+
     print(requests.__version__)
 
 
 with requires("pylint", "requests", venv_name="myenv", ephemeral=False):
     import pylint
+
     print(pylint.__version__)
     import requests  # This is also available here because it was installed in the same virtual environment
+
     print(requests.__version__)
 ```
 
@@ -148,8 +162,10 @@ The `requires` can automatically delete ephemeral virtual environments after use
 @requires("requests", venv_name="myenv", ephemeral=True)
 def my_function():
     import requests
+
     print(requests.__version__)
 
+
 my_function()
 ```
 
@@ -160,12 +176,15 @@ If you need to ensure a completely clean environment, you can force its recreati
 ```python
 from pydepinject import requires
 
+
 # This will delete the "my-clean-env" venv if it exists and create it from scratch
 @requires("requests", venv_name="my-clean-env", recreate=True)
 def my_function():
     import requests
+
     print(requests.__version__)
 
+
 my_function()
 ```
 
@@ -199,16 +218,20 @@ You can forward extra arguments to the underlying installer (pip or uv pip) via
 ```python
 from pydepinject import requires
 
+
 @requires(
     "requests",
     install_args=(
-        "--index-url", "https://pypi.myorg/simple",
-        "--upgrade-strategy", "eager",
+        "--index-url",
+        "https://pypi.myorg/simple",
+        "--upgrade-strategy",
+        "eager",
     ),
     venv_backend="venv",
 )
 def my_function():
     import requests
+
     print(requests.__version__)
 ```
 
@@ -243,6 +266,84 @@ This helps with debugging and reproducibility.
 
 These variables provide a convenient way to standardize behavior in CI/CD pipelines or development environments.
 
+## Where venvs are stored and cleaning them up
+
+Each managed environment is a plain virtual environment directory under a single
+root. By default that root is `<system-temp-dir>/pydepinject/venvs` (overridable
+with `PYDEPINJECT_VENV_ROOT`), and each venv is a subdirectory named either after
+your `venv_name` or a content hash derived from the requirement set, Python
+version, and backend.
+
+Because the default root lives under the OS temporary directory, the operating
+system usually reclaims it for you — temp-file cleaners and reboots clear stale
+entries — so in the common case there is **nothing to clean up manually**.
+
+For finer control:
+
+- **Avoid persistence per call**: pass `ephemeral=True` so the venv is deleted as
+  soon as the decorated function or `with` block finishes.
+- **Prune a persistent root you manage**: the venvs are just directories, so
+  `rm -rf "$PYDEPINJECT_VENV_ROOT"` removes everything, or delete individual
+  subdirectories to reclaim space selectively.
+- **Script age-based cleanup**: each venv contains `.pydepinject-*.json` metadata
+  files recording the install timestamp (and the packages installed), which you
+  can use to find and remove environments older than a chosen age.
+
+## Limitations and thread-safety
+
+`pydepinject` works by mutating **process-global interpreter state** for the
+duration of the managed scope (the decorated call or `with` block). When a
+requirement is not already importable, it:
+
+- inserts the venv's `site-packages` at the front of `sys.path`,
+- prepends to the `PYTHONPATH` and `PATH` environment variables,
+- evicts conflicting entries from `sys.modules` so fresh imports resolve to the venv.
+
+The original `sys.path`, environment variables, and `sys.modules` state are
+restored when the scope exits. If every requested package is already satisfied in
+the current environment, **no global state is changed at all** — activation is a
+no-op fast path.
+
+Because this state is global to the interpreter, please keep the following in mind:
+
+- **Not thread-safe and not safe under `asyncio`/concurrent use.** Two managed
+  scopes active at the same time in different threads (or interleaved coroutines)
+  will race on `sys.path`, the environment variables, and `sys.modules`, and can
+  corrupt each other's save/restore. Use `pydepinject` from a single thread of
+  control. If you need dependencies isolated across concurrent workers, give each
+  worker its own **process**.
+- **Already-imported modules are handled best-effort.** If a package was already
+  imported earlier in the process from a different location, swapping it for the
+  venv's copy within the scope cannot be guaranteed — code holding a reference to
+  the previously imported module keeps using it.
+- **It mutates the running interpreter, by design.** This makes it ideal for
+  scripts, notebooks, plugins, and ad-hoc tooling, but it is **not** a substitute
+  for a properly provisioned environment or a lockfile in a production
+  application. For those, prefer real environment/dependency management.
+
+## When NOT to use this
+
+`pydepinject` is built for **scripts, notebooks, plugins, and ad-hoc tooling or
+CI glue** — cases where "make sure X is importable, install it if not" is the
+whole job. It is the wrong tool, and you should reach for a real
+environment plus a lockfile (`uv`, `pip-tools`, Poetry, etc.) instead, when:
+
+- You are building a **deployable application or service** where dependency
+  reproducibility matters.
+- Your code runs under **threads, `asyncio`, or parallel workers** — activation
+  mutates global interpreter state and is not safe to interleave (see
+  [Limitations and thread-safety](#limitations-and-thread-safety); give each
+  worker its own process).
+- You need **pinned, audited, reproducible** dependency sets across machines and
+  CI runs.
+- Packages are **already imported** earlier in the process and must be swapped
+  mid-run — `pydepinject` can only do this best-effort.
+- You run a **long-lived production process** where persistent venvs accumulating
+  under the temp root would be a problem.
+
+For the mechanics behind these caveats, see
+[Limitations and thread-safety](#limitations-and-thread-safety) above.
+
 ## Unit Tests
 
 Unit tests are provided to verify the functionality of the `requires`. The tests use `pytest` and cover various scenarios including decorator usage, context manager usage, ephemeral environments, and more.

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0}/src/pydepinject.egg-info/SOURCES.txt

@@ -9,10 +9,5 @@ src/pydepinject.egg-info/SOURCES.txt
 src/pydepinject.egg-info/dependency_links.txt
 src/pydepinject.egg-info/requires.txt
 src/pydepinject.egg-info/top_level.txt
-src/requirementmanager.egg-info/PKG-INFO
-src/requirementmanager.egg-info/SOURCES.txt
-src/requirementmanager.egg-info/dependency_links.txt
-src/requirementmanager.egg-info/requires.txt
-src/requirementmanager.egg-info/top_level.txt
 tests/conftest.py
 tests/test_pydepinject.py

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0}/src/pydepinject.egg-info/requires.txt

@@ -1,4 +1,4 @@
-packaging>=23.0
+packaging>=24.0
 typing-extensions>=4.4.0
 
 [lint]

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0}/tests/conftest.py

@@ -7,7 +7,7 @@ import pytest
 PROJECT_DIR = pathlib.Path(__file__).parent.parent
 
 
-@pytest.fixture(autouse=True)
+@pytest.fixture(autouse=True)  # noqa: RUF076
 def _check_test_leftovers():
     """Checks if the test left any files in the project directory."""
     items_before = list(PROJECT_DIR.iterdir())

{pydepinject-0.0.3.dev0 → pydepinject-0.0.5.dev0}/tests/test_pydepinject.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import functools
+import os
+import sys
 
 import pytest
 
@@ -376,6 +378,121 @@ def test_invalid_requirements_install_raises_error_decorator(
         assert len(list(venv_root.iterdir())) == 1
 
 
+@pytest.mark.parametrize(
+    "exc",
+    [RuntimeError("install boom"), FileNotFoundError("missing binary")],
+    ids=["runtimeerror", "filenotfounderror"],
+)
+@pytest.mark.parametrize("ephemeral", [True, False], ids=["ephemeral", "non-ephemeral"])
+def test_failed_activation_restores_global_state(
+    venv_root, monkeypatch, ephemeral, exc
+):
+    """A failure during installation must restore sys.path and env vars and
+    propagate the original exception type, regardless of ephemeral.
+
+    The venv is created (so global state has been mutated) before install runs,
+    so a raising install exercises the failure-cleanup path.
+    """
+    with pytest.raises(ImportError):
+        import attrs
+
+    def _boom(*args, **kwargs):  # noqa: ARG001 - stub replacing backend.install
+        raise exc
+
+    from pydepinject import backends
+
+    monkeypatch.setattr(backends.VenvBackendVenv, "install", _boom, raising=True)
+
+    # Concrete sentinel for PYTHONPATH so restoration is unambiguous; PATH is left
+    # at its real value because venv creation shells out and needs it.
+    monkeypatch.setenv("PYTHONPATH", "/pdi-sentinel")
+    pythonpath_before = os.environ["PYTHONPATH"]
+    path_before = os.environ["PATH"]
+    syspath_before = sys.path.copy()
+
+    mgr = requires(
+        "attrs", venv_root=venv_root, ephemeral=ephemeral, venv_backend="venv"
+    )
+
+    with pytest.raises(type(exc)):
+        mgr()
+
+    assert sys.path == syspath_before
+    assert os.environ["PATH"] == path_before
+    assert os.environ["PYTHONPATH"] == pythonpath_before
+
+    # The import should still fail in the current interpreter.
+    with pytest.raises(ImportError):
+        import attrs
+
+
+def test_interrupt_mid_activation_restores_env(venv_root, monkeypatch):
+    """An interrupt landing after env mutation but before activation completes
+    must still restore PATH/PYTHONPATH.
+
+    The env vars are set before ``sys.path.insert``; making ``insert`` raise
+    reproduces an interrupt in that narrow window. Cleanup must not depend on the
+    activation having reached its final ``_activated = True``.
+    """
+    with pytest.raises(ImportError):
+        import attrs
+
+    monkeypatch.setenv("PYTHONPATH", "/pdi-sentinel")
+    pythonpath_before = os.environ["PYTHONPATH"]
+    path_before = os.environ["PATH"]
+
+    # Must be a real list subclass: sys.path has to stay a plain list for
+    # CPython's import machinery, so UserList is not an option here.
+    class _RaisingInsertList(list):  # noqa: FURB189
+        def insert(self, *args, **kwargs):  # noqa: ARG002, PLR6301 - stub
+            raise KeyboardInterrupt("simulated interrupt mid-activation")
+
+    monkeypatch.setattr(sys, "path", _RaisingInsertList(sys.path))
+
+    mgr = requires("attrs", venv_root=venv_root, venv_backend="venv")
+
+    with pytest.raises(KeyboardInterrupt):
+        mgr()
+
+    assert os.environ["PYTHONPATH"] == pythonpath_before
+    assert os.environ["PATH"] == path_before
+
+
+def test_run_command_surfaces_output_on_failure(tmp_path):
+    """A failing command must surface its captured output in the raised error.
+
+    The script is written to a file (rather than ``-c``) so the marker strings
+    appear only in the subprocess output, never in the command line itself.
+    """
+    from pydepinject import backends
+
+    script_path = tmp_path / "boom.py"
+    script_path.write_text(
+        "import sys\n"
+        "sys.stdout.write('hello-from-stdout\\n')\n"
+        "sys.stderr.write('boom-from-stderr\\n')\n"
+        "sys.exit(3)\n"
+    )
+
+    backend = backends.VenvBackendVenv(tmp_path)
+
+    with pytest.raises(RuntimeError) as excinfo:
+        backend._run_command([sys.executable, str(script_path)])
+
+    message = str(excinfo.value)
+    assert "boom-from-stderr" in message
+    assert "hello-from-stdout" in message
+    assert "exit code 3" in message
+
+
+def test_run_command_success_returns_without_error(tmp_path):
+    """A successful command must not raise even though output is now captured."""
+    from pydepinject import backends
+
+    backend = backends.VenvBackendVenv(tmp_path)
+    backend._run_command([sys.executable, "-c", "print('ok')"])
+
+
 def test_invalid_backend_value_raises_valueerror(venv_root):
     # Supplying an unknown backend should raise ValueError during initialization
     with pytest.raises(ValueError, match="Invalid venv_backend: invalid"):

pydepinject-0.0.3.dev0/src/requirementmanager.egg-info/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.1
-Name: requirementmanager
-Version: 0.0.1.dev0
-Summary: A package to dynamically inject requirements into a virtual environment.
-Author-email: Your Name <your.email@example.com>
-Maintainer-email: Your Name <your.email@example.com>
-License: MIT
-Project-URL: homepage, https://github.com/yourusername/requirementmanager
-Project-URL: documentation, https://github.com/yourusername/requirementmanager
-Project-URL: repository, https://github.com/yourusername/requirementmanager
-Keywords: virtualenv,requirements,dependency management
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Typing :: Typed
-Description-Content-Type: text/x-rst
-Provides-Extra: dev
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: flake8; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: pyright; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Requires-Dist: wheel; extra == "dev"
-Requires-Dist: setuptools; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"

pydepinject-0.0.3.dev0/src/requirementmanager.egg-info/SOURCES.txt

@@ -1,7 +0,0 @@
-pyproject.toml
-src/pydepinject/__init__.py
-src/requirementmanager.egg-info/PKG-INFO
-src/requirementmanager.egg-info/SOURCES.txt
-src/requirementmanager.egg-info/dependency_links.txt
-src/requirementmanager.egg-info/requires.txt
-src/requirementmanager.egg-info/top_level.txt

pydepinject-0.0.3.dev0/src/requirementmanager.egg-info/dependency_links.txt

@@ -1 +0,0 @@
-

pydepinject-0.0.3.dev0/src/requirementmanager.egg-info/requires.txt

@@ -1,11 +0,0 @@
-
-[dev]
-ruff
-pytest
-flake8
-black
-pyright
-twine
-wheel
-setuptools
-pre-commit

pydepinject-0.0.3.dev0/src/requirementmanager.egg-info/top_level.txt

@@ -1 +0,0 @@
-pydepinject