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

Doc/library/venv.rst

@@ -143,7 +143,7 @@ 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_file=None)
 
  The :class:`EnvBuilder` class accepts the following keyword arguments on
  instantiation:
@@ -172,6 +172,12 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
  * ``upgrade_deps`` -- Update the base venv modules to the latest on PyPI
 
+ * ``scm_ignore_file`` -- Create an ignore file for the specified source
+ control manager (SCM). Support is defined by having a method named
+ ``create_{scm}_ignore_file``. The only value currently supported is
+ ``"git"`` via :meth:`create_git_ignore_file`.
+
+
  .. versionchanged:: 3.4
  Added the ``with_pip`` parameter
 
@@ -181,6 +187,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_file`` parameter
+
  Creators of third-party virtual environment tools will be free to use the
  provided :class:`EnvBuilder` class as a base class.
 
@@ -339,11 +348,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_file=None)
 
  Create an :class:`EnvBuilder` with the given keyword arguments, and call its
  :meth:`~EnvBuilder.create` method with the *env_dir* argument.
@@ -359,6 +375,9 @@ There is also a module-level convenience function:
  .. versionchanged:: 3.9
  Added the ``upgrade_deps`` parameter
 
+ .. versionchanged:: 3.13
+ Added the ``scm_ignore_file`` 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
 

Lib/test/test_venv.py

@@ -138,7 +138,8 @@ def _check_output_of_default_create(self):
  self.assertIn('executable = %s' %
  os.path.realpath(sys.executable), data)
  copies = '' if os.name=='nt' else ' --copies'
- cmd = f'command = {sys.executable} -m venv{copies} --without-pip {self.env_dir}'
+ cmd = (f'command = {sys.executable} -m venv{copies} --without-pip '
+ f'--without-scm-ignore-file {self.env_dir}')
  self.assertIn(cmd, data)
  fn = self.get_env_file(self.bindir, self.exe)
  if not os.path.exists(fn): # diagnostics for Windows buildbot failures
@@ -148,35 +149,37 @@ def _check_output_of_default_create(self):
  self.assertTrue(os.path.exists(fn), 'File %r should exist.' % fn)
 
  def test_config_file_command_key(self):
- attrs = [
- (None, None),
- ('symlinks', '--copies'),
- ('with_pip', '--without-pip'),
- ('system_site_packages', '--system-site-packages'),
- ('clear', '--clear'),
- ('upgrade', '--upgrade'),
- ('upgrade_deps', '--upgrade-deps'),
- ('prompt', '--prompt'),
+ options = [
+ (None, None, None), # Default case.
+ ('--copies', 'symlinks', False),
+ ('--without-pip', 'with_pip', False),
+ ('--system-site-packages', 'system_site_packages', True),
+ ('--clear', 'clear', True),
+ ('--upgrade', 'upgrade', True),
+ ('--upgrade-deps', 'upgrade_deps', True),
+ ('--prompt', 'prompt', True),
+ ('--without-scm-ignore-file', 'scm_ignore_file', None),
  ]
- for attr, opt in attrs:
- rmtree(self.env_dir)
- if not attr:
- b = venv.EnvBuilder()
- else:
- b = venv.EnvBuilder(
- **{attr: False if attr in ('with_pip', 'symlinks') else True})
- b.upgrade_dependencies = Mock() # avoid pip command to upgrade deps
- b._setup_pip = Mock() # avoid pip setup
- self.run_with_capture(b.create, self.env_dir)
- data = self.get_text_file_contents('pyvenv.cfg')
- if not attr:
- for opt in ('--system-site-packages', '--clear', '--upgrade',
- '--upgrade-deps', '--prompt'):
- self.assertNotRegex(data, rf'command = .* {opt}')
- elif os.name=='nt' and attr=='symlinks':
- pass
- else:
- self.assertRegex(data, rf'command = .* {opt}')
+ for opt, attr, value in options:
+ with self.subTest(opt=opt, attr=attr, value=value):
+ rmtree(self.env_dir)
+ if not attr:
+ kwargs = {}
+ else:
+ kwargs = {attr: value}
+ b = venv.EnvBuilder(**kwargs)
+ b.upgrade_dependencies = Mock() # avoid pip command to upgrade deps
+ b._setup_pip = Mock() # avoid pip setup
+ self.run_with_capture(b.create, self.env_dir)
+ data = self.get_text_file_contents('pyvenv.cfg')
+ if not attr or opt.endswith('git'):
+ for opt in ('--system-site-packages', '--clear', '--upgrade',
+ '--upgrade-deps', '--prompt'):
+ self.assertNotRegex(data, rf'command = .* {opt}')
+ elif os.name=='nt' and attr=='symlinks':
+ pass
+ else:
+ self.assertRegex(data, rf'command = .* {opt}')
 
  def test_prompt(self):
  env_name = os.path.split(self.env_dir)[1]
@@ -585,6 +588,7 @@ def test_zippath_from_non_installed_posix(self):
  "-m",
  "venv",
  "--without-pip",
+ "--without-scm-ignore-file",
  self.env_dir]
  # Our fake non-installed python is not fully functional because
  # it cannot find the extensions. Set PYTHONPATH so it can run the
@@ -616,6 +620,7 @@ def test_zippath_from_non_installed_posix(self):
  out, err = check_output(cmd)
  self.assertTrue(zip_landmark.encode() in out)
 
