Let's get our tutorial environment setup. Most of the setup work is in standard Python development practices (install Python, make an isolated environment, and setup packaging tools.)
Pyramid encourages standard Python development practices with packaging tools, virtual environments, logging, and so on. There are many variations, implementations, and opinions across the Python community. For consistency, ease of documentation maintenance, and to minimize confusion, the Pyramid documentation has adopted specific conventions.
This Quick Tutorial is based on:
Pyramid was one of the first web frameworks to fully support Python 3 in October 2011.
Download the latest standard Python 3.3+ release (not development release) from python.org. On that page, you must click the latest version, then scroll down to the "Downloads" section for your operating system.
Windows and Mac OS X users can download and run an installer.
Windows users should also install the Python for Windows extensions. Carefully read the README.txt file at the end of the list of builds, and follow its directions. Make sure you get the proper 32- or 64-bit build and Python version.
Linux users can either use their package manager to install Python 3.3 or may build Python 3.3 from source.
We will arrive at a directory structure of workspace->project->package, with our workspace named quick_tutorial. The following diagram shows how this is structured and where our virtual environment will reside:
For Linux, the commands to do so are as follows:
# Mac and Linux $ cd ~ $ mkdir -p projects/quick_tutorial $ cd projects/quick_tutorial
# Windows c:\> cd \ c:\> mkdir projects\quick_tutorial c:\> cd projects\quick_tutorial
In the above figure, your user home directory is represented by ~. In your home directory, all of your projects are in the projects directory. This is a general convention not specific to Pyramid that many developers use. Windows users will do well to use c:\ as the location for projects in order to avoid spaces in any of the path names.
Next within projects is your workspace directory, here named quick_tutorial. A workspace is a common term used by integrated development environments (IDE) like PyCharm and PyDev that stores isolated Python environments (virtualenvs) and specific project files and repositories.
This tutorial will refer frequently to the location of the virtual environment. We set an environment variable to save typing later.
# Mac and Linux $ export VENV=~/projects/quick_tutorial/env33/ # Windows # TODO: This command does not work c:\> set VENV=c:\projects\quick_tutorial\env33
The current state of isolated Python environments using pyvenv on Windows is suboptimal in comparison to Mac and Linux. See http://stackoverflow.com/q/15981111/95735 for a discussion of the issue and PEP 453 for a proposed resolution.
pyvenv is a tool to create isolated Python 3.3 environments, each with its own Python binary and independent set of installed Python packages in its site directories. Let's create one, using the location we just specified in the environment variable.
# Mac and Linux $ pyvenv $VENV # Windows c:\> c:\Python33\python -m venv %VENV%
The following command will download a script to install setuptools, then pipe it to your environment's version of Python.
# Mac and Linux $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python # Windows # Use your browser to download: # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.p # ...into c:\projects\quick_tutorial\ez_setup.py c:\> %VENV%\Scripts\python ez_setup.py
If wget complains with a certificate error, then run this command instead:
# Mac and Linux $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python
We have our Python standard prerequisites out of the way. The Pyramid part is pretty easy:
# Mac and Linux $ $VENV/bin/easy_install "pyramid==1.5.1" # Windows c:\> %VENV%\Scripts\easy_install "pyramid==1.5.1"
Our Python virtual environment now has the Pyramid software available.
You can optionally install some of the extra Python packages used during this tutorial:
# Mac and Linux $ $VENV/bin/easy_install nose webtest deform sqlalchemy \ pyramid_chameleon pyramid_debugtoolbar waitress \ pyramid_tm zope.sqlalchemy # Windows c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar waitress pyramid_tm zope.sqlalchemy
Why easy_install and not pip? Pyramid encourages use of namespace packages, for which pip's support is less-than-optimal. Also, Pyramid's dependencies use some optional C extensions for performance: with easy_install, Windows users can get these extensions without needing a C compiler (pip does not support installing binary Windows distributions, except for wheels, which are not yet available for all dependencies).