Add a new tutorial on installing packages using pipenv (pypa#369)

Author: Jon Wayne Parrott

source/conf.py

@@ -32,6 +32,7 @@
 # ones.
 extensions = [
     'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -355,3 +356,9 @@
     'pip': ('https://pip.pypa.io/en/latest/', None),
     'pypa': ('https://pypa.io/en/latest/', None),
 }
+
+
+# f this is True, todo and todolist produce output, else they produce nothing.
+# The default is False.
+
+todo_include_todos = True

source/key_projects.rst

@@ -76,6 +76,17 @@ Dev irc:#pypa-dev
 
 A tool for installing Python packages.
 
+.. _Pipfile:
+
+Pipfile
+=======
+
+`Source <https://github.com/pypa/pipfile>`__
+
+``Pipfile`` and its sister ``Pipfile.lock`` are a higher-level
+application-centric alternative to :ref:`pip`'s lower-level
+``requirements.txt`` file.
+
 
 Python Packaging User Guide
 ===========================
@@ -158,8 +169,8 @@ Warehouse
 Dev irc:#pypa-dev
 
 
-The current codebase powering :term:`PyPI`. It is hosted at
-`pypi.org <https://pypi.org/>`_.
+The current codebase powering the :term:`Python Package Index (PyPI)`. It is
+hosted at `pypi.org <https://pypi.org/>`_.
 
 
 .. _wheel:
@@ -310,6 +321,22 @@ files, standalone Python environments in the spirit of :ref:`virtualenv`.
 ``#!/usr/bin/env python`` and special ``__main__.py``, and are designed to make
 deployment of Python applications as simple as ``cp``.
 
+
+.. _Pipenv:
+
+Pipenv
+======
+
+`Docs <http://docs.pipenv.org/en/latest/>`__ |
+`Source <https://github.com/kennethreitz/pipenv>`__ |
+`Issues <https://github.com/kennethreitz/pipenv/issues>`__ |
+`PyPI <https://pypi.python.org/pypi/pipenv>`__
+
+Pipenv is a project that aims to bring the best of all packaging worlds to the
+Python world. It harnesses :ref:`Pipfile`, :ref:`pip`, and :ref:`virtualenv`
+into one single toolchain. It features very pretty terminal colors.
+
+
 .. _spack:
 
 Spack

source/new-tutorials/index.rst

@@ -6,3 +6,8 @@ New Tutorials
 .. warning:: This section is for work-in-progress tutorials! These will
     eventually be promoted to the :doc:`/tutorials/index` section.
     Do not link to these pages!
+
+.. toctree::
+   :maxdepth: 1
+
+   installing-and-using-packages

source/new-tutorials/installing-and-using-packages.rst

@@ -0,0 +1,194 @@
+Installing and using packages
+=============================
+
+This tutorial walks you through installing and using Python packages. It will
+show you how to install and use the necessary tools and make strong
+recommendations on best practices. Keep in mind that Python is used for a great
+many different purposes, and precisely how you want to manage your dependencies
+may change based on how you decide to publish your software. The guidance
+presented here is most directly applicable to the development and deployment of
+network services (including web applications), but is also very well suited to
+managing development and testing environments for any kind of project.
+
+.. Note:: This guide is written for Python 3, however, these instructions
+    should work fine on Python 2.7.
+
+
+Make sure you've got Python & pip
+---------------------------------
+
+Before you go any further, make sure you have Python and that it's avalable
+from your command line. You can check this by simply running:
+
+.. code-block:: bash
+
+    python --version
+
+You should get some output like ``3.6.2``. If you do not have Python, please
+install the latest 3.x version from `python.org`_ or refer to the
+`Installing Python`_ section of the Hitchhiker's Guide to Python.
+
+.. Note:: If you're a newcomer and you get an error like this:
+    
+    .. code-block:: python
+
+        >>> python
+        Traceback (most recent call last):
+          File "<stdin>", line 1, in <module>
+        NameError: name 'python' is not defined
+
+    It's because this command and other suggested commands in this tutorial
+    are intended to be run in a *shell* (also called a *terminal* or
+    *console*). See the Python for Beginners `getting started tutorial`_ for
+    an introduction to using your operating system's shell and interacting with
+    Python.
+
+Additionally, you'll need to make sure you have :ref:`pip` available. You can
+check this by running:
+
+.. code-block:: bash
+
+    pip --version
+
+If you installed Python from source, with an installer from `python.org`_, or
+via `Homebrew`_ you should already have pip. If you're on Linux and installed
+using your OS package manager, you may have to install pip separately, see
+:doc:`/guides/installing-using-linux-tools`.
+
+.. _getting started tutorial: https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly
+.. _python.org: https://python.org
+.. _Homebrew: https://brew.sh
+.. _Installing Python: http://docs.python-guide.org/en/latest/starting/installation/
+
+
+Installing Pipenv
+-----------------
+
+:ref:`Pipenv` is a dependency manager for Python projects. If you're familiar
+with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit to those
+tools. While :ref:`pip` can install Python packages, Pipenv is recommended as
+it's a higher-level tool that simplifies dependency management for common use
+cases.
+
+Use ``pip`` to install Pipenv:
+
+.. code-block:: python
+
+    pip install --user pipenv
+
+
+.. Note:: This does a `user installation`_ to prevent breaking any system-wide
+    packages. If ``pipenv`` isn't available in your shell after installation,
+    you'll need to add the `user base`_'s ``bin`` directory to your ``PATH``.
+    You can find the user base by running ``python -m site`` which will print
+    site information including the user base. For example, on Linux this will
+    return ``USER_BASE: '~/.local'`` so you'll need to add ``~/.local/bin`` to
+    your ``PATH``. On Linux and macOS you can set your ``PATH`` permanently
+    by `modifying ~/.profile`_. On Windows you can set the user
+    ``PATH`` permanently in the `Control Panel`_.
+
+.. _npm: https://www.npmjs.com/
+.. _bundler: http://bundler.io/
+.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
+.. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
+.. _modifying ~/.profile: https://stackoverflow.com/a/14638025
+.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx
+
+Installing packages for your project
+------------------------------------
+
+Pipenv manages dependencies on a per-project basis. To install packages,
+change into your project's directory (or just an empty directory for this
+tutorial) and run:
+
+.. code-block:: bash
+
+    cd myproject
+    pipenv install requests
+
+Pipenv will install the excellent `Requests`_ library and create a ``Pipfile``
+for you in your project's directory. The :ref:`Pipfile` is used to track which
+dependencies your project needs in case you need to re-install them, such as
+when you share your project with others. You should get output similar to this
+(although the exact paths shown will vary):
+
+.. code-block:: text
+
+    Creating a Pipfile for this project...
+    Creating a virtualenv for this project...
+    Using base prefix '/usr/local/Cellar/python3/3.6.2/Frameworks/Python.framework/Versions/3.6'
+    New python executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python3.6
+    Also creating executable in ~/.local/share/virtualenvs/tmp-agwWamBd/bin/python
+    Installing setuptools, pip, wheel...done.
+
+    Virtualenv location: ~/.local/share/virtualenvs/tmp-agwWamBd
+    Installing requests...
+    Collecting requests
+      Using cached requests-2.18.4-py2.py3-none-any.whl
+    Collecting idna<2.7,>=2.5 (from requests)
+      Using cached idna-2.6-py2.py3-none-any.whl
+    Collecting urllib3<1.23,>=1.21.1 (from requests)
+      Using cached urllib3-1.22-py2.py3-none-any.whl
+    Collecting chardet<3.1.0,>=3.0.2 (from requests)
+      Using cached chardet-3.0.4-py2.py3-none-any.whl
+    Collecting certifi>=2017.4.17 (from requests)
+      Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
+    Installing collected packages: idna, urllib3, chardet, certifi, requests
+    Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22
+
+    Adding requests to Pipfile's [packages]...
+    P.S. You have excellent taste! ✨ 🍰 ✨
+
+.. _Requests: https://python-requests.org
+
+
+Using installed packages
+------------------------
+
+Now that Requests is installed you can create a simple ``main.py`` file to
+use it:
+
+.. code-block:: python
+
+    import requests
+
+    response = requests.get('https://httpbin.org/ip')
+
+    print('Your IP is {0}'.format(response.json['origin']))
+
+Then you can run this script using ``pipenv run``:
+
+.. code-block:: bash
+
+    pipenv run python main.py
+
+You should get output similar to this:
+
+.. code-block:: text
+
+    Your IP is 8.8.8.8
+
+Using ``pipenv run`` ensures that your installed packages are available to
+your script. It's also possible to spawn a new shell that ensures all commands
+have access to your installed packages with ``pipenv shell``.
+
+
+Next steps
+----------
+
+Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨
+
+There's more resources you can look at to learn about installing and using
+Python packages:
+
+.. TODO:: Link to additional guides and resources.
+
+If you find this approach isn't working well for you or your use case, you may
+want to explore these other approaches:
+
+.. TODO:: Link to alternatives
+
+If you're interesting in creating and distributing Python packages, see the
+tutorial on packaging and distributing packages.
+
+.. TODO:: Link to packaging tutorial when it exists.