update docs to recommend 2.7, add distribute-related instructions for pytho...

Chris McDonough

2012-09-16 eab66f3e3f5c6ddbe88c5e632d78263a5c3d7cd4

update docs to recommend 2.7, add distribute-related instructions for python 3, add windows instructions for python 3, closes #653

 docs/glossary.rst

@@ -41,14 +41,20 @@
   setuptools
     `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
     builds on Python's ``distutils`` to provide easier building,
     distribution, and installation of libraries and applications.
     distribution, and installation of libraries and applications.  As of
     this writing, setuptools runs under Python 2, but not under Python 3.
     You can use :term:`distribute` under Python 3 instead.

   distribute
     `Distribute <http://packages.python.org/distribute/>`_ is a fork of
     :term:`setuptools` which runs on both Python 2 and Python 3.

   pkg_resources
     A module which ships with :term:`setuptools` that provides an API for
     addressing "asset files" within a Python :term:`package`.  Asset files
     are static files, template files, etc; basically anything
     non-Python-source that lives in a Python package can be considered a
     asset file.  See also `PkgResources
     A module which ships with :term:`setuptools` and :term:`distribute` that
     provides an API for addressing "asset files" within a Python
     :term:`package`.  Asset files are static files, template files, etc;
     basically anything non-Python-source that lives in a Python package can
     be considered a asset file.  See also `PkgResources
     <http://peak.telecommunity.com/DevCenter/PkgResources>`_

   asset
@@ -84,7 +90,7 @@
     (Setuptools/distutils terminology).  A file representing an
     installable library or application.  Distributions are usually
     files that have the suffix of ``.egg``, ``.tar.gz``, or ``.zip``.
     Distributions are the target of Setuptools commands such as
     Distributions are the target of Setuptools-related commands such as
     ``easy_install``.

   entry point

 docs/narr/install.rst

@@ -14,13 +14,13 @@

.. sidebar:: Python Versions

    As of this writing, :app:`Pyramid` has been tested under Python 2.6.6,
    Python 2.7.2, and Python 3.2.  :app:`Pyramid` does not run under any
    version of Python before 2.6.
    As of this writing, :app:`Pyramid` has been tested under Python 2.6.8,
    Python 2.7.3, Python 3.2.3, and Python 3.3b1.  :app:`Pyramid` does not
    run under any version of Python before 2.6.

:app:`Pyramid` is known to run on all popular UNIX-like systems such as
Linux, MacOS X, and FreeBSD as well as on Windows platforms.  It is also
known to run on :term:`PyPy` (1.6+).
known to run on :term:`PyPy` (1.9+).

:app:`Pyramid` installation does not require the compilation of any
C code, so you need only a Python interpreter that meets the
@@ -45,15 +45,15 @@
them is usually the same.

For example, on an Ubuntu Linux system, to use the system package
manager to install a Python 2.6 interpreter, use the following
manager to install a Python 2.7 interpreter, use the following
command:

.. code-block:: text

   $ sudo apt-get install python2.6-dev
   $ sudo apt-get install python2.7-dev

Once these steps are performed, the Python interpreter will usually be
invokable via ``python2.6`` from a shell prompt.
invokable via ``python2.7`` from a shell prompt.

.. index::
   pair: install; Python (from source, UNIX)
@@ -80,7 +80,7 @@
<http://developer.apple.com/tools/xcode/>`_ has much the same effect.

Once you've got development tools installed on your system, you can
install a Python 2.6 interpreter from *source*, on the same system,
install a Python 2.7 interpreter from *source*, on the same system,
using the following commands:

.. code-block:: text
@@ -90,15 +90,15 @@
   [chrism@vitaminf ~]$ mkdir opt
   [chrism@vitaminf ~]$ cd tmp
   [chrism@vitaminf tmp]$ wget \
          http://www.python.org/ftp/python/2.6.4/Python-2.6.4.tgz
   [chrism@vitaminf tmp]$ tar xvzf Python-2.6.4.tgz
   [chrism@vitaminf tmp]$ cd Python-2.6.4
   [chrism@vitaminf Python-2.6.4]$ ./configure \
           --prefix=$HOME/opt/Python-2.6.4
   [chrism@vitaminf Python-2.6.4]$ make; make install
          http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz
   [chrism@vitaminf tmp]$ tar xvzf Python-2.7.3.tgz
   [chrism@vitaminf tmp]$ cd Python-2.7.3
   [chrism@vitaminf Python-2.7.3]$ ./configure \
           --prefix=$HOME/opt/Python-2.7.3
   [chrism@vitaminf Python-2.7.3]$ make; make install

