one does not simply "create a virtualenv". one should "create a virtual env...

Steve Piercy

2016-04-12 d67566acebf890a603fad0e9069d5e131dfb5b31

one does not simply "create a virtualenv". one should "create a virtual environment".
- Fixes #2483

 docs/conventions.rst

@@ -57,7 +57,7 @@

     $ $VENV/bin/nosetests

(See :term:`virtualenv` for the meaning of ``$VENV``)
(See :term:`venv` for the meaning of ``$VENV``)

Example blocks representing Windows ``cmd.exe`` commands are prefixed with a
drive letter and/or a directory name, e.g.:
@@ -66,7 +66,7 @@

     c:\examples> %VENV%\Scripts\nosetests

(See :term:`virtualenv` for the meaning of ``%VENV%``)
(See :term:`venv` for the meaning of ``%VENV%``)

Sometimes, when it's unknown which directory is current, Windows ``cmd.exe``
example block commands are prefixed only with a ``>`` character, e.g.:

 docs/glossary.rst

@@ -155,9 +155,9 @@
     request before it returns a :term:`context` resource.

   virtualenv
     A term referring both to an isolated Python environment,
     or `the leading tool <http://www.virtualenv.org>`_ that allows one to
     create such environments.
     The `virtualenv tool <https://virtualenv.pypa.io/en/latest/>`_ that allows
     one to create virtual environments. In Python 3.3 and greater,
     :term:`venv` is the preferred tool.

     Note: whenever you encounter commands prefixed with ``$VENV`` (Unix)
     or ``%VENV`` (Windows), know that that is the environment variable whose
@@ -1012,8 +1012,8 @@

   console script
     A script written to the ``bin`` (on UNIX, or ``Scripts`` on Windows)
     directory of a Python installation or :term:`virtualenv` as the result of
     running ``setup.py install`` or ``setup.py develop``.
     directory of a Python installation or :term:`virtual environment` as the
     result of running ``pip install`` or ``pip install -e .``.

   introspector
     An object with the methods described by
@@ -1110,6 +1110,14 @@
      but it is deprecated in 3.6 in favor of ``python3 -m venv`` which is
      backward compatible.

   virtual environment
      An isolated Python environment that allows packages to be installed for
      use by a particular application, rather than being installed system wide.

   venv
      The `Python Packaging Authority's <https://www.pypa.io/>`_ recommended
      tool for creating virtual environments.

      Note: whenever you encounter commands prefixed with ``$VENV`` (Unix)
      or ``%VENV`` (Windows), know that that is the environment variable whose
      value is the root of the virtual environment in question.

 docs/narr/commandline.rst

@@ -815,17 +815,17 @@
----------------------------------------

A "console script" is :term:`setuptools` terminology for a script that gets
installed into the ``bin`` directory of a Python :term:`virtualenv` (or "base"
Python environment) when a :term:`distribution` which houses that script is
installed.  Because it's installed into the ``bin`` directory of a virtualenv
when the distribution is installed, it's a convenient way to package and
distribute functionality that you can call from the command-line. It's often
more convenient to create a console script than it is to create a ``.py``
script and instruct people to call it with the "right" Python interpreter.  A
console script generates a file that lives in ``bin``, and when it's invoked it
will always use the "right" Python environment, which means it will always be
invoked in an environment where all the libraries it needs (such as Pyramid)
are available.
installed into the ``bin`` directory of a Python :term:`virtual environment`
(or "base" Python environment) when a :term:`distribution` which houses that
script is installed. Because it's installed into the ``bin`` directory of a
virtual environment when the distribution is installed, it's a convenient way
to package and distribute functionality that you can call from the
command-line. It's often more convenient to create a console script than it is
to create a ``.py`` script and instruct people to call it with the "right"
Python interpreter. A console script generates a file that lives in ``bin``,
and when it's invoked it will always use the "right" Python environment, which
means it will always be invoked in an environment where all the libraries it
needs (such as Pyramid) are available.

In general, you can make your script into a console script by doing the
following:
@@ -843,7 +843,7 @@
- Run ``pip install -e .`` or ``pip install .`` to get your distribution
  reinstalled. When you reinstall your distribution, a file representing the
  script that you named in the last step will be in the ``bin`` directory of
  the virtualenv in which you installed the distribution. It will be
  the virtual environment in which you installed the distribution. It will be
  executable. Invoking it from a terminal will execute your callable.

