Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e218e50

Browse files
brettcannonAA-Turnerhugovk
authored
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]>
1 parent 6b179ad commit e218e50

File tree

7 files changed

+233
-95
lines changed

7 files changed

+233
-95
lines changed

‎Doc/library/venv.rst

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,8 @@ creation according to their needs, the :class:`EnvBuilder` class.
143143

144144
.. class:: EnvBuilder(system_site_packages=False, clear=False, \
145145
symlinks=False, upgrade=False, with_pip=False, \
146-
prompt=None, upgrade_deps=False)
146+
prompt=None, upgrade_deps=False, \
147+
*, scm_ignore_files=frozenset())
147148
148149
The :class:`EnvBuilder` class accepts the following keyword arguments on
149150
instantiation:
@@ -172,6 +173,12 @@ creation according to their needs, the :class:`EnvBuilder` class.
172173

173174
* ``upgrade_deps`` -- Update the base venv modules to the latest on PyPI
174175

176+
* ``scm_ignore_files`` -- Create ignore files based for the specified source
177+
control managers (SCM) in the iterable. Support is defined by having a
178+
method named ``create_{scm}_ignore_file``. The only value supported by
179+
default is ``"git"`` via :meth:`create_git_ignore_file`.
180+
181+
175182
.. versionchanged:: 3.4
176183
Added the ``with_pip`` parameter
177184

@@ -181,6 +188,9 @@ creation according to their needs, the :class:`EnvBuilder` class.
181188
.. versionadded:: 3.9
182189
Added the ``upgrade_deps`` parameter
183190

191+
.. versionadded:: 3.13
192+
Added the ``scm_ignore_files`` parameter
193+
184194
Creators of third-party virtual environment tools will be free to use the
185195
provided :class:`EnvBuilder` class as a base class.
186196

@@ -339,11 +349,18 @@ creation according to their needs, the :class:`EnvBuilder` class.
339349
The directories are allowed to exist (for when an existing environment
340350
is being upgraded).
341351

352+
.. method:: create_git_ignore_file(context)
353+
354+
Creates a ``.gitignore`` file within the virtual environment that causes
355+
the entire directory to be ignored by the ``git`` source control manager.
356+
357+
.. versionadded:: 3.13
358+
342359
There is also a module-level convenience function:
343360

344361
.. function:: create(env_dir, system_site_packages=False, clear=False, \
345362
symlinks=False, with_pip=False, prompt=None, \
346-
upgrade_deps=False)
363+
upgrade_deps=False, *, scm_ignore_files=frozenset())
347364
348365
Create an :class:`EnvBuilder` with the given keyword arguments, and call its
349366
:meth:`~EnvBuilder.create` method with the *env_dir* argument.
@@ -359,6 +376,9 @@ There is also a module-level convenience function:
359376
.. versionchanged:: 3.9
360377
Added the ``upgrade_deps`` parameter
361378

379+
.. versionchanged:: 3.13
380+
Added the ``scm_ignore_files`` parameter
381+
362382
An example of extending ``EnvBuilder``
363383
--------------------------------------
364384

‎Doc/using/venv-create.inc

Lines changed: 42 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -35,37 +35,48 @@ your :ref:`Python installation <using-on-windows>`::
3535
3636
The command, if run with ``-h``, will show the available options::
3737
38-
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
39-
[--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
40-
ENV_DIR [ENV_DIR ...]
41-
42-
Creates virtual Python environments in one or more target directories.
43-
44-
positional arguments:
45-
ENV_DIR A directory to create the environment in.
46-
47-
optional arguments:
48-
-h, --help show this help message and exit
49-
--system-site-packages
50-
Give the virtual environment access to the system
51-
site-packages dir.
52-
--symlinks Try to use symlinks rather than copies, when symlinks
53-
are not the default for the platform.
54-
--copies Try to use copies rather than symlinks, even when
55-
symlinks are the default for the platform.
56-
--clear Delete the contents of the environment directory if it
57-
already exists, before environment creation.
58-
--upgrade Upgrade the environment directory to use this version
59-
of Python, assuming Python has been upgraded in-place.
60-
--without-pip Skips installing or upgrading pip in the virtual
61-
environment (pip is bootstrapped by default)
62-
--prompt PROMPT Provides an alternative prompt prefix for this
63-
environment.
64-
--upgrade-deps Upgrade core dependencies (pip) to the
65-
latest version in PyPI
66-
67-
Once an environment has been created, you may wish to activate it, e.g. by
68-
sourcing an activate script in its bin directory.
38+
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
39+
[--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
40+
[--without-scm-ignore-file]
41+
ENV_DIR [ENV_DIR ...]
42+
43+
Creates virtual Python environments in one or more target directories.
44+
45+
positional arguments:
46+
ENV_DIR A directory to create the environment in.
47+
48+
options:
49+
-h, --help show this help message and exit
50+
--system-site-packages
51+
Give the virtual environment access to the system
52+
site-packages dir.
53+
--symlinks Try to use symlinks rather than copies, when
54+
symlinks are not the default for the platform.
55+
--copies Try to use copies rather than symlinks, even when
56+
symlinks are the default for the platform.
57+
--clear Delete the contents of the environment directory if
58+
it already exists, before environment creation.
59+
--upgrade Upgrade the environment directory to use this
60+
version of Python, assuming Python has been upgraded
61+
in-place.
62+
--without-pip Skips installing or upgrading pip in the virtual
63+
environment (pip is bootstrapped by default)
64+
--prompt PROMPT Provides an alternative prompt prefix for this
65+
environment.
66+
--upgrade-deps Upgrade core dependencies (pip) to the latest
67+
version in PyPI
68+
--without-scm-ignore-file
69+
Skips adding the default SCM ignore file to the
70+
environment directory (the default is a .gitignore
71+
file).
72+
73+
Once an environment has been created, you may wish to activate it, e.g. by
74+
sourcing an activate script in its bin directory.
75+
76+
.. versionchanged:: 3.13
77+
78+
``--without-scm-ignore-file`` was added along with creating an ignore file
79+
for ``git`` by default.
6980
7081
.. versionchanged:: 3.12
7182

‎Doc/whatsnew/3.13.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,16 @@ typing
220220
check whether a class is a :class:`typing.Protocol`. (Contributed by Jelle Zijlstra in
221221
:gh:`104873`.)
222222

223+
venv
224+
----
225+
226+
* Add support for adding source control management (SCM) ignore files to a
227+
virtual environment's directory. By default, Git is supported. This is
228+
implemented as opt-in via the API which can be extended to support other SCMs
229+
(:class:`venv.EnvBuilder` and :func:`venv.create`), and opt-out via the CLI
230+
(using ``--without-scm-ignore-files``). (Contributed by Brett Cannon in
231+
:gh:`108125`.)
232+
223233
Optimizations
224234
=============
225235

0 commit comments

Comments
 (0)