Make --system-site-packages venv opt-in; add --py-system-site-packages flag

Virtual environments are now isolated by default. The previous behavior
of always passing --system-site-packages to venv/uv is removed.

Changes:
- setup_venv() in utils.py gains system_site_packages=False parameter
- project_ops.py threads args.py_system_site_packages through to setup_venv()
- __main__.py adds --py-system-site-packages to both update and clone commands
- test/unit/test_venv.py: new tests for isolated (default) and opt-in venv creation
- docs: update reference.rst, python_packages.rst, getting_started.rst

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mballance

docs/source/getting_started.rst

@@ -69,6 +69,11 @@ Clone Command Options
     Choose whether ``ivpm update`` should use "uv" or "pip"
     to manage the project-local Python virtual environment.
 
+``--py-system-site-packages``
+    Opt in to inheriting system site-packages inside the virtual environment.
+    By default the environment is **isolated**; use this flag only when you
+    need access to system-installed packages (e.g. hardware-specific bindings).
+
 **Examples:**
 
 .. code-block:: bash

docs/source/python_packages.rst

@@ -36,6 +36,18 @@ Creates::
         └── ...
 
 The virtual environment is created using Python's built-in ``venv`` module.
+By default the environment is **isolated**: packages installed in the base
+Python or system Python are **not** visible inside it.  This ensures
+reproducible, self-contained workspaces.
+
+To opt in to inheriting system site-packages (e.g. for hardware-specific
+Python extensions that cannot be installed via pip), pass
+``--py-system-site-packages`` to ``ivpm update`` or ``ivpm clone``:
+
+.. code-block:: bash
+
+    $ ivpm update --py-system-site-packages
+    $ ivpm clone https://github.com/org/project --py-system-site-packages
 
 Package Manager Selection
 --------------------------

docs/source/reference.rst

@@ -239,6 +239,13 @@ Create a new workspace from a Git repository.
 ``--py-pip``
     Use 'pip' for Python package management
 
+``--py-system-site-packages``
+    Inherit the base Python's system site-packages inside the created virtual
+    environment.  By default the environment is **isolated** (system packages
+    are not visible).  Pass this flag only when you intentionally need access
+    to system-installed packages (e.g. hardware-specific Python bindings that
+    cannot be installed via pip).
+
 **Examples:**
 
 .. code-block:: bash
@@ -523,6 +530,12 @@ Fetch dependencies and initialize environment.
 ``--py-pip``
     Use 'pip' for package management
 
+``--py-system-site-packages``
+    Inherit the base Python's system site-packages inside the created virtual
+    environment.  By default the environment is **isolated** (system packages
+    are not visible).  Pass this flag only when you intentionally need access
+    to system-installed packages.
+
 ``--lock-file <path>``
     Reproduce workspace from a ``package-lock.json`` file.  ``ivpm.yaml``
     is not read for packages; the lock file supplies the complete package

src/ivpm/__main__.py

@@ -142,6 +142,9 @@ def get_parser(parser_ext : List = None, options_ext : List = None):
         help="Use 'uv' to manage virtual environment")
     clone_cmd.add_argument("--py-pip", dest="py_pip", action="store_true",
         help="Use 'pip' to manage virtual environment")
+    clone_cmd.add_argument("--py-system-site-packages", dest="py_system_site_packages",
+        action="store_true", default=False,
+        help="Inherit system site-packages in the virtual environment (default: isolated)")
     clone_cmd.set_defaults(func=CmdClone())
     subcommands["clone"] = clone_cmd
 
@@ -170,8 +173,11 @@ def get_parser(parser_ext : List = None, options_ext : List = None):
         help="Use 'uv' to manage virtual environment",
         action="store_true")
     update_cmd.add_argument("--py-pip",
-        help="Use 'uv' to manage virtual environment",
+        help="Use 'pip' to manage virtual environment",
         action="store_true")
