update virtual environment instructions

docs/contents.rst.inc

@@ -22,7 +22,7 @@ New to Python? Let's properly setup up your Python environment:
     starting/install/linux
 
 
-- Using Virtualenvs with Pipenv:
+- Package Installation and Project Isolation:
 
  .. toctree::
     :maxdepth: 2

docs/dev/pip-virtualenv.rst

@@ -1,6 +1,6 @@
 .. _pip-virtualenv:
 
-Further Configuration of pip and Virtualenv
+Further Configuration of pip and virtual environments
 ===========================================
 
 .. image:: /_static/photos/34018732105_f0e6758859_k_d.jpg

docs/dev/virtualenvs.rst

@@ -1,7 +1,7 @@
 .. _virtualenvironments-ref:
 
-Pipenv & Virtual Environments
-=============================
+Package Installation and Project Isolation
+==========================================
 
 .. image:: /_static/photos/35294660055_42c02b2316_k_d.jpg
 
@@ -65,6 +65,9 @@ using your OS package manager, you may have to `install pip <https://pip.pypa.io
 .. _Installing Python: https://docs.python-guide.org/starting/installation/
 
 
+Pipenv
+======
+
 Installing Pipenv
 -----------------
 
@@ -197,27 +200,17 @@ Congratulations, you now know how to install and use Python packages! ✨ 🍰 
 
 
 
-Lower level: virtualenv
-=======================
+Project Isolation with Virtual Environments
+===========================================
 
-`virtualenv <http://pypi.org/project/virtualenv>`_ is a tool to create
-isolated Python environments. virtualenv creates a folder which contains all the
-necessary executables to use the packages that a Python project would need.
+If you choose not to use Pipenv or it does not fit your needs, you can
+use the `venv <https://docs.python.org/3/library/venv.html>`_ tool directly to create
+isolated Python environments. The ``venv`` module is part of Python's standard library,
+and was introduced in Python 3.3. It creates a folder which contains all the necessary
+executables to use the packages that a Python project would need.
 
 It can be used standalone, in place of Pipenv.
 
-Install virtualenv via pip:
-
-.. code-block:: console
-
-  $ pip install virtualenv
-
-Test your installation:
-
-.. code-block:: console
-
-   $ virtualenv --version
-
 Basic Usage
 -----------
 
@@ -226,45 +219,60 @@ Basic Usage
 .. code-block:: console
 
    $ cd project_folder
-   $ virtualenv venv
+   $ python -m venv venv
 
