Steve Piercy
2017-10-22 594874099a39fb991d7eedc0d6203dc370c7470a
commit | author | age
b731b5 1 .. _qtut_requirements:
PE 2
187104 3 ============
PE 4 Requirements
5 ============
6
44bbbc 7 Let's get our tutorial environment set up. Most of the set up work is in
SP 8 standard Python development practices (install Python and make an isolated
b61a8b 9 virtual environment.)
187104 10
PE 11 .. note::
12
b61a8b 13   Pyramid encourages standard Python development practices with packaging
SP 14   tools, virtual environments, logging, and so on. There are many variations,
15   implementations, and opinions across the Python community.  For consistency,
16   ease of documentation maintenance, and to minimize confusion, the Pyramid
17   *documentation* has adopted specific conventions that are consistent with the
18   :term:`Python Packaging Authority`.
187104 19
PE 20 This *Quick Tutorial* is based on:
21
c8a5e0 22 * **Python 3.6**. Pyramid fully supports Python 3.4+ and Python 2.7+. This
SP 23   tutorial uses **Python 3.6** but runs fine under Python 2.7.
187104 24
d60369 25 * **venv**. We believe in virtual environments. For this tutorial, we use
c8a5e0 26   Python 3.6's built-in solution :term:`venv`. For Python 2.7, you can install
b61a8b 27   :term:`virtualenv`.
187104 28
b61a8b 29 * **pip**. We use :term:`pip` for package management.
187104 30
b61a8b 31 * **Workspaces, projects, and packages.** Our home directory will contain a
SP 32   *tutorial workspace* with our Python virtual environment and *Python
33   projects* (a directory with packaging information and *Python packages* of
34   working code.)
187104 35
b61a8b 36 * **Unix commands**. Commands in this tutorial use UNIX syntax and paths.
SP 37   Windows users should adjust commands accordingly.
187104 38
PE 39 .. note::
40     Pyramid was one of the first web frameworks to fully support Python 3 in
41     October 2011.
b61a8b 42
SP 43 .. note::
44     Windows commands use the plain old MSDOS shell. For PowerShell command
45     syntax, see its documentation.
187104 46
PE 47 Steps
48 =====
49
44bbbc 50 #. :ref:`install-python-3`
187104 51 #. :ref:`create-a-project-directory-structure`
PE 52 #. :ref:`set-an-environment-variable`
53 #. :ref:`create-a-virtual-environment`
54 #. :ref:`install-pyramid`
55
56
44bbbc 57 .. _install-python-3:
187104 58
44bbbc 59 Install Python 3
SP 60 ----------------
187104 61
b61a8b 62 See the detailed recommendation for your operating system described under
SP 63 :ref:`installing_chapter`.
44bbbc 64
b61a8b 65 - :ref:`for-mac-os-x-users`
SP 66 - :ref:`if-you-don-t-yet-have-a-python-interpreter-unix`
67 - :ref:`if-you-don-t-yet-have-a-python-interpreter-windows`
187104 68
PE 69
70 .. _create-a-project-directory-structure:
71
72 Create a project directory structure
73 ------------------------------------
74
b61a8b 75 We will arrive at a directory structure of ``workspace -> project -> package``,
SP 76 where our workspace is named ``quick_tutorial``. The following tree diagram
77 shows how this will be structured, and where our :term:`virtual environment`
78 will reside as we proceed through the tutorial:
187104 79
0d4d7c 80 .. code-block:: text
187104 81
f3a884 82     `── ~
SP 83         `── projects
84             `── quick_tutorial
85                 │── env
86                 `── step_one
87                     │── intro
88                     │   │── __init__.py
89                     │   `── app.py
90                     `── setup.py
187104 91
ebca90 92 For Linux, the commands to do so are as follows:
187104 93
PE 94 .. code-block:: bash
95
96     # Mac and Linux
97     $ cd ~
ebca90 98     $ mkdir -p projects/quick_tutorial
PE 99     $ cd projects/quick_tutorial
100
101 For Windows:
102
b61a8b 103 .. code-block:: doscon
187104 104
PE 105     # Windows
106     c:\> cd \
ebca90 107     c:\> mkdir projects\quick_tutorial
PE 108     c:\> cd projects\quick_tutorial
187104 109
b61a8b 110 In the above figure, your user home directory is represented by ``~``. In your
SP 111 home directory, all of your projects are in the ``projects`` directory. This is
112 a general convention not specific to Pyramid that many developers use. Windows
113 users will do well to use ``c:\`` as the location for ``projects`` in order to
114 avoid spaces in any of the path names.
187104 115
PE 116 Next within ``projects`` is your workspace directory, here named
117 ``quick_tutorial``. A workspace is a common term used by integrated
b61a8b 118 development environments (IDE), like PyCharm and PyDev, where virtual
SP 119 environments, specific project files, and repositories are stored.
187104 120
PE 121
122 .. _set-an-environment-variable:
123
b61a8b 124 Set an environment variable
187104 125 ---------------------------
PE 126
b61a8b 127 This tutorial will refer frequently to the location of the :term:`virtual
SP 128 environment`. We set an environment variable to save typing later.
187104 129
PE 130 .. code-block:: bash
131
132     # Mac and Linux
0d4d7c 133     $ export VENV=~/projects/quick_tutorial/env
187104 134
b61a8b 135 .. code-block:: doscon
44bbbc 136
187104 137     # Windows
0d4d7c 138     c:\> set VENV=c:\projects\quick_tutorial\env
187104 139
PE 140
141 .. _create-a-virtual-environment:
142
789a90 143 Create a virtual environment
187104 144 ----------------------------
PE 145
d60369 146 ``venv`` is a tool to create isolated Python 3 environments, each with its own
SP 147 Python binary and independent set of installed Python packages in its site
148 directories. Let's create one, using the location we just specified in the
149 environment variable.
187104 150
PE 151 .. code-block:: bash
152
153     # Mac and Linux
d60369 154     $ python3 -m venv $VENV
187104 155
b61a8b 156 .. code-block:: doscon
187104 157
PE 158     # Windows
7ed8e2 159     c:\> python -m venv %VENV%
25c886 160
186b72 161 .. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
d67566 162    2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package.
187104 163
PE 164
789a90 165 Update packaging tools in the virtual environment
SP 166 -------------------------------------------------
167
168 It's always a good idea to update to the very latest version of packaging tools
169 because the installed Python bundles only the version that was available at the
170 time of its release.
171
172 .. code-block:: bash
173
174     # Mac and Linux
caee6c 175     $ $VENV/bin/pip install --upgrade pip setuptools
789a90 176
SP 177 .. code-block:: doscon
178
179     # Windows
180     c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
181
21f2b6 182 .. seealso:: See also :ref:`Why use $VENV/bin/pip instead of source
SP 183    bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.
184
789a90 185
187104 186 .. _install-pyramid:
PE 187
188 Install Pyramid
189 ---------------
190
191 We have our Python standard prerequisites out of the way. The Pyramid
95afe6 192 part is pretty easy. We'll also install a WSGI server, Waitress.
187104 193
ebca90 194 .. parsed-literal::
187104 195
PE 196     # Mac and Linux
95afe6 197     $ $VENV/bin/pip install "pyramid==\ |release|\ " waitress
187104 198
PE 199     # Windows
95afe6 200     c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " waitress
187104 201
95afe6 202 Our Python virtual environment now has the Pyramid software available
SP 203 as well as the ``waitress`` package.
187104 204
b61a8b 205 You can optionally install some of the extra Python packages used in this
789a90 206 tutorial.
187104 207
PE 208 .. code-block:: bash
209
210     # Mac and Linux
878d1a 211     $ $VENV/bin/pip install webtest pytest pytest-cov deform sqlalchemy \
d5e676 212       pyramid_chameleon pyramid_debugtoolbar pyramid_jinja2 waitress \
SP 213       pyramid_tm zope.sqlalchemy
187104 214
b61a8b 215 .. code-block:: doscon
44bbbc 216
187104 217     # Windows
7ed8e2 218     c:\> %VENV%\Scripts\pip install webtest pytest pytest-cov deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar pyramid_jinja2 waitress pyramid_tm zope.sqlalchemy