As an example, let's create some code that can be invoked by a console script
@@ -1029,7 +1029,7 @@
         )

Once you've done this, invoking ``$VENV/bin/pip install -e .`` will install a
file named ``show_settings`` into the ``$somevirtualenv/bin`` directory with a
file named ``show_settings`` into the ``$somevenv/bin`` directory with a
small bit of Python code that points to your entry point. It will be
executable. Running it without any arguments will print an error and exit.
Running it with a single argument that is the path of a config file will print

 docs/narr/i18n.rst

@@ -270,12 +270,12 @@
   $ sudo apt-get install gettext

Installing Lingua is done with the Python packaging tools. If the
:term:`virtualenv` into which you've installed your :app:`Pyramid` application
lives in ``/my/virtualenv``, you can install Lingua like so:
:term:`virtual environment` into which you've installed your :app:`Pyramid`
application lives in ``/my/venv``, you can install Lingua like so:

.. code-block:: text

   $ cd /my/virtualenv
   $ cd /my/venv
   $ $VENV/bin/easy_install lingua

Installation on Windows
@@ -288,8 +288,8 @@
``$PATH``.

Installing Lingua is done with the Python packaging tools. If the
:term:`virtualenv` into which you've installed your :app:`Pyramid` application
lives in ``C:\my\virtualenv``, you can install Lingua like so:
:term:`virtual environment` into which you've installed your :app:`Pyramid`
application lives in ``C:\my\venv``, you can install Lingua like so:

.. code-block:: text


 docs/narr/install.rst

@@ -150,7 +150,7 @@
:ref:`if-you-don-t-yet-have-a-python-interpreter-unix`, and satisfying the
:ref:`requirements-for-installing-packages`, you can now install Pyramid.

#. Make a :term:`virtualenv` workspace:
#. Make a :term:`virtual environment` workspace:

   .. code-block:: bash

@@ -184,7 +184,7 @@
:ref:`if-you-don-t-yet-have-a-python-interpreter-windows`, and satisfying the
:ref:`requirements-for-installing-packages`, you can now install Pyramid.

#. Make a :term:`virtualenv` workspace:
#. Make a :term:`virtual environment` workspace:

   .. code-block:: ps1con


 docs/narr/project.rst

@@ -67,14 +67,14 @@
.. seealso:: See also the output of :ref:`pcreate --help <pcreate_script>`.

In :ref:`installing_chapter`, you created a virtual Python environment via the
``virtualenv`` command.  To start a :app:`Pyramid` :term:`project`, use the
``pcreate`` command installed within the virtualenv.  We'll choose the
``venv`` command.  To start a :app:`Pyramid` :term:`project`, use the
``pcreate`` command installed within the virtual environment.  We'll choose the
``starter`` scaffold for this purpose.  When we invoke ``pcreate``, it will
create a directory that represents our project.

In :ref:`installing_chapter` we called the virtualenv directory ``env``. The
following commands assume that our current working directory is the ``env``
directory.
In :ref:`installing_chapter` we called the virtual environment directory
``env``. The following commands assume that our current working directory is
the ``env`` directory.

The below example uses the ``pcreate`` command to create a project with the
``starter`` scaffold.
@@ -112,16 +112,16 @@
which holds very simple :app:`Pyramid` sample code.  This is where you'll edit
your application's Python code and templates.

We created this project within an ``env`` virtualenv directory.  However, note
that this is not mandatory.  The project directory can go more or less anywhere
on your filesystem.  You don't need to put it in a special "web server"
directory, and you don't need to put it within a virtualenv directory.  The
author uses Linux mainly, and tends to put project directories which he creates
within his ``~/projects`` directory.  On Windows, it's a good idea to put
project directories within a directory that contains no space characters, so
it's wise to *avoid* a path that contains, i.e., ``My Documents``.  As a
result, the author, when he uses Windows, just puts his projects in
``C:\projects``.
We created this project within an ``env`` virtual environment directory.
However, note that this is not mandatory. The project directory can go more or
less anywhere on your filesystem. You don't need to put it in a special "web
server" directory, and you don't need to put it within a virtual environment
directory. The author uses Linux mainly, and tends to put project directories
which he creates within his ``~/projects`` directory. On Windows, it's a good
idea to put project directories within a directory that contains no space
characters, so it's wise to *avoid* a path that contains, i.e., ``My
Documents``. As a result, the author, when he uses Windows, just puts his
projects in ``C:\projects``.