-``virtualenv venv`` will create a folder in the current directory which will
-contain the Python executable files, and a copy of the ``pip`` library which you
+On Windows use this command:
+
+.. code-block:: console
+
+   $ py -m venv venv
+
+``python -m venv venv`` will create a folder in the current directory which will
+contain the Python executable files, and a copy of the ``pip`` application which you
 can use to install other packages. The name of the virtual environment (in this
-case, it was ``venv``) can be anything; omitting the name will place the files
-in the current directory instead.
+case, it was ``venv``) can be anything.
 
 .. note::
     'venv' is the general convention used globally. As it is readily available in ignore files (eg: .gitignore')
 
 This creates a copy of Python in whichever directory you ran the command in,
 placing it in a folder named :file:`venv`.
 
-You can also use the Python interpreter of your choice (like
-``python2.7``).
+You can also use the Python interpreter of your choice, like ``python3.8``. Sometimes ``python`` will still point to a Python 2 interpreter, so you can do this instead to be sure you are using the right Python version.
 
 .. code-block:: console
 
-   $ virtualenv -p /usr/bin/python2.7 venv
+   $ python3.8 -m venv venv
 
-or change the interpreter globally with an env variable in ``~/.bashrc``:
+
+On Windows use this command:
 
 .. code-block:: console
 
-   $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7
+   $ py -3.8 -m venv venv
+
+
+2. To begin using the virtual environment, you can either invoke the virtual environment's executables
+directly, or activate it.
+
+To use the virtual environment's Python executable directly, run
+``venv/bin/python``; to use its pip executable, ``venv/bin/pip``.
 
-2. To begin using the virtual environment, it needs to be activated:
+Alternatively, you can "activate"
+the environment so you can just type ``python`` or ``pip`` and it will automatically use the
+executables in the virtual environment (in this case, at ``venv/bin``).
 
 .. code-block:: console
 
    $ source venv/bin/activate
 
-The name of the current virtual environment will now appear on the left of
+Now, the name of the current virtual environment will appear on the left of
 the prompt (e.g. ``(venv)Your-Computer:project_folder UserName$``) to let you know
 that it's active. From now on, any package that you install using pip will be
 placed in the ``venv`` folder, isolated from the global Python installation.
 
-For Windows, the same command mentioned in step 1 can be used to create a virtual environment. However, activating the environment requires a slightly different command.
+For Windows, the same command mentioned in step 1 can be used to create a virtual environment.
+However, activating the environment requires a slightly different command.
 
 Assuming that you are in your project directory:
 
@@ -286,25 +294,26 @@ Install packages using the ``pip`` command:
     $ deactivate
 
 This puts you back to the system's default Python interpreter with all its
-installed libraries.
+installed libraries. This is not necessary if you invoked the executables directly.
 
 To delete a virtual environment, just delete its folder. (In this case,
 it would be ``rm -rf venv``.)
 
 After a while, though, you might end up with a lot of virtual environments
-littered across your system, and it's possible you'll forget their names or
-where they were placed.
+littered across your system. It's possible you'll forget their names or
+where they were placed, so try to follow a convention across your projects.
 
 .. note::
-    Python has included venv module from version 3.3. For more details: `venv <https://docs.python.org/3/library/venv.html>`_.
+    The ``venv`` module is part of Python's standard library in Python3.3+.
+    Older versions of Python can use the
+    3rd party package `virtualenv <https://pypi.org/project/virtualenv/>`_.
 
 Other Notes
 -----------
 
-Running ``virtualenv`` with the option ``--no-site-packages`` will not
-include the packages that are installed globally. This can be useful
-for keeping the package list clean in case it needs to be accessed later.
-[This is the default behavior for ``virtualenv`` 1.7 and later.]
+Running ``python -m venv`` with the option ``--system-site-packages`` will include
+the packages that are installed globally. Usually you do not want to do this so
+the package list remains clean in case it needs to be accessed later.
 
 In order to keep your environment consistent, it's a good idea to "freeze"
 the current state of the environment packages. To do this, run:
@@ -330,112 +339,43 @@ and across developers.
 Lastly, remember to exclude the virtual environment folder from source
 control by adding it to the ignore list (see :ref:`Version Control Ignores<version_control_ignores>`).
 
-.. _virtualenvwrapper-ref:
-
-virtualenvwrapper
------------------
-
-`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/en/latest/index.html>`_
-provides a set of commands which makes working with virtual environments much
-more pleasant. It also places all your virtual environments in one place.
-
-To install (make sure **virtualenv** is already installed):
-
-.. code-block:: console
-
-  $ pip install virtualenvwrapper
-  $ export WORKON_HOME=~/Envs
-  $ source /usr/local/bin/virtualenvwrapper.sh
-
-(`Full virtualenvwrapper install instructions <https://virtualenvwrapper.readthedocs.io/en/latest/install.html>`_.)
-
-For Windows, you can use the `virtualenvwrapper-win <https://github.com/davidmarble/virtualenvwrapper-win/>`_.
-
-To install (make sure **virtualenv** is already installed):
-
-.. code-block:: console
-
-  $ pip install virtualenvwrapper-win
-
-In Windows, the default path for WORKON_HOME is %USERPROFILE%\\Envs
-
-Basic Usage
-~~~~~~~~~~~
 
-1. Create a virtual environment:
-
-.. code-block:: console
-
-   $ mkvirtualenv project_folder
-
-This creates the :file:`project_folder` folder inside :file:`~/Envs`.
-
-2. Work on a virtual environment:
-
-.. code-block:: console
-
-   $ workon project_folder
-
-Alternatively, you can make a project, which creates the virtual environment,
-and also a project directory inside ``$WORKON_HOME``, which is ``cd``-ed into
-when you ``workon project_folder``.
-
-.. code-block:: console
-
-   $ mkproject project_folder
-
-**virtualenvwrapper** provides tab-completion on environment names. It really
-helps when you have a lot of environments and have trouble remembering their
-names.
-
-``workon`` also deactivates whatever environment you are currently in, so you
-can quickly switch between environments.
-
-3. Deactivating is still the same:
+Other Tools
+-----------
 
-.. code-block:: console
+There are many tools to complement usage of pip and virtual environments. Here are some useful ones we like.
 
-   $ deactivate
+direnv
+~~~~~~
+When you ``cd`` into a directory containing a :file:`.env`, `direnv <https://direnv.net>`_
+automagically activates the environment.
 
-4. To delete:
+Install it on Mac OS X using ``brew``:
 
 .. code-block:: console
 
-   $ rmvirtualenv venv
-
-Other useful commands
-~~~~~~~~~~~~~~~~~~~~~
-
-``lsvirtualenv``
-  List all of the environments.
-
-``cdvirtualenv``
-  Navigate into the directory of the currently activated virtual environment,
-  so you can browse its :file:`site-packages`, for example.
-
-``cdsitepackages``
-  Like the above, but directly into :file:`site-packages` directory.
+   $ brew install direnv
 
-``lssitepackages``
-  Shows contents of :file:`site-packages` directory.
+On Linux follow the instructions at `direnv.net <https://direnv.net>`_
 
-`Full list of virtualenvwrapper commands <https://virtualenvwrapper.readthedocs.io/en/latest/command_ref.html>`_.
+pip-tools
+~~~~~~~~~
+`pip-tools <https://github.com/jazzband/pip-tools>`_ is a suite of two tools that complement pip and virtual environments. It has similar functionaly to pipenv, and in fact pipenv uses pip-tools in its implementation. However, compared to pipenv, pip-tools lets you have a little more control over how and when operations are performed.
 
-virtualenv-burrito
-------------------
+It does two things:
+1.) Generate a complete dependency list (lockfile, or ``requirements.txt`` file) from abstract dependencies. It does this with a full dependency resolver, which pip does not currently have, and can optionally generate the lockfile with hashes.
+2.) Synchronize a virtual environment to exactly match a requirements lockfile.
 
