Commits

Carl Meyer  committed 7deda2b

Bring venv documentation up to date with implementation and remove references to DistributeEnvBuilder.

  • Participants
  • Parent commits 88d6f22
  • Branches base_prefix

Comments (0)

Files changed (1)

File Doc/library/venv.rst

 
 The command, if run with ``-h``, will show the available options::
 
-    usage: pyvenv [-h] [--no-distribute] [--no-site-packages] [--clear]
+    usage: pyvenv [-h] [--system-site-packages] [--symlink] [--clear]
                   ENV_DIR [ENV_DIR ...]
 
     Creates virtual Python environments in one or more target directories.
 
     optional arguments:
       -h, --help             show this help message and exit
-      --no-distribute        Don't install Distribute in the virtual environment.
       --system-site-packages Give access to the global site-packages dir to the
                              virtual environment.
+      --symlink              Attempt to symlink rather than copy.
       --clear                Delete the environment directory if it already exists.
                              If not specified and the directory exists, an error is
                              raised.
 
-.. note::
-
-   The current version allows Distribute to be optionally installed within
-   environments, so facilitate installation of existing packages and
-   experimentation with virtual environments. This functionality will be
-   removed from the standard library before the release of Python 3.3: it is
-   expected that third-party tools using this module will fill the gap.
-
 
 If the target directory already exists an error will be raised, unless
 the ``--clear`` option was provided, in which case the target
 
 The created ``pyvenv.cfg`` file also includes the
 ``include-system-site-packages`` key, set to ``true`` if ``venv`` is
-run with the ``--use-site-packages`` option, ``false`` otherwise.
+run with the ``--system-site-packages`` option, ``false`` otherwise.
 
 Multiple paths can be given to ``pyvenv``, in which case an identical
 virtualenv will be created, according to the given options, at each
      existing target directory instead of raising an exception
      (defaults to ``False``).
 
-   * ``use_symlinks`` - A Boolean value indicating whether to attempt
+   * ``symlinks`` - A Boolean value indicating whether to attempt
      to symlink the Python binary (and any necessary DLLs or other
      binaries, e.g. ``pythonw.exe``), rather than copying. Defaults to
      ``True`` on Linux and Unix systems, but ``False`` on Windows and
 convenience::
 
     def create(env_dir,
-               system_site_packages=False, clear=False, use_symlinks=None):
+               system_site_packages=False, clear=False, symlinks=False):
         builder = EnvBuilder(
-            system_site_packages=system_site_packages, clear=clear)
+            system_site_packages=system_site_packages,
+            clear=clear,
+            symlinks=symlinks)
         builder.create(env_dir)
 
 The ``create`` method of the ``EnvBuilder`` class illustrates the
-hooks available for customization::
+hooks available for subclass customization::
 
     def create(self, env_dir):
         """
         context = self.create_directories(env_dir)
         self.create_configuration(context)
         self.setup_python(context)
-        self.setup_packages(context)
         self.setup_scripts(context)
+        self.post_setup(context)
 
 Each of the methods ``create_directories``, ``create_configuration``,
-``setup_python``, ``setup_packages`` and ``setup_scripts`` can be
+``setup_python``, ``setup_scripts`` and ``post_setup`` can be
 overridden.  The functions of these methods are:
 
    * ``create_directories`` - creates the environment directory and
    * ``setup_python`` - creates a copy of the Python executable (and,
      under Windows, DLLs) in the environment.
 
-   * ``setup_packages`` - A placeholder method which can be overridden
+   * ``setup_scripts`` - Installs activation scripts appropriate to the
+     platform into the virtual environment.
+
+   * ``post_setup`` - A placeholder method which can be overridden
      in third party implementations to pre-install packages in the
-     virtual environment.
+     virtual environment or perform other post-creation steps.
 
-   * ``setup_scripts`` - A placeholder methd which can be overridden
-     in third party implementations to pre-install scripts (such as
-     activation and deactivation scripts) in the virtual environment.
+In addition, ``EnvBuilder`` provides an ``install_scripts`` utility
+method that can be called from ``setup_scripts`` or ``post_setup`` in
+subclasses to assist in installing custom scripts into the virtual
+environment. The method accepts as arguments the context object (see
+above) and a path to a directory. The directory should contain
+subdirectories "common", "posix", "nt", each containing scripts
+destined for the bin directory in the environment. The contents of
+"common" and the directory corresponding to ``os.name`` are copied
+after some text replacement of placeholders:
 
-The ``DistributeEnvBuilder`` subclass in the reference implementation
-illustrates how these last two methods can be used in practice. It's
-not envisaged that ``DistributeEnvBuilder`` will be actually added to
-Python core, but it makes the reference implementation more
-immediately useful for testing and exploratory purposes.
+* ``__VENV_DIR__`` is replaced with the absolute path of the
+  environment directory.
 
-   * The ``setup_packages`` method installs Distribute in the target
-     environment. This is needed at the moment in order to actually
-     install most packages in an environment, since most packages are
-     not yet packaging / setup.cfg based.
+* ``__VENV_NAME__`` is replaced with the environment name (final path
+  segment of environment directory).
 
-   * The ``setup_scripts`` method installs activation and pysetup3
-     scripts in the environment. This is also done in a configurable
-     way: A ``scripts`` property on the builder is expected to provide
-     a buffer which is a base64-encoded zip file. The zip file
-     contains directories "common", "nt", and "posix", each
-     containing scripts destined for the bin directory in the
-     environment. The contents of "common" and the directory
-     corresponding to the platform are copied after doing some
-     text replacement of placeholders:
+* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
+  (either ``bin`` or ``Scripts``).
 
-        * ``__VIRTUAL_ENV__`` is replaced with absolute path of the
-          environment directory.
-
-        * ``__VIRTUAL_PROMPT__`` is replaced with the environment
-          prompt prefix.
-
-        * ``__BIN_NAME__`` is replaced with the name of the bin
-          directory.
-
-        * ``__ENV_PYTHON__`` is replaced with the absolute path of the
-          environment's executable.
-
-
+* ``__VENV_PYTHON__`` is replaced with the absolute path of the
+  environment's executable.