.. warning::

@@ -140,9 +140,9 @@

To install a newly created project for development, you should ``cd`` to the
newly created project directory and use the Python interpreter from the
:term:`virtualenv` you created during :ref:`installing_chapter` to invoke the
command ``pip install -e .``, which installs the project in development mode
(``-e`` is for "editable") into the current directory (``.``).
:term:`virtual environment` you created during :ref:`installing_chapter` to
invoke the command ``pip install -e .``, which installs the project in
development mode (``-e`` is for "editable") into the current directory (``.``).

The file named ``setup.py`` will be in the root of the pcreate-generated
project directory.  The ``python`` you're invoking should be the one that lives

 docs/quick_tutorial/databases.rst

@@ -176,7 +176,7 @@

The ``initialize_tutorial_db`` is a nice example of framework support.
You point your setup at the location of some ``[console_scripts]`` and
these get generated into your virtualenv's ``bin`` directory. Our
these get generated into your virtual environment's ``bin`` directory. Our
console script follows the pattern of being fed a configuration file
with all the bootstrapping. It then opens SQLAlchemy and creates the
root of the wiki, which also makes the SQLite file. Note the

 docs/quick_tutorial/requirements.rst

@@ -129,7 +129,7 @@
Next within ``projects`` is your workspace directory, here named
``quick_tutorial``. A workspace is a common term used by integrated
development environments (IDE) like PyCharm and PyDev that stores
isolated Python environments (virtualenvs) and specific project files
isolated Python environments (virtual environments) and specific project files
and repositories.


@@ -174,7 +174,7 @@
    c:\> c:\Python35\python3 -m venv %VENV%

.. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
   2's `virtualenv <http://www.virtualenv.org/en/latest/>`_ package.
   2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package.


.. _install-pyramid:

 docs/tutorials/modwsgi/index.rst

@@ -24,21 +24,15 @@
    system.  If you do not, install Apache 2.X for your platform in
    whatever manner makes sense.

#.  It is also assumed that you have satisfied the
    :ref:`requirements-for-installing-packages`.

#.  Once you have Apache installed, install ``mod_wsgi``.  Use the
    (excellent) `installation instructions
    <http://code.google.com/p/modwsgi/wiki/InstallationInstructions>`_
    for your platform into your system's Apache installation.

#.  Install :term:`virtualenv` into the Python which mod_wsgi will
    run using pip.

    .. code-block:: text

       $ sudo /usr/bin/pip install virtualenv

    This command may need to be performed as the root user.

#.  Create a :term:`virtualenv` which we'll use to install our
#.  Create a :term:`virtual environment` which we'll use to install our
    application.

    .. code-block:: text
@@ -46,9 +40,9 @@
       $ cd ~
       $ mkdir modwsgi
       $ cd modwsgi
       $ /usr/local/bin/virtualenv env
       $ python3 -m venv env

#.  Install :app:`Pyramid` into the newly created virtualenv:
#.  Install :app:`Pyramid` into the newly created virtual environment:

    .. code-block:: text

@@ -67,7 +61,7 @@
       $ cd myapp
       $ $VENV/bin/pip install -e .

#.  Within the virtualenv directory (``~/modwsgi/env``), create a
#.  Within the virtual environment directory (``~/modwsgi/env``), create a
    script named ``pyramid.wsgi``.  Give it these contents:

    .. code-block:: python

 docs/tutorials/wiki/distributing.rst

@@ -7,8 +7,8 @@
Once your application works properly, you can create a "tarball" from it by
using the ``setup.py sdist`` command.  The following commands assume your
current working directory is the ``tutorial`` package we've created and that
the parent directory of the ``tutorial`` package is a virtualenv representing
a :app:`Pyramid` environment.
the parent directory of the ``tutorial`` package is a virtual environment
representing a :app:`Pyramid` environment.

On UNIX:


 docs/tutorials/wiki/installation.rst

@@ -12,8 +12,7 @@
install Pyramid**.  Thereby you will satisfy the following requirements.

* A Python interpreter is installed on your operating system.
* :term:`virtualenv` is installed.
* :term:`pip` will be installed when we create a virtual environment.
* You've satisfied the :ref:`requirements-for-installing-packages`.


Create directory to contain the project
@@ -39,8 +38,8 @@
Create and use a virtual Python environment
-------------------------------------------

