GH-83417: Allow venv to add a .gitignore file to environments via a new scm_ignore_file parameter (GH-108125)

This feature is off by default via code but on by default via the CLI. The `.gitignore` file contains `*` which causes the entire directory to be ignored.

Co-authored-by: Adam Turner <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>

Author: 3 people

Doc/library/venv.rst

@@ -143,7 +143,8 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
 .. class:: EnvBuilder(system_site_packages=False, clear=False, \
                       symlinks=False, upgrade=False, with_pip=False, \
-                      prompt=None, upgrade_deps=False)
+                      prompt=None, upgrade_deps=False, \
+                      *, scm_ignore_files=frozenset())
 
     The :class:`EnvBuilder` class accepts the following keyword arguments on
     instantiation:
@@ -172,6 +173,12 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
     * ``upgrade_deps`` -- Update the base venv modules to the latest on PyPI
 
+    * ``scm_ignore_files`` -- Create ignore files based for the specified source
+      control managers (SCM) in the iterable. Support is defined by having a
+      method named ``create_{scm}_ignore_file``. The only value supported by
+      default is ``"git"`` via :meth:`create_git_ignore_file`.
+
+
     .. versionchanged:: 3.4
        Added the ``with_pip`` parameter
 
@@ -181,6 +188,9 @@ creation according to their needs, the :class:`EnvBuilder` class.
     .. versionadded:: 3.9
        Added the ``upgrade_deps`` parameter
 
+    .. versionadded:: 3.13
+       Added the ``scm_ignore_files`` parameter
+
     Creators of third-party virtual environment tools will be free to use the
     provided :class:`EnvBuilder` class as a base class.
 
@@ -339,11 +349,18 @@ creation according to their needs, the :class:`EnvBuilder` class.
         The directories are allowed to exist (for when an existing environment
         is being upgraded).
 
+    .. method:: create_git_ignore_file(context)
+
+       Creates a ``.gitignore`` file within the virtual environment that causes
+       the entire directory to be ignored by the ``git`` source control manager.
+
+       .. versionadded:: 3.13
+
 There is also a module-level convenience function:
 
 .. function:: create(env_dir, system_site_packages=False, clear=False, \
                      symlinks=False, with_pip=False, prompt=None, \
-                     upgrade_deps=False)
+                     upgrade_deps=False, *, scm_ignore_files=frozenset())
 
     Create an :class:`EnvBuilder` with the given keyword arguments, and call its
     :meth:`~EnvBuilder.create` method with the *env_dir* argument.
@@ -359,6 +376,9 @@ There is also a module-level convenience function:
     .. versionchanged:: 3.9
        Added the ``upgrade_deps`` parameter
 
+    .. versionchanged:: 3.13
+       Added the ``scm_ignore_files`` parameter
+
 An example of extending ``EnvBuilder``
 --------------------------------------
 

Doc/using/venv-create.inc

@@ -35,37 +35,48 @@ your :ref:`Python installation <using-on-windows>`::
 
 The command, if run with ``-h``, will show the available options::
 
-    usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
-                [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
-                ENV_DIR [ENV_DIR ...]
-
-    Creates virtual Python environments in one or more target directories.
-
-    positional arguments:
-      ENV_DIR               A directory to create the environment in.
-
-    optional arguments:
-      -h, --help            show this help message and exit
-      --system-site-packages
-                            Give the virtual environment access to the system
-                            site-packages dir.
-      --symlinks            Try to use symlinks rather than copies, when symlinks
-                            are not the default for the platform.
-      --copies              Try to use copies rather than symlinks, even when
-                            symlinks are the default for the platform.
-      --clear               Delete the contents of the environment directory if it
-                            already exists, before environment creation.
-      --upgrade             Upgrade the environment directory to use this version
-                            of Python, assuming Python has been upgraded in-place.
-      --without-pip         Skips installing or upgrading pip in the virtual
-                            environment (pip is bootstrapped by default)
-      --prompt PROMPT       Provides an alternative prompt prefix for this
-                            environment.
-      --upgrade-deps        Upgrade core dependencies (pip) to the
-                            latest version in PyPI
-
-    Once an environment has been created, you may wish to activate it, e.g. by
-    sourcing an activate script in its bin directory.
+   usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
+               [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
+               [--without-scm-ignore-file]
+               ENV_DIR [ENV_DIR ...]
+
+   Creates virtual Python environments in one or more target directories.
+
+   positional arguments:
+   ENV_DIR               A directory to create the environment in.
+
+   options:
+   -h, --help            show this help message and exit
+   --system-site-packages
+                           Give the virtual environment access to the system
+                           site-packages dir.
+   --symlinks            Try to use symlinks rather than copies, when
+                           symlinks are not the default for the platform.
+   --copies              Try to use copies rather than symlinks, even when
+                           symlinks are the default for the platform.
+   --clear               Delete the contents of the environment directory if
+                           it already exists, before environment creation.
+   --upgrade             Upgrade the environment directory to use this
+                           version of Python, assuming Python has been upgraded
+                           in-place.
+   --without-pip         Skips installing or upgrading pip in the virtual
+                           environment (pip is bootstrapped by default)
+   --prompt PROMPT       Provides an alternative prompt prefix for this
+                           environment.
+   --upgrade-deps        Upgrade core dependencies (pip) to the latest
+                           version in PyPI
+   --without-scm-ignore-file
+                           Skips adding the default SCM ignore file to the
+                           environment directory (the default is a .gitignore
+                           file).
+
+   Once an environment has been created, you may wish to activate it, e.g. by
+   sourcing an activate script in its bin directory.
+
+.. versionchanged:: 3.13
+
+   ``--without-scm-ignore-file`` was added along with creating an ignore file
+   for ``git`` by default.
 
 .. versionchanged:: 3.12
 

Doc/whatsnew/3.13.rst

@@ -220,6 +220,16 @@ typing
   check whether a class is a :class:`typing.Protocol`. (Contributed by Jelle Zijlstra in
   :gh:`104873`.)
 
+venv
+----
+
+* Add support for adding source control management (SCM) ignore files to a
+  virtual environment's directory. By default, Git is supported. This is
+  implemented as opt-in via the API which can be extended to support other SCMs
+  (:class:`venv.EnvBuilder` and :func:`venv.create`), and opt-out via the CLI
+  (using ``--without-scm-ignore-files``). (Contributed by Brett Cannon in
+  :gh:`108125`.)
+
 Optimizations
 =============