Requirements¶
Let's get our tutorial environment set up. Most of the set up work is in standard Python development practices (install Python and make an isolated virtual environment.)
Note
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 that are consistent with the Python Packaging Authority.
This Quick Tutorial is based on:
- Python 3.3. Pyramid fully supports Python 3.2+ and Python 2.6+. This tutorial uses Python 3.3 but runs fine under Python 2.7.
- pyvenv. We believe in virtual environments. For this tutorial,
we use Python 3.3's built-in solution, the
pyvenv
command. For Python 2.7, you can installvirtualenv
. - setuptools and easy_install. We use setuptools and its
easy_install
for package management. - Workspaces, projects, and packages. Our home directory will contain a tutorial workspace with our Python virtual environment and Python projects (a directory with packaging information and Python packages of working code.)
- Unix commands. Commands in this tutorial use UNIX syntax and paths. Windows users should adjust commands accordingly.
Note
Pyramid was one of the first web frameworks to fully support Python 3 in October 2011.
Note
Windows commands use the plain old MSDOS shell. For PowerShell command syntax, see its documentation.
Steps¶
- Install Python 3.3 or greater
- Create a project directory structure
- Set an environment variable
- Create a virtual environment
- Install setuptools (Python packaging tools)
- Install Pyramid
Install Python 3.3 or greater¶
Download the latest standard Python 3.3+ release (not development release) from python.org.
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.
Create a project directory structure¶
We will arrive at a directory structure of workspace -> project -> package
,
where our workspace is named quick_tutorial
. The following tree diagram
shows how this will be structured, and where our virtual environment
will reside as we proceed through the tutorial:
`── ~
`── projects
`── quick_tutorial
│── env
`── step_one
│── intro
│ │── __init__.py
│ `── app.py
`── setup.py
For Linux, the commands to do so are as follows:
# Mac and Linux
$ cd ~
$ mkdir -p projects/quick_tutorial
$ cd projects/quick_tutorial
For Windows:
# 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, where virtual
environments, specific project files, and repositories are stored.
Set an environment variable¶
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/env
# Windows
c:\> set VENV=c:\projects\quick_tutorial\env
Create a virtual environment¶
Warning
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%
See also
See also Python 3's venv module
,
Python 2's virtualenv
package,
Installing Pyramid on a Windows System
Install setuptools
(Python packaging tools)¶
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://bootstrap.pypa.io/ez_setup.py -O - | $VENV/bin/python
# Windows
#
# Use your web browser to download this file:
# https://bootstrap.pypa.io/ez_setup.py
#
# ...and save it to:
# c:\projects\quick_tutorial\ez_setup.py
#
# Then run the following command:
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://bootstrap.pypa.io/ez_setup.py -O - | $VENV/bin/python
Install Pyramid¶
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.6.5" # Windows c:\> %VENV%\Scripts\easy_install "pyramid==1.6.5"
Our Python virtual environment now has the Pyramid software available.
You can optionally install some of the extra Python packages used in 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
Note
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).
See also
See also Installing Pyramid on a UNIX System. For instructions to set up your Python environment for development using Windows or Python 2, see Pyramid's Before You Install.
See also Python 3's venv module
, the setuptools
installation instructions,
and easy_install help.