Add a new tutorial on installing packages

source/new-tutorials/index.rst

@@ -3,6 +3,11 @@
 New Tutorials
 =============
 
+.. toctree::
+   :maxdepth: 1
+
+   installing/index
+
 .. 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!

source/new-tutorials/installing/index.rst

@@ -0,0 +1,19 @@
+:orphan:
+
+Installing and using Python packages
+====================================
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   installing-packaging-tools
+   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 the Python packging
+ecosystem is a varied one so this isn't the only way to install and use
+Python packages, however, it does cover the most common use cases.
+
+Continue on to :doc:`installing-packaging-tools`.

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

@@ -0,0 +1,141 @@
+Installing and using packages
+=============================
+
+This tutorial will show you how to install a Python package and use it. Before
+you read this tutorial make sure you have all the packaging tools by reading
+:doc:`installing-packaging-tools`.
+
+Creating a virtualenv
+---------------------
+
+As mentioned in the previous tutorial, :ref:`virtualenv` allows you to manage
+separate package installations for different projects. It essentially allows
+you to create a "virtual" isolated Python installation and install packages
+into that virtual installation. When you switch projects, you can simply
+create a new virtual environment and not have to worry about breaking the
+packages installed in the other environments. It is always recommended to use
+a virtualenv while developing Python applications.
+
+To create a virtual environment, go to your project's directory (you can
+just create an empty directory somewhere for this tutorial) and run
+virtualenv:
+
+.. code-block:: bash 
+
+    virtualenv env
+
+.. Note:: If you have Python 2 and 3 installed, you will probably need to
+    specify the Python version you want using
+    ``virtualenv --python python3 env``.
+
+The second argument is the location to create the virtualenv. Generally, you
+can just create this in your project and call it ``env``.
+
+.. Note:: You should exclude your virtualenv directory from your version
+    control system using ``.gitignore`` or similar.
+
+virtualenv will create a virtual Python installation in the ``env`` folder.
+
+
+Activating a virtualenv
+-----------------------
+
+Before you can start installing or using packages in your virtualenv you'll
+need to *activate* it. 
+
+On macOS and Linux:
+
+.. code-block:: bash
+
+    source env/bin/activate
+
+On Windows::
+
+    .\env\Scripts\activate
+
+You can confirm you're in the virtualenv by checking the location of your
+Python interpreter, it should point to the ``env`` directory.
+
+On macOS and Linux:
+
+.. code-block:: bash
+
+    which python
+    .../env/bin/python
+
+On Windows:
+
+.. code-block:: bash
+
+    where python
+    .../env/bin/python.exe
+
+
+Installing packages
+-------------------
+
+Now that you're in your virtualenv you can install packages. Let's install
+the excellent `Requests`_ library from the :term:`Python Package Index (PyPI)`:
+
+.. code-block:: bash
+
+    pip install requests
+
+pip should download requests and all of its dependencies and install them:
+
+.. code-block:: text
+
+    Collecting requests
+      Using cached requests-2.18.4-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 urllib3<1.23,>=1.21.1 (from requests)
+      Using cached urllib3-1.22-py2.py3-none-any.whl
+    Collecting certifi>=2017.4.17 (from requests)
+      Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
+    Collecting idna<2.7,>=2.5 (from requests)
+      Using cached idna-2.6-py2.py3-none-any.whl
+    Installing collected packages: chardet, urllib3, certifi, idna, requests
+    Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22
+
+.. _Requests: http://docs.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 {}'.format(response.text))
+
+As long as you're in your virtualenv you'll be able to import and use your
+installed packages.
+
+
+Leaving the virtualenv
+----------------------
+
+If you want to switch projects or otherwise leave your virtualenv, simply run:
+
+.. code-block:: bash
+
+    deactivate
+
+If you want to re-enter the virtualenv just follow the same instructions above
+about activating a virtualenv. There's no need to re-create the virtualenv.
+
+
+Next steps
+----------
+
+You now know how to install and use Python packages! :) However, there is
+still some other useful things to learn that can be helpful.
+
+.. TODO:: Link to tutorials on using requirements.txt, guides on using different install sources and methods, etc.

source/new-tutorials/installing/installing-packaging-tools.rst

@@ -0,0 +1,104 @@
+Installing packaging tools
+==========================
+
+This tutorial will show you how to install the Python package manager and
+associated tools.
+
+Make sure you've got Python
+---------------------------
+
+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.1``. 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:: This guide is written for Python 3, however, these instructions
+    should work fine on Python 2. If there are any caveats for Python 2 this
+    guide will call it out with a note just like this one.
+
+.. _python.org: https://python.org
+.. _Installing Python: http://docs.python-guide.org/en/latest/starting/installation/
+
+
+Installing pip
+--------------
+
+:ref:`pip` is the the Python package manager. It's used to install and update
+packages. You'll need to make sure you have the latest version of pip
+installed.
+
+
+Windows
++++++++
+
+The Python installers for Windows include pip. If you setup Python to be in
+your ``PATH`` you should have access to pip already:
+
+.. code-block:: bash
+
+    pip version
+    pip 9.0.1 from  c:\python36\lib\site-packages (Python 3.6.1)
+
+.. Note:: If Python and pip aren't in your PATH, If you you'll need to add
+    Python's installation directory as well as the Scripts folder to your path,
+    for example: ``C:\Python36\;C:\Python36\Scripts\``.
+
+You should make sure that pip is up-to-date by running:
+
+.. code-block:: bash
+
+    pip install --upgrade pip
+
+
+Linux and macOS
+++++++++++++++++
+
+While Debian and most other distributions include a `python-pip`_ package, it's
+recommended that you install pip yourself to get the latest version. This
+also applies to Python on OS X (both system and Homebrew Python):
+
+.. code-block:: bash
+
+    wget https://bootstrap.pypa.io/get-pip.py
+    sudo python get-pip.py
+
+.. _python-pip: https://packages.debian.org/stable/python-pip
+
+Afterwards, you should have pip:
+
+.. code-block:: bash
+
+    pip --version
+    pip 9.0.1 from /usr/local/lib/python2.7/dist-packages (python 2.7)
+
+
+Installing virtualenv
+---------------------
+
+:ref:`virtualenv` is used to manage Python packages for different projects.
+Using virtualenv allows you to avoid installing Python packages globally
+which could break system tools or other projects.
+
+Since you now have pip, you can install virtualenv by running:
+
+.. code-block:: bash
+
+    pip install --upgrade virtualenv
+
+.. Note:: If you're on Linux or macOS, you may need to run this with ``sudo``.
+    In general, you should avoid invoking pip with ``sudo`` as this installs
+    packages globally. However, virtualenv and pip are core utilities that
+    make sense to be installed globally.
+
+
+Next step
+---------
+
+Now that you've got the tools installed, continue on to
+:doc:`installing-and-using-packages`.