+ @requireVenvCreate
  def test_activate_shell_script_has_no_dos_newlines(self):
  """
  Test that the `activate` shell script contains no CR LF.
@@ -632,6 +637,17 @@ def test_activate_shell_script_has_no_dos_newlines(self):
  error_message = f"CR LF found in line {i}"
  self.assertFalse(line.endswith(b'\r\n'), error_message)
 
+ @requireVenvCreate
+ def test_create_git_ignore_file(self):
+ """
+ Test that a .gitignore file is created.
+ The file should contain a `*\n` line.
+ """
+ self.run_with_capture(venv.create, self.env_dir, scm_ignore_file='git')
+ file_lines = self.get_text_file_contents('.gitignore').splitlines()
+ self.assertIn('*', file_lines)
+
+
 @requireVenvCreate
 class EnsurePipTest(BaseTest):
  """Test venv module installation of pip."""

Lib/venv/__init__.py

@@ -41,11 +41,12 @@ class EnvBuilder:
  environment
  :param prompt: Alternative terminal prefix for the environment.
  :param upgrade_deps: Update the base venv modules to the latest on PyPI
+ :param scm_ignore_file: Create an ignore file for the specified SCM.
  """
 
  def __init__(self, system_site_packages=False, clear=False,
  symlinks=False, upgrade=False, with_pip=False, prompt=None,
- upgrade_deps=False):
+ upgrade_deps=False, *, scm_ignore_file=None):
  self.system_site_packages = system_site_packages
  self.clear = clear
  self.symlinks = symlinks
@@ -56,6 +57,9 @@ def __init__(self, system_site_packages=False, clear=False,
  prompt = os.path.basename(os.getcwd())
  self.prompt = prompt
  self.upgrade_deps = upgrade_deps
+ if scm_ignore_file:
+ scm_ignore_file = scm_ignore_file.lower()
+ self.scm_ignore_file = scm_ignore_file
 
  def create(self, env_dir):
  """
@@ -66,6 +70,8 @@ def create(self, env_dir):
  """
  env_dir = os.path.abspath(env_dir)
  context = self.ensure_directories(env_dir)
+ if self.scm_ignore_file:
+ getattr(self, f"create_{self.scm_ignore_file}_ignore_file")(context)
  # See issue 24875. We need system_site_packages to be False
  # until after pip is installed.
  true_system_site_packages = self.system_site_packages
@@ -210,6 +216,8 @@ def create_configuration(self, context):
  args.append('--upgrade-deps')
  if self.orig_prompt is not None:
  args.append(f'--prompt="{self.orig_prompt}"')
+ if not self.scm_ignore_file:
+ args.append('--without-scm-ignore-file')
 
  args.append(context.env_dir)
  args = ' '.join(args)
@@ -278,6 +286,19 @@ def symlink_or_copy(self, src, dst, relative_symlinks_ok=False):
 
  shutil.copyfile(src, dst)
 
+ def create_git_ignore_file(self, context):
+ """
+ Create a .gitignore file in the environment directory.
+
+ The contents of the file cause the entire environment directory to be
+ ignored by git.
+ """
+ gitignore_path = os.path.join(context.env_dir, '.gitignore')
+ with open(gitignore_path, 'w', encoding='utf-8') as file:
+ file.write('# Created by venv; '
+ 'see https://docs.python.org/3/library/venv.html\n')
+ file.write('*\n')
+
  def setup_python(self, context):
  """
  Set up a Python executable in the environment.
@@ -461,11 +482,13 @@ def upgrade_dependencies(self, context):
 
 
 def create(env_dir, system_site_packages=False, clear=False,
- symlinks=False, with_pip=False, prompt=None, upgrade_deps=False):
+ symlinks=False, with_pip=False, prompt=None, upgrade_deps=False,
+ *, scm_ignore_file=None):
  """Create a virtual environment in a directory."""
  builder = EnvBuilder(system_site_packages=system_site_packages,
  clear=clear, symlinks=symlinks, with_pip=with_pip,
- prompt=prompt, upgrade_deps=upgrade_deps)
+ prompt=prompt, upgrade_deps=upgrade_deps,
+ scm_ignore_file=scm_ignore_file)
  builder.create(env_dir)
 
 
@@ -525,6 +548,11 @@ def main(args=None):
  dest='upgrade_deps',
  help=f'Upgrade core dependencies ({", ".join(CORE_VENV_DEPS)}) '
  'to the latest version in PyPI')
+ parser.add_argument('--without-scm-ignore-file', dest='scm_ignore_file',
+ action='store_const', const=None, default='git',
+ help='Skips adding the default SCM ignore file to the '
+ 'environment directory (the default is a '
+ '.gitignore file).')
  options = parser.parse_args(args)
  if options.upgrade and options.clear:
  raise ValueError('you cannot supply --upgrade and --clear together.')
@@ -534,7 +562,8 @@ def main(args=None):
  upgrade=options.upgrade,
  with_pip=options.with_pip,
  prompt=options.prompt,
- upgrade_deps=options.upgrade_deps)
+ upgrade_deps=options.upgrade_deps,
+ scm_ignore_file=options.scm_ignore_file)
  for d in options.dirs:
  builder.create(d)
 

Lib/venv/__main__.py

@@ -6,5 +6,5 @@
  main()
  rc = 0
 except Exception as e:
- print('Error: %s' % e, file=sys.stderr)
+ print('Error:', e, file=sys.stderr)
 sys.exit(rc)

Misc/NEWS.d/next/Library/2023-08-18-22-58-07.gh-issue-83417.61J4yM.rst

@@ -0,0 +1,3 @@
+Add the ability for venv to create a ``.gitignore`` file which causes the
+created environment to be ignored by git. It is on by default when venv is
+called via its CLI.