+    update_cmd.add_argument("--py-system-site-packages", dest="py_system_site_packages",
+        action="store_true", default=False,
+        help="Inherit system site-packages in the virtual environment (default: isolated)")
     update_cmd.add_argument("--lock-file", dest="lock_file", default=None,
         help="Reproduce workspace from a package-lock.json file (ignores ivpm.yaml)")
     update_cmd.add_argument("--refresh-all", dest="refresh_all",

src/ivpm/project_ops.py

@@ -78,6 +78,10 @@ def update(self,
                         uv_pip = "uv"
                     elif hasattr(args, "py_pip") and args.py_pip:
                         uv_pip = "pip"
+                    system_site_packages = (
+                        hasattr(args, "py_system_site_packages") and
+                        bool(args.py_system_site_packages)
+                    )
 
                     # Signal venv creation start
                     venv_start_time = time.time()
@@ -89,7 +93,8 @@ def update(self,
                         ivpm_python = setup_venv(
                             os.path.join(deps_dir, "python"), 
                             uv_pip=uv_pip,
-                            suppress_output=suppress_output
+                            suppress_output=suppress_output,
+                            system_site_packages=system_site_packages
                         )
                         # Signal venv creation complete
                         event_dispatcher.dispatch(UpdateEvent(

src/ivpm/utils.py

@@ -76,7 +76,7 @@ def get_venv_python(python_dir):
 
     return ivpm_python
 
-def setup_venv(python_dir, uv_pip="auto", suppress_output=False):
+def setup_venv(python_dir, uv_pip="auto", suppress_output=False, system_site_packages=False):
     note("creating Python virtual environment")
 
     if uv_pip == "auto":
@@ -106,9 +106,10 @@ def setup_venv(python_dir, uv_pip="auto", suppress_output=False):
             "venv",
             "--python",
             python,
-            "--system-site-packages",
-            python_dir
         ]
+        if system_site_packages:
+            cmd.append("--system-site-packages")
+        cmd.append(python_dir)
 
         result = subprocess.run(
             cmd,
@@ -145,14 +146,18 @@ def setup_venv(python_dir, uv_pip="auto", suppress_output=False):
         ivpm_python = get_venv_python(python_dir)
     else:
         note("Using 'pip' to manage virtual environment")
+        venv_cmd = [python, "-m", "venv"]
+        if system_site_packages:
+            venv_cmd.append("--system-site-packages")
+        venv_cmd.append(python_dir)
         if suppress_output:
             result = subprocess.run(
-                [python, "-m", "venv", "--system-site-packages", python_dir],
+                venv_cmd,
                 stdout=stdout_arg,
                 stderr=stderr_arg
             )
         else:
-            os.system(python + " -m venv --system-site-packages " + python_dir)
+            os.system(" ".join(venv_cmd))
         note("upgrading pip")
         ivpm_python = get_venv_python(python_dir)
 

test/unit/test_venv.py

@@ -0,0 +1,85 @@
+"""
+Tests for virtual environment creation behavior.
+
+Verifies that:
+- Default venv creation produces an isolated environment (no system-site-packages).
+- Opt-in via py_system_site_packages=True produces a venv that includes system site-packages.
+"""
+import os
+import configparser
+from .test_base import TestBase
+
+
+_SIMPLE_IVPM_YAML = """
+package:
+    name: venv_test
+    dep-sets:
+        - name: default-dev
+          deps:
+            - name: leaf_proj1
+              url: file://${DATA_DIR}/leaf_proj1
+              src: dir
+"""
+
+
+def _read_pyvenv_cfg(python_dir):
+    """Parse pyvenv.cfg from a virtualenv directory."""
+    cfg_path = os.path.join(python_dir, "pyvenv.cfg")
+    cfg = configparser.ConfigParser()
+    # pyvenv.cfg has no section header; add a fake one
+    with open(cfg_path) as fp:
+        content = "[root]\n" + fp.read()
+    cfg.read_string(content)
+    return dict(cfg["root"])
+
+
+class TestVenv(TestBase):
+
+    def _make_project(self):
+        self.mkFile("ivpm.yaml", _SIMPLE_IVPM_YAML)
+
+    def test_venv_isolated_by_default(self):
+        """Default update must create an isolated venv (no system site-packages)."""
+        self._make_project()
+
+        class Args:
+            py_uv = False
+            py_pip = True          # force pip so we don't need uv
+            py_system_site_packages = False
+            anonymous_git = None
+            log_level = "NONE"
+
+        self.ivpm_update(skip_venv=False, args=Args())
+
+        python_dir = os.path.join(self.testdir, "packages", "python")
+        self.assertTrue(os.path.isdir(python_dir),
+                        "packages/python directory should exist after update")
+
+        cfg = _read_pyvenv_cfg(python_dir)
+        value = cfg.get("include-system-site-packages", "false").strip().lower()
+        self.assertEqual(value, "false",
+                         "Default venv must NOT include system site-packages; "
+                         "got include-system-site-packages = %r" % value)
+
+    def test_venv_system_site_packages_opt_in(self):
+        """Update with py_system_site_packages=True must create a venv that includes system site-packages."""
+        self._make_project()
+
+        class Args:
+            py_uv = False
+            py_pip = True          # force pip so we don't need uv
+            py_system_site_packages = True
+            anonymous_git = None
+            log_level = "NONE"
+
+        self.ivpm_update(skip_venv=False, args=Args())
+
+        python_dir = os.path.join(self.testdir, "packages", "python")
+        self.assertTrue(os.path.isdir(python_dir),
+                        "packages/python directory should exist after update")
+
+        cfg = _read_pyvenv_cfg(python_dir)
+        value = cfg.get("include-system-site-packages", "false").strip().lower()
+        self.assertEqual(value, "true",
+                         "Opt-in venv MUST include system site-packages; "
+                         "got include-system-site-packages = %r" % value)