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 |
|