Sep 15, 2023 · Aug 18, 2023 · Aug 18, 2023 · Aug 21, 2023 · Aug 21, 2023 · Sep 4, 2023
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst

 .. 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:

    * ``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

    .. 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.

        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.
    .. versionchanged:: 3.9
       Added the ``upgrade_deps`` parameter

    .. versionchanged:: 3.13
       Added the ``scm_ignore_files`` parameter

 An example of extending ``EnvBuilder``
 --------------------------------------

diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc

 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

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
  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
 =============
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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:
Expand DownExpand Up		@@ -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

Expand All		@@ -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.

Expand DownExpand Up		@@ -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.
Expand All		@@ -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``
		--------------------------------------

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
		=============

Expand Down