Next let's create a ``virtualenv`` workspace for our project.  We will use the
``VENV`` environment variable instead of the absolute path of the virtual
Next let's create a virtual environment workspace for our project.  We will use
the ``VENV`` environment variable instead of the absolute path of the virtual
environment.

On UNIX
@@ -49,7 +48,7 @@
.. code-block:: bash

   $ export VENV=~/pyramidtut
   $ virtualenv $VENV
   $ python3 -m venv $VENV

On Windows
^^^^^^^^^^
@@ -71,7 +70,7 @@

.. code-block:: ps1con

   c:\> c:\Python35\Scripts\virtualenv %VENV%
   c:\> c:\Python35\Scripts\python -m venv %VENV%


Upgrade ``pip`` and ``setuptools`` in the virtual environment
@@ -164,8 +163,9 @@

.. note:: If you are using Windows, the ``zodb`` scaffold may not deal
   gracefully with installation into a location that contains spaces in the
   path. If you experience startup problems, try putting both the virtualenv
   and the project into directories that do not contain spaces in their paths.
   path. If you experience startup problems, try putting both the virtual
   environment and the project into directories that do not contain spaces in
   their paths.


.. _installing_project_in_dev_mode_zodb:
@@ -177,7 +177,7 @@
project as a development egg in your workspace using the ``pip install -e .``
command. In order to do so, change directory to the ``tutorial`` directory that
you created in :ref:`making_a_project`, and run the ``pip install -e .``
command using the virtualenv Python interpreter.
command using the virtual environment Python interpreter.

On UNIX
^^^^^^^
@@ -283,8 +283,8 @@
"coverage" information, exposing which lines of your project are covered by the
tests.

We've already installed the ``pytest-cov`` package into our ``virtualenv``, so
we can run the tests with coverage.
We've already installed the ``pytest-cov`` package into our virtual
environment, so we can run the tests with coverage.

On UNIX
^^^^^^^

 docs/tutorials/wiki2/installation.rst

@@ -12,8 +12,7 @@
install Pyramid**.  Thereby you will satisfy the following requirements.

* A Python interpreter is installed on your operating system.
* :term:`virtualenv` is installed.
* :term:`pip` will be installed when we create a virtual environment.
* You've satisfied the :ref:`requirements-for-installing-packages`.


Create directory to contain the project
@@ -39,8 +38,8 @@
Create and use a virtual Python environment
-------------------------------------------

Next let's create a ``virtualenv`` workspace for our project.  We will use the
``VENV`` environment variable instead of the absolute path of the virtual
Next let's create a virtual environment workspace for our project.  We will use
the ``VENV`` environment variable instead of the absolute path of the virtual
environment.

On UNIX
@@ -49,7 +48,7 @@
.. code-block:: bash

   $ export VENV=~/pyramidtut
   $ virtualenv $VENV
   $ python3 -m venv $VENV

On Windows
^^^^^^^^^^
@@ -71,7 +70,7 @@

.. code-block:: ps1con

   c:\> c:\Python35\Scripts\virtualenv %VENV%
   c:\> c:\Python35\Scripts\python -m venv %VENV%


Upgrade ``pip`` and ``setuptools`` in the virtual environment
@@ -185,8 +184,9 @@

.. note:: If you are using Windows, the ``alchemy`` scaffold may not deal
   gracefully with installation into a location that contains spaces in the
   path. If you experience startup problems, try putting both the virtualenv
   and the project into directories that do not contain spaces in their paths.
   path. If you experience startup problems, try putting both the virtual
   environment and the project into directories that do not contain spaces in
   their paths.


.. _installing_project_in_dev_mode:
@@ -198,7 +198,7 @@
project as a development egg in your workspace using the ``pip install -e .``
command. In order to do so, change directory to the ``tutorial`` directory that
you created in :ref:`sql_making_a_project`, and run the ``pip install -e .``
command using the virtualenv Python interpreter.
command using the virtual environment Python interpreter.

On UNIX
^^^^^^^
@@ -302,8 +302,8 @@
"coverage" information, exposing which lines of your project are covered by the
tests.

We've already installed the ``pytest-cov`` package into our ``virtualenv``, so
we can run the tests with coverage.
We've already installed the ``pytest-cov`` package into our virtual
environment, so we can run the tests with coverage.

On UNIX
^^^^^^^