-With `virtualenv-burrito <https://github.com/brainsik/virtualenv-burrito>`_, you
-can have a working virtualenv + virtualenvwrapper environment in a single command.
+pipx
+~~~~
+`pipx <https://github.com/pipxproject/pipx>`_ is a tool to install system-wide command line tools, each to their own individual environment. Unlike ``pip`` which installs all packages to the same environment, ``pipx`` isolates tools in their own virtual environment, and exposes the command-line tools to your shell. ``pipx`` is used for installing command-line tools, similar to ``brew`` or ``apt``, but for Python applications. It's not used to install libraries.
 
-direnv
--------
-When you ``cd`` into a directory containing a :file:`.env`, `direnv <https://direnv.net>`_
-automagically activates the environment.
 
-Install it on Mac OS X using ``brew``:
+tox and nox
+~~~~~~~~~~~
 
-.. code-block:: console
+`tox <https://tox.readthedocs.io/en/latest/>`_ and  `nox <https://nox.thea.codes/en/stable/>`_ are widely used command-line tools that automate environment setup and task execution. tox and nox are often used to run tests across multiple Python versions, among other things. They do this by reading a configuration file, either ``tox.ini`` for tox, or ``noxfile.py`` for nox.
 
-   $ brew install direnv
+For example, if you have unit tests that you want to run with Python 3.6, 3.7, and 3.8, you can use one of these tools. It will create three virtual environments, one for each Python version, then install necessary dependencies, and finally run tests in each environment. You can also run specific tasks like running a lint check, or publishing a new version of your package.
 
-On Linux follow the instructions at `direnv.net <https://direnv.net>`
+The main difference between the two tools are ``tox`` uses a custom file format for configuration, while ``nox`` uses a standard Python file for configuration.