Once these steps are performed, the Python interpreter will be
invokable via ``$HOME/opt/Python-2.6.4/bin/python`` from a shell
invokable via ``$HOME/opt/Python-2.7.3/bin/python`` from a shell
prompt.

.. index::
@@ -108,7 +108,7 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your Windows system doesn't have a Python interpreter, you'll need
to install it by downloading a Python 2.6-series interpreter
to install it by downloading a Python 2.7-series interpreter
executable from `python.org's download section
<http://python.org/download/>`_ (the files labeled "Windows
Installer").  Once you've downloaded it, double click on the
@@ -119,7 +119,7 @@
.. warning::

   After you install Python on Windows, you may need to add the
   ``C:\Python26`` directory to your environment's ``Path`` in order
   ``C:\Python27`` directory to your environment's ``Path`` in order
   to make it possible to invoke Python from a command prompt by
   typing ``python``.  To do so, right click ``My Computer``, select
   ``Properties`` --> ``Advanced Tab`` --> ``Environment Variables``
@@ -141,39 +141,62 @@
also prevent :app:`Pyramid` from globally installing versions of
packages that are not compatible with your system Python.

To set up a virtualenv in which to install :app:`Pyramid`, first
ensure that :term:`setuptools` is installed.  Invoke ``import
setuptools`` within the Python interpreter you'd like to run
:app:`Pyramid` under:
To set up a virtualenv in which to install :app:`Pyramid`, first ensure that
:term:`setuptools` or :term:`distribute` is installed.  To do so, invoke
``import setuptools`` within the Python interpreter you'd like to run
:app:`Pyramid` under.

Here's the output you'll expect if setuptools or distribute is already
installed:

.. code-block:: text

   [chrism@vitaminf pyramid]$ python
   Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) 
   [GCC 4.4.3] on linux2
   [chrism@thinko docs]$ python2.7
   Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
   [GCC 4.6.3] on linux2
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import setuptools
   >>> 

If running ``import setuptools`` does not raise an ``ImportError``, it
means that setuptools is already installed into your Python
interpreter.  If ``import setuptools`` fails, you will need to install
setuptools manually.  Note that above we're using a Python 2.6-series
interpreter on Mac OS X; your output may differ if you're using a
later Python version or a different platform.
Here's the output you can expect if setuptools or distribute is not already
installed:

If you are using a "system" Python (one installed by your OS
distributor or a 3rd-party packager such as Fink or MacPorts), you can
usually install the setuptools package by using your system's package
manager.  If you cannot do this, or if you're using a self-installed
version of Python, you will need to install setuptools "by hand".
Installing setuptools "by hand" is always a reasonable thing to do,
even if your package manager already has a pre-chewed version of
setuptools for installation.
.. code-block:: text

To install setuptools by hand, first download `ez_setup.py
<http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it
using the Python interpreter into which you want to install
setuptools.
   [chrism@thinko docs]$ python2.7
   Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
   [GCC 4.6.3] on linux2
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import setutptools
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ImportError: No module named setutptools
   >>>

If ``import setuptools`` raises an :exc:`ImportError` as it does above, you
will need to install setuptools or distribute manually.  Note that above
we're using a Python 2.7-series interpreter on Mac OS X; your output may
differ if you're using a later Python version or a different platform.

If you are using a "system" Python (one installed by your OS distributor or a
3rd-party packager such as Fink or MacPorts), you can usually install the
setuptools or distribute package by using your system's package manager.  If
you cannot do this, or if you're using a self-installed version of Python,
you will need to install setuptools or distribute "by hand".  Installing
setuptools or distribute "by hand" is always a reasonable thing to do, even
if your package manager already has a pre-chewed version of setuptools for
installation.

If you're using Python 2, you'll want to install ``setuptools``.  If you're
using Python 3, you'll want to install ``distribute``.  Below we tell you how
to do both.

Installing Setuptools On Python 2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To install setuptools by hand under Python 2, first download `ez_setup.py
<http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it using the
Python interpreter into which you want to install setuptools.

.. code-block:: text

