Debian Codegraph @

Doc/library/venv.rst

raw
1 :mod:`!venv` --- Creation of virtual environments
2 =================================================
3
4 .. module:: venv
5 :synopsis: Creation of virtual environments.
6
7 .. moduleauthor:: Vinay Sajip <[email protected]>
8 .. sectionauthor:: Vinay Sajip <[email protected]>
9
10 .. versionadded:: 3.3
11
12 **Source code:** :source:`Lib/venv/`
13
14 .. index:: pair: Environments; virtual
15
16 --------------
17
18 .. _venv-def:
19 .. _venv-intro:
20
21 The :mod:`!venv` module supports creating lightweight "virtual environments",
22 each with their own independent set of Python packages installed in
23 their :mod:`site` directories.
24 A virtual environment is created on top of an existing
25 Python installation, known as the virtual environment's "base" Python, and by
26 default is isolated from the packages in the base environment,
27 so that only those explicitly installed in the virtual environment are
28 available. See :ref:`sys-path-init-virtual-environments` and :mod:`site`'s
29 :ref:`virtual environments documentation <site-virtual-environments-configuration>`
30 for more information.
31
32 When used from within a virtual environment, common installation tools such as
33 :pypi:`pip` will install Python packages into a virtual environment
34 without needing to be told to do so explicitly.
35
36 A virtual environment is (amongst other things):
37
38 * Used to contain a specific Python interpreter and software libraries and
39 binaries which are needed to support a project (library or application). These
40 are by default isolated from software in other virtual environments and Python
41 interpreters and libraries installed in the operating system.
42
43 * Contained in a directory, conventionally named ``.venv`` or ``venv`` in
44 the project directory, or under a container directory for lots of virtual
45 environments, such as ``~/.virtualenvs``.
46
47 * Not checked into source control systems such as Git.
48
49 * Considered as disposable -- it should be simple to delete and recreate it from
50 scratch. You don't place any project code in the environment.
51
52 * Not considered as movable or copyable -- you just recreate the same
53 environment in the target location.
54
55 See :pep:`405` for more background on Python virtual environments.
56
57 .. seealso::
58
59 `Python Packaging User Guide: Creating and using virtual environments
60 <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments>`__
61
62 .. include:: ../includes/wasm-mobile-notavail.rst
63
64 Creating virtual environments
65 -----------------------------
66
67 :ref:`Virtual environments <venv-def>` are created by executing the ``venv``
68 module:
69
70 .. code-block:: shell
71
72 python -m venv /path/to/new/virtual/environment
73
74 This creates the target directory (including parent directories as needed)
75 and places a :file:`pyvenv.cfg` file in it with a ``home`` key
76 pointing to the Python installation from which the command was run.
77 It also creates a :file:`bin` (or :file:`Scripts` on Windows) subdirectory
78 containing a copy or symlink of the Python executable
79 (as appropriate for the platform or arguments used at environment creation time).
80 It also creates a :file:`lib/pythonX.Y/site-packages` subdirectory
81 (on Windows, this is :file:`Lib\\site-packages`).
82 If an existing directory is specified, it will be re-used.
83
84 .. versionchanged:: 3.5
85 The use of ``venv`` is now recommended for creating virtual environments.
86
87 .. deprecated-removed:: 3.6 3.8
88 :program:`pyvenv` was the recommended tool for creating virtual environments
89 for Python 3.3 and 3.4, and replaced in 3.5 by executing ``venv`` directly.
90
91 .. highlight:: none
92
93 On Windows, invoke the ``venv`` command as follows:
94
95 .. code-block:: ps1con
96
97 PS> python -m venv C:\path\to\new\virtual\environment
98
99 The command, if run with ``-h``, will show the available options::
100
101 usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
102 [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
103 [--without-scm-ignore-files]
104 ENV_DIR [ENV_DIR ...]
105
106 Creates virtual Python environments in one or more target directories.
107
108 Once an environment has been created, you may wish to activate it, e.g. by
109 sourcing an activate script in its bin directory.
110
111 .. _venv-cli:
112 .. program:: venv
113
114 .. option:: ENV_DIR
115
116 A required argument specifying the directory to create the environment in.
117
118 .. option:: --system-site-packages
119
120 Give the virtual environment access to the system site-packages directory.
121
122 .. option:: --symlinks
123
124 Try to use symlinks rather than copies, when symlinks are not the default for the platform.
125
126 .. option:: --copies
127
128 Try to use copies rather than symlinks, even when symlinks are the default for the platform.
129
130 .. option:: --clear
131
132 Delete the contents of the environment directory if it already exists, before environment creation.
133
134 .. option:: --upgrade
135
136 Upgrade the environment directory to use this version of Python, assuming Python has been upgraded in-place.
137
138 .. option:: --without-pip
139
140 Skips installing or upgrading pip in the virtual environment (pip is bootstrapped by default).
141
142 .. option:: --prompt <PROMPT>
143
144 Provides an alternative prompt prefix for this environment.
145
146 .. option:: --upgrade-deps
147
148 Upgrade core dependencies (pip) to the latest version in PyPI.
149
150 .. option:: --without-scm-ignore-files
151
152 Skips adding SCM ignore files to the environment directory (Git is supported by default).
153
154
155 .. versionchanged:: 3.4
156 Installs pip by default, added the ``--without-pip`` and ``--copies``
157 options.
158
159 .. versionchanged:: 3.4
160 In earlier versions, if the target directory already existed, an error was
161 raised, unless the ``--clear`` or ``--upgrade`` option was provided.
162
163 .. versionchanged:: 3.9
164 Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI.
165
166 .. versionchanged:: 3.12
167
168 ``setuptools`` is no longer a core venv dependency.
169
170 .. versionchanged:: 3.13
171
172 Added the ``--without-scm-ignore-files`` option.
173 .. versionchanged:: 3.13
174 ``venv`` now creates a :file:`.gitignore` file for Git by default.
175
176 .. note::
177 While symlinks are supported on Windows, they are not recommended. Of
178 particular note is that double-clicking ``python.exe`` in File Explorer
179 will resolve the symlink eagerly and ignore the virtual environment.
180
181 .. note::
182 On Microsoft Windows, it may be required to enable the ``Activate.ps1``
183 script by setting the execution policy for the user. You can do this by
184 issuing the following PowerShell command:
185
186 .. code-block:: powershell
187
188 PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
189
190 See `About Execution Policies
191 <https://go.microsoft.com/fwlink/?LinkID=135170>`_
192 for more information.
193
194 The created :file:`pyvenv.cfg` file also includes the
195 ``include-system-site-packages`` key, set to ``true`` if ``venv`` is
196 run with the ``--system-site-packages`` option, ``false`` otherwise.
197
198 Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
199 invoked to bootstrap ``pip`` into the virtual environment.
200
201 Multiple paths can be given to ``venv``, in which case an identical virtual
202 environment will be created, according to the given options, at each provided
203 path.
204
205 .. _venv-explanation:
206
207 How venvs work
208 --------------
209
210 When a Python interpreter is running from a virtual environment,
211 :data:`sys.prefix` and :data:`sys.exec_prefix`
212 point to the directories of the virtual environment,
213 whereas :data:`sys.base_prefix` and :data:`sys.base_exec_prefix`
214 point to those of the base Python used to create the environment.
215 It is sufficient to check
216 ``sys.prefix != sys.base_prefix`` to determine if the current interpreter is
217 running from a virtual environment.
218
219 A virtual environment may be "activated" using a script in its binary directory
220 (``bin`` on POSIX; ``Scripts`` on Windows).
221 This will prepend that directory to your :envvar:`PATH`, so that running
222 :program:`python` will invoke the environment's Python interpreter
223 and you can run installed scripts without having to use their full path.
224 The invocation of the activation script is platform-specific
225 (:samp:`{<venv>}` must be replaced by the path to the directory
226 containing the virtual environment):
227
228 +-------------+------------+--------------------------------------------------+
229 | Platform | Shell | Command to activate virtual environment |
230 +=============+============+==================================================+
231 | POSIX | bash/zsh | :samp:`$ source {<venv>}/bin/activate` |
232 | +------------+--------------------------------------------------+
233 | | fish | :samp:`$ source {<venv>}/bin/activate.fish` |
234 | +------------+--------------------------------------------------+
235 | | csh/tcsh | :samp:`$ source {<venv>}/bin/activate.csh` |
236 | +------------+--------------------------------------------------+
237 | | pwsh | :samp:`$ {<venv>}/bin/Activate.ps1` |
238 +-------------+------------+--------------------------------------------------+
239 | Windows | cmd.exe | :samp:`C:\\> {<venv>}\\Scripts\\activate.bat` |
240 | +------------+--------------------------------------------------+
241 | | PowerShell | :samp:`PS C:\\> {<venv>}\\Scripts\\Activate.ps1` |
242 +-------------+------------+--------------------------------------------------+
243
244 .. versionadded:: 3.4
245 :program:`fish` and :program:`csh` activation scripts.
246
247 .. versionadded:: 3.8
248 PowerShell activation scripts installed under POSIX for PowerShell Core
249 support.
250
251 You don't specifically *need* to activate a virtual environment,
252 as you can just specify the full path to that environment's
253 Python interpreter when invoking Python.
254 Furthermore, all scripts installed in the environment
255 should be runnable without activating it.
256
257 In order to achieve this, scripts installed into virtual environments have
258 a "shebang" line which points to the environment's Python interpreter,
259 :samp:`#!/{<path-to-venv>}/bin/python`.
260 This means that the script will run with that interpreter regardless of the
261 value of :envvar:`PATH`. On Windows, "shebang" line processing is supported if
262 you have the :ref:`launcher` installed. Thus, double-clicking an installed
263 script in a Windows Explorer window should run it with the correct interpreter
264 without the environment needing to be activated or on the :envvar:`PATH`.
265
266 When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV`
267 environment variable is set to the path of the environment.
268 Since explicitly activating a virtual environment is not required to use it,
269 :envvar:`!VIRTUAL_ENV` cannot be relied upon to determine
270 whether a virtual environment is being used.
271
272 .. warning:: Because scripts installed in environments should not expect the
273 environment to be activated, their shebang lines contain the absolute paths
274 to their environment's interpreters. Because of this, environments are
275 inherently non-portable, in the general case. You should always have a
276 simple means of recreating an environment (for example, if you have a
277 requirements file ``requirements.txt``, you can invoke ``pip install -r
278 requirements.txt`` using the environment's ``pip`` to install all of the
279 packages needed by the environment). If for any reason you need to move the
280 environment to a new location, you should recreate it at the desired
281 location and delete the one at the old location. If you move an environment
282 because you moved a parent directory of it, you should recreate the
283 environment in its new location. Otherwise, software installed into the
284 environment may not work as expected.
285
286 You can deactivate a virtual environment by typing ``deactivate`` in your shell.
287 The exact mechanism is platform-specific and is an internal implementation
288 detail (typically, a script or shell function will be used).
289
290
291 .. _venv-api:
292
293 API
294 ---
295
296 .. highlight:: python
297
298 The high-level method described above makes use of a simple API which provides
299 mechanisms for third-party virtual environment creators to customize environment
300 creation according to their needs, the :class:`EnvBuilder` class.
301
302 .. class:: EnvBuilder(system_site_packages=False, clear=False, \
303 symlinks=False, upgrade=False, with_pip=False, \
304 prompt=None, upgrade_deps=False, \
305 *, scm_ignore_files=frozenset())
306
307 The :class:`EnvBuilder` class accepts the following keyword arguments on
308 instantiation:
309
310 * *system_site_packages* -- a boolean value indicating that the system Python
311 site-packages should be available to the environment (defaults to ``False``).
312
313 * *clear* -- a boolean value which, if true, will delete the contents of
314 any existing target directory, before creating the environment.
315
316 * *symlinks* -- a boolean value indicating whether to attempt to symlink the
317 Python binary rather than copying.
318
319 * *upgrade* -- a boolean value which, if true, will upgrade an existing
320 environment with the running Python - for use when that Python has been
321 upgraded in-place (defaults to ``False``).
322
323 * *with_pip* -- a boolean value which, if true, ensures pip is
324 installed in the virtual environment. This uses :mod:`ensurepip` with
325 the ``--default-pip`` option.
326
327 * *prompt* -- a string to be used after virtual environment is activated
328 (defaults to ``None`` which means directory name of the environment would
329 be used). If the special string ``"."`` is provided, the basename of the
330 current directory is used as the prompt.
331
332 * *upgrade_deps* -- Update the base venv modules to the latest on PyPI
333
334 * *scm_ignore_files* -- Create ignore files based for the specified source
335 control managers (SCM) in the iterable. Support is defined by having a
336 method named ``create_{scm}_ignore_file``. The only value supported by
337 default is ``"git"`` via :meth:`create_git_ignore_file`.
338
339
340 .. versionchanged:: 3.4
341 Added the ``with_pip`` parameter
342
343 .. versionchanged:: 3.6
344 Added the ``prompt`` parameter
345
346 .. versionchanged:: 3.9
347 Added the ``upgrade_deps`` parameter
348
349 .. versionchanged:: 3.13
350 Added the ``scm_ignore_files`` parameter
351
352 :class:`EnvBuilder` may be used as a base class.
353
354 .. method:: create(env_dir)
355
356 Create a virtual environment by specifying the target directory
357 (absolute or relative to the current directory) which is to contain the
358 virtual environment. The ``create`` method will either create the
359 environment in the specified directory, or raise an appropriate
360 exception.
361
362 The ``create`` method of the :class:`EnvBuilder` class illustrates the
363 hooks available for subclass customization::
364
365 def create(self, env_dir):
366 """
367 Create a virtualized Python environment in a directory.
368 env_dir is the target directory to create an environment in.
369 """
370 env_dir = os.path.abspath(env_dir)
371 context = self.ensure_directories(env_dir)
372 self.create_configuration(context)
373 self.setup_python(context)
374 self.setup_scripts(context)
375 self.post_setup(context)
376
377 Each of the methods :meth:`ensure_directories`,
378 :meth:`create_configuration`, :meth:`setup_python`,
379 :meth:`setup_scripts` and :meth:`post_setup` can be overridden.
380
381 .. method:: ensure_directories(env_dir)
382
383 Creates the environment directory and all necessary subdirectories that
384 don't already exist, and returns a context object. This context object
385 is just a holder for attributes (such as paths) for use by the other
386 methods. If the :class:`EnvBuilder` is created with the arg
387 ``clear=True``, contents of the environment directory will be cleared
388 and then all necessary subdirectories will be recreated.
389
390 The returned context object is a :class:`types.SimpleNamespace` with the
391 following attributes:
392
393 * ``env_dir`` - The location of the virtual environment. Used for
394 ``__VENV_DIR__`` in activation scripts (see :meth:`install_scripts`).
395
396 * ``env_name`` - The name of the virtual environment. Used for
397 ``__VENV_NAME__`` in activation scripts (see :meth:`install_scripts`).
398
399 * ``prompt`` - The prompt to be used by the activation scripts. Used for
400 ``__VENV_PROMPT__`` in activation scripts (see :meth:`install_scripts`).
401
402 * ``executable`` - The underlying Python executable used by the virtual
403 environment. This takes into account the case where a virtual environment
404 is created from another virtual environment.
405
406 * ``inc_path`` - The include path for the virtual environment.
407
408 * ``lib_path`` - The purelib path for the virtual environment.
409
410 * ``bin_path`` - The script path for the virtual environment.
411
412 * ``bin_name`` - The name of the script path relative to the virtual
413 environment location. Used for ``__VENV_BIN_NAME__`` in activation
414 scripts (see :meth:`install_scripts`).
415
416 * ``env_exe`` - The name of the Python interpreter in the virtual
417 environment. Used for ``__VENV_PYTHON__`` in activation scripts
418 (see :meth:`install_scripts`).
419
420 * ``env_exec_cmd`` - The name of the Python interpreter, taking into
421 account filesystem redirections. This can be used to run Python in
422 the virtual environment.
423
424
425 .. versionchanged:: 3.11
426 The *venv*
427 :ref:`sysconfig installation scheme <installation_paths>`
428 is used to construct the paths of the created directories.
429
430 .. versionchanged:: 3.12
431 The attribute ``lib_path`` was added to the context, and the context
432 object was documented.
433
434 .. method:: create_configuration(context)
435
436 Creates the ``pyvenv.cfg`` configuration file in the environment.
437
438 .. method:: setup_python(context)
439
440 Creates a copy or symlink to the Python executable in the environment.
441 On POSIX systems, if a specific executable ``python3.x`` was used,
442 symlinks to ``python`` and ``python3`` will be created pointing to that
443 executable, unless files with those names already exist.
444
445 .. method:: setup_scripts(context)
446
447 Installs activation scripts appropriate to the platform into the virtual
448 environment.
449
450 .. method:: upgrade_dependencies(context)
451
452 Upgrades the core venv dependency packages (currently :pypi:`pip`)
453 in the environment. This is done by shelling out to the
454 ``pip`` executable in the environment.
455
456 .. versionadded:: 3.9
457 .. versionchanged:: 3.12
458
459 :pypi:`setuptools` is no longer a core venv dependency.
460
461 .. method:: post_setup(context)
462
463 A placeholder method which can be overridden in third party
464 implementations to pre-install packages in the virtual environment or
465 perform other post-creation steps.
466
467 .. method:: install_scripts(context, path)
468
469 This method can be
470 called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
471 assist in installing custom scripts into the virtual environment.
472
473 *path* is the path to a directory that should contain subdirectories
474 ``common``, ``posix``, ``nt``; each containing scripts destined for the
475 ``bin`` directory in the environment. The contents of ``common`` and the
476 directory corresponding to :data:`os.name` are copied after some text
477 replacement of placeholders:
478
479 * ``__VENV_DIR__`` is replaced with the absolute path of the environment
480 directory.
481
482 * ``__VENV_NAME__`` is replaced with the environment name (final path
483 segment of environment directory).
484
485 * ``__VENV_PROMPT__`` is replaced with the prompt (the environment
486 name surrounded by parentheses and with a following space)
487
488 * ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
489 (either ``bin`` or ``Scripts``).
490
491 * ``__VENV_PYTHON__`` is replaced with the absolute path of the
492 environment's executable.
493
494 The directories are allowed to exist (for when an existing environment
495 is being upgraded).
496
497 .. method:: create_git_ignore_file(context)
498
499 Creates a ``.gitignore`` file within the virtual environment that causes
500 the entire directory to be ignored by the Git source control manager.
501
502 .. versionadded:: 3.13
503
504 .. versionchanged:: 3.7.2
505 Windows now uses redirector scripts for ``python[w].exe`` instead of
506 copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
507 nothing unless running from a build in the source tree.
508
509 .. versionchanged:: 3.7.3
510 Windows copies the redirector scripts as part of :meth:`setup_python`
511 instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
512 When using symlinks, the original executables will be linked.
513
514 There is also a module-level convenience function:
515
516 .. function:: create(env_dir, system_site_packages=False, clear=False, \
517 symlinks=False, with_pip=False, prompt=None, \
518 upgrade_deps=False, *, scm_ignore_files=frozenset())
519
520 Create an :class:`EnvBuilder` with the given keyword arguments, and call its
521 :meth:`~EnvBuilder.create` method with the *env_dir* argument.
522
523 .. versionadded:: 3.3
524
525 .. versionchanged:: 3.4
526 Added the *with_pip* parameter
527
528 .. versionchanged:: 3.6
529 Added the *prompt* parameter
530
531 .. versionchanged:: 3.9
532 Added the *upgrade_deps* parameter
533
534 .. versionchanged:: 3.13
535 Added the *scm_ignore_files* parameter
536
537 An example of extending ``EnvBuilder``
538 --------------------------------------
539
540 The following script shows how to extend :class:`EnvBuilder` by implementing a
541 subclass which installs setuptools and pip into a created virtual environment::
542
543 import os
544 import os.path
545 from subprocess import Popen, PIPE
546 import sys
547 from threading import Thread
548 from urllib.parse import urlsplit
549 from urllib.request import urlretrieve
550 import venv
551
552 class ExtendedEnvBuilder(venv.EnvBuilder):
553 """
554 This builder installs setuptools and pip so that you can pip or
555 easy_install other packages into the created virtual environment.
556
557 :param nodist: If true, setuptools and pip are not installed into the
558 created virtual environment.
559 :param nopip: If true, pip is not installed into the created
560 virtual environment.
561 :param progress: If setuptools or pip are installed, the progress of the
562 installation can be monitored by passing a progress
563 callable. If specified, it is called with two
564 arguments: a string indicating some progress, and a
565 context indicating where the string is coming from.
566 The context argument can have one of three values:
567 'main', indicating that it is called from virtualize()
568 itself, and 'stdout' and 'stderr', which are obtained
569 by reading lines from the output streams of a subprocess
570 which is used to install the app.
571
572 If a callable is not specified, default progress
573 information is output to sys.stderr.
574 """
575
576 def __init__(self, *args, **kwargs):
577 self.nodist = kwargs.pop('nodist', False)
578 self.nopip = kwargs.pop('nopip', False)
579 self.progress = kwargs.pop('progress', None)
580 self.verbose = kwargs.pop('verbose', False)
581 super().__init__(*args, **kwargs)
582
583 def post_setup(self, context):
584 """
585 Set up any packages which need to be pre-installed into the
586 virtual environment being created.
587
588 :param context: The information for the virtual environment
589 creation request being processed.
590 """
591 os.environ['VIRTUAL_ENV'] = context.env_dir
592 if not self.nodist:
593 self.install_setuptools(context)
594 # Can't install pip without setuptools
595 if not self.nopip and not self.nodist:
596 self.install_pip(context)
597
598 def reader(self, stream, context):
599 """
600 Read lines from a subprocess' output stream and either pass to a progress
601 callable (if specified) or write progress information to sys.stderr.
602 """
603 progress = self.progress
604 while True:
605 s = stream.readline()
606 if not s:
607 break
608 if progress is not None:
609 progress(s, context)
610 else:
611 if not self.verbose:
612 sys.stderr.write('.')
613 else:
614 sys.stderr.write(s.decode('utf-8'))
615 sys.stderr.flush()
616 stream.close()
617
618 def install_script(self, context, name, url):
619 _, _, path, _, _ = urlsplit(url)
620 fn = os.path.split(path)[-1]
621 binpath = context.bin_path
622 distpath = os.path.join(binpath, fn)
623 # Download script into the virtual environment's binaries folder
624 urlretrieve(url, distpath)
625 progress = self.progress
626 if self.verbose:
627 term = '\n'
628 else:
629 term = ''
630 if progress is not None:
631 progress('Installing %s ...%s' % (name, term), 'main')
632 else:
633 sys.stderr.write('Installing %s ...%s' % (name, term))
634 sys.stderr.flush()
635 # Install in the virtual environment
636 args = [context.env_exe, fn]
637 p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
638 t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
639 t1.start()
640 t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))
641 t2.start()
642 p.wait()
643 t1.join()
644 t2.join()
645 if progress is not None:
646 progress('done.', 'main')
647 else:
648 sys.stderr.write('done.\n')
649 # Clean up - no longer needed
650 os.unlink(distpath)
651
652 def install_setuptools(self, context):
653 """
654 Install setuptools in the virtual environment.
655
656 :param context: The information for the virtual environment
657 creation request being processed.
658 """
659 url = "https://bootstrap.pypa.io/ez_setup.py"
660 self.install_script(context, 'setuptools', url)
661 # clear up the setuptools archive which gets downloaded
662 pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')
663 files = filter(pred, os.listdir(context.bin_path))
664 for f in files:
665 f = os.path.join(context.bin_path, f)
666 os.unlink(f)
667
668 def install_pip(self, context):
669 """
670 Install pip in the virtual environment.
671
672 :param context: The information for the virtual environment
673 creation request being processed.
674 """
675 url = 'https://bootstrap.pypa.io/get-pip.py'
676 self.install_script(context, 'pip', url)
677
678
679 def main(args=None):
680 import argparse
681
682 parser = argparse.ArgumentParser(prog=__name__,
683 description='Creates virtual Python '
684 'environments in one or '
685 'more target '
686 'directories.')
687 parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
688 help='A directory in which to create the '
689 'virtual environment.')
690 parser.add_argument('--no-setuptools', default=False,
691 action='store_true', dest='nodist',
692 help="Don't install setuptools or pip in the "
693 "virtual environment.")
694 parser.add_argument('--no-pip', default=False,
695 action='store_true', dest='nopip',
696 help="Don't install pip in the virtual "
697 "environment.")
698 parser.add_argument('--system-site-packages', default=False,
699 action='store_true', dest='system_site',
700 help='Give the virtual environment access to the '
701 'system site-packages dir.')
702 if os.name == 'nt':
703 use_symlinks = False
704 else:
705 use_symlinks = True
706 parser.add_argument('--symlinks', default=use_symlinks,
707 action='store_true', dest='symlinks',
708 help='Try to use symlinks rather than copies, '
709 'when symlinks are not the default for '
710 'the platform.')
711 parser.add_argument('--clear', default=False, action='store_true',
712 dest='clear', help='Delete the contents of the '
713 'virtual environment '
714 'directory if it already '
715 'exists, before virtual '
716 'environment creation.')
717 parser.add_argument('--upgrade', default=False, action='store_true',
718 dest='upgrade', help='Upgrade the virtual '
719 'environment directory to '
720 'use this version of '
721 'Python, assuming Python '
722 'has been upgraded '
723 'in-place.')
724 parser.add_argument('--verbose', default=False, action='store_true',
725 dest='verbose', help='Display the output '
726 'from the scripts which '
727 'install setuptools and pip.')
728 options = parser.parse_args(args)
729 if options.upgrade and options.clear:
730 raise ValueError('you cannot supply --upgrade and --clear together.')
731 builder = ExtendedEnvBuilder(system_site_packages=options.system_site,
732 clear=options.clear,
733 symlinks=options.symlinks,
734 upgrade=options.upgrade,
735 nodist=options.nodist,
736 nopip=options.nopip,
737 verbose=options.verbose)
738 for d in options.dirs:
739 builder.create(d)
740
741 if __name__ == '__main__':
742 rc = 1
743 try:
744 main()
745 rc = 0
746 except Exception as e:
747 print('Error: %s' % e, file=sys.stderr)
748 sys.exit(rc)
749
750
751 This script is also available for download `online
752 <https://gist.github.com/vsajip/4673395>`_.