From eab66f3e3f5c6ddbe88c5e632d78263a5c3d7cd4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 16 Sep 2012 14:36:44 -0400 Subject: update docs to recommend 2.7, add distribute-related instructions for python 3, add windows instructions for python 3, closes #653 --- docs/narr/install.rst | 213 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 156 insertions(+), 57 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 172cfd6d3..e8482a289 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -14,13 +14,13 @@ run :app:`Pyramid`. .. 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 @@ system's package manager is slightly different, but the "flavor" of 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 @@ On Mac OS X, installing `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 @@ using the following commands: [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 You Don't Yet Have A Python Interpreter (Windows) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 `_ (the files labeled "Windows Installer"). Once you've downloaded it, double click on the @@ -119,7 +119,7 @@ extensions `_. .. 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 @@ done by using the :term:`virtualenv` package. Using a virtualenv will 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. - -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. - -To install setuptools by hand, first download `ez_setup.py -`_ then invoke it -using the Python interpreter into which you want to install -setuptools. +Here's the output you can expect if setuptools or distribute is not already +installed: + +.. code-block:: text + + [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 "", line 1, in + 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 +`_ then invoke it using the +Python interpreter into which you want to install setuptools. .. code-block:: text @@ -188,16 +211,37 @@ the script. To remediate this, you may need to do: $ 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 +`_ 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,90 @@ complete, as it downloads and installs a number of dependencies. Installing :app:`Pyramid` on a Windows System ------------------------------------------------- -#. Install, or find `Python 2.6 - `_ 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 + `_ for your system. #. Install the `Python for Windows extensions `_. 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 `_ 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:\Python27\Scripts\easy_install virtualenv + +#. Use that Python's virtualenv to make a workspace: + + .. code-block:: text + + c:\> c:\Python27\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 + + c:\env> Scripts\easy_install pyramid + +Windows Using Python 3 +~~~~~~~~~~~~~~~~~~~~~~ + +#. Install, or find `Python 3.2 + `_ for your system. + +#. Install the `Python for Windows extensions + `_. 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 + `_ 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:\Python26\Scripts\easy_install virtualenv + c:\> c:\Python32\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:\Python32\Scripts\virtualenv --no-site-packages env #. Switch to the ``env`` directory: @@ -308,8 +407,8 @@ Installing :app:`Pyramid` on a Windows System #. (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 -- cgit v1.2.3