@@ -188,16 +211,37 @@

   $ sudo python ez_setup.py

Installing Distribute On Python 3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``setuptools`` doesn't work under Python 3.  Instead, you can use
``distribute``, which is a fork of setuptools that does work on Python 3.  To
install it, first download `distribute_setup.py
<http://python-distribute.org/distribute_setup.py>`_ then invoke it using the
Python interpreter into which you want to install setuptools.

.. code-block:: text

   $ python3 distribute_setup.py

Once this command is invoked, distribute should be installed on your system.
If the command fails due to permission errors, you may need to be the
administrative user on your system to successfully invoke the script.  To
remediate this, you may need to do:

.. code-block:: text

   $ sudo python3 distribute_setup.py

.. index::
   pair: install; virtualenv

Installing the ``virtualenv`` Package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once you've got setuptools installed, you should install the
:term:`virtualenv` package.  To install the :term:`virtualenv` package
into your setuptools-enabled Python interpreter, use the
``easy_install`` command.
Once you've got setuptools or distribute installed, you should install the
:term:`virtualenv` package.  To install the :term:`virtualenv` package into
your setuptools-enabled Python interpreter, use the ``easy_install`` command.

.. code-block:: text

@@ -269,35 +313,41 @@
Installing :app:`Pyramid` on a Windows System
-------------------------------------------------

#. Install, or find `Python 2.6
   <http://python.org/download/releases/2.6.4/>`_ for your system.
You can use Pyramid on Windows under Python 2 or under Python 3.  Directions
for both versions are included below.

Windows Using Python 2
~~~~~~~~~~~~~~~~~~~~~~

#. Install, or find `Python 2.7
   <http://www.python.org/download/releases/2.7.3/>`_ for your system.

#. Install the `Python for Windows extensions
   <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
   pick the right download for Python 2.6 and install it using the
   pick the right download for Python 2.7 and install it using the
   same Python installation from the previous step.

#. Install latest :term:`setuptools` distribution into the Python you
   obtained/installed/found in the step above: download `ez_setup.py
   <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
   the ``python`` interpreter of your Python 2.6 installation using a
   the ``python`` interpreter of your Python 2.7 installation using a
   command prompt:

   .. code-block:: text

      c:\> c:\Python26\python ez_setup.py
      c:\> c:\Python27\python ez_setup.py

#. Use that Python's `bin/easy_install` to install `virtualenv`:

   .. code-block:: text

      c:\> c:\Python26\Scripts\easy_install virtualenv
      c:\> c:\Python27\Scripts\easy_install virtualenv

#. Use that Python's virtualenv to make a workspace:

   .. code-block:: text

      c:\> c:\Python26\Scripts\virtualenv --no-site-packages env
      c:\> c:\Python27\Scripts\virtualenv --no-site-packages env

#. Switch to the ``env`` directory:

@@ -308,8 +358,57 @@
#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell
   environment wired to use the virtualenv.

#. Use ``easy_install`` pointed at the "current" index to get
   :app:`Pyramid` and its direct dependencies installed:
#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
   installed:

   .. code-block:: text

      c:\env> Scripts\easy_install pyramid

Windows Using Python 3
~~~~~~~~~~~~~~~~~~~~~~

#. Install, or find `Python 3.2
   <http://www.python.org/download/releases/3.2.3/>`_ for your system.

#. Install the `Python for Windows extensions
   <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
   pick the right download for Python 3.2 and install it using the
   same Python installation from the previous step.

#. Install latest :term:`distribute` distribution into the Python you
   obtained/installed/found in the step above: download `distribute_setup.py
   <http://python-distribute.org/distribute_setup.py>`_ and run it using the
   ``python`` interpreter of your Python 3.2 installation using a command
   prompt:

   .. code-block:: text

      c:\> c:\Python32\python distribute_setup.py

#. Use that Python's `bin/easy_install` to install `virtualenv`:

   .. code-block:: text

      c:\> c:\Python32\Scripts\easy_install virtualenv

#. Use that Python's virtualenv to make a workspace:

   .. code-block:: text

      c:\> c:\Python32\Scripts\virtualenv --no-site-packages env

#. Switch to the ``env`` directory:

   .. code-block:: text

      c:\> cd env

#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell
   environment wired to use the virtualenv.

#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
   installed:

   .. code-block:: text