Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 282 lines (176 sloc) 8.409 kb
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
1 .. _getting_started:
233b6c4 @bbangert Initial docs in progress
bbangert authored
2
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
3 ===============
233b6c4 @bbangert Initial docs in progress
bbangert authored
4 Getting Started
5 ===============
6
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
7 This section is intended to get Pylons up and running as fast as
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
8 possible and provide a quick overview of the project. Links are provided
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
9 throughout to encourage exploration of the various aspects of Pylons.
c85feb4 @bbangert More doc updates
bbangert authored
10
11
6c22d75 @bbangert Updated for proper para settings
bbangert authored
12 ************
233b6c4 @bbangert Initial docs in progress
bbangert authored
13 Requirements
6c22d75 @bbangert Updated for proper para settings
bbangert authored
14 ************
233b6c4 @bbangert Initial docs in progress
bbangert authored
15
d4c2a18 @bbangert Whitespace
bbangert authored
16 * Python 2 series above and including 2.4 (Python 3 or later not supported at
ef28651 @bbangert Update for RC2, deprecation warning fix
bbangert authored
17 this time)
233b6c4 @bbangert Initial docs in progress
bbangert authored
18
1a36a50 @bbangert Some minor updates to quickwiki
bbangert authored
19
20 .. _installing_pylons:
21
6c22d75 @bbangert Updated for proper para settings
bbangert authored
22 **********
233b6c4 @bbangert Initial docs in progress
bbangert authored
23 Installing
6c22d75 @bbangert Updated for proper para settings
bbangert authored
24 **********
233b6c4 @bbangert Initial docs in progress
bbangert authored
25
26 To avoid conflicts with system-installed Python libraries, Pylons comes with a
041d2b2 @ches add glossary entries for easy_install and virtualenv -- they're referenc...
ches authored
27 boot-strap Python script that sets up a "virtual" Python environment. Pylons will then be installed under the virtual environment.
233b6c4 @bbangert Initial docs in progress
bbangert authored
28
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
29 .. admonition:: By the Way
d4c2a18 @bbangert Whitespace
bbangert authored
30
041d2b2 @ches add glossary entries for easy_install and virtualenv -- they're referenc...
ches authored
31 :term:`virtualenv` is a useful tool to create isolated Python environments.
32 In addition to isolating packages from possible system conflicts, it makes
33 it easy to install Python libraries using :term:`easy_install` without
34 dumping lots of packages into the system-wide Python.
d4c2a18 @bbangert Whitespace
bbangert authored
35
c85feb4 @bbangert More doc updates
bbangert authored
36 The other great benefit is that no root access is required since all
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
37 modules are kept under the desired directory. This makes it easy
233b6c4 @bbangert Initial docs in progress
bbangert authored
38 to setup a working Pylons install on shared hosting providers and other
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
39 systems where system-wide access is unavailable.
233b6c4 @bbangert Initial docs in progress
bbangert authored
40
820669c @bbangert 1.0 updates
bbangert authored
41 1. Download the `go-pylons.py <http://www.pylonshq.com/download/1.0/go-pylons.py>`_ script.
233b6c4 @bbangert Initial docs in progress
bbangert authored
42 2. Run the script and specify a directory for the virtual environment to be created under:
d4c2a18 @bbangert Whitespace
bbangert authored
43
233b6c4 @bbangert Initial docs in progress
bbangert authored
44 .. code-block:: bash
d4c2a18 @bbangert Whitespace
bbangert authored
45
233b6c4 @bbangert Initial docs in progress
bbangert authored
46 $ python go-pylons.py mydevenv
47
137b769 @bbangert Doc updates
bbangert authored
48 .. admonition:: Tip
d4c2a18 @bbangert Whitespace
bbangert authored
49
137b769 @bbangert Doc updates
bbangert authored
50 The two steps can be combined on unix systems with curl using the
51 following short-cut:
d4c2a18 @bbangert Whitespace
bbangert authored
52
137b769 @bbangert Doc updates
bbangert authored
53 .. code-block:: bash
d4c2a18 @bbangert Whitespace
bbangert authored
54
55 $ curl https://raw.githubusercontent.com/Pylons/pylons/master/scripts/go-pylons.py | python - mydevenv
56
137b769 @bbangert Doc updates
bbangert authored
57 To isolate further from additional system-wide Python libraries, run
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
58 with the --no-site-packages option:
d4c2a18 @bbangert Whitespace
bbangert authored
59
137b769 @bbangert Doc updates
bbangert authored
60 .. code-block:: bash
d4c2a18 @bbangert Whitespace
bbangert authored
61
137b769 @bbangert Doc updates
bbangert authored
62 $ python go-pylons.py --no-site-packages mydevenv
d4c2a18 @bbangert Whitespace
bbangert authored
63
1a36a50 @bbangert Some minor updates to quickwiki
bbangert authored
64 | **How it Works**
d4c2a18 @bbangert Whitespace
bbangert authored
65
1a36a50 @bbangert Some minor updates to quickwiki
bbangert authored
66 The ``go-pylons.py`` script is little more than a basic :term:`virtualenv`
67 bootstrap script, that then does ``easy_install Pylons==1.0``. You could
68 do the equivilant steps by manually fetching the ``virtualenv.py`` script
69 and then installing Pylons like so:
d4c2a18 @bbangert Whitespace
bbangert authored
70
1a36a50 @bbangert Some minor updates to quickwiki
bbangert authored
71 .. code-block:: bash
d4c2a18 @bbangert Whitespace
bbangert authored
72
1a36a50 @bbangert Some minor updates to quickwiki
bbangert authored
73 curl -O http://bitbucket.org/ianb/virtualenv/raw/8dd7663d9811/virtualenv.py
74 python virtualenv.py mydevenv
75 mydevenv/bin/easy_install Pylons==1.0
d4c2a18 @bbangert Whitespace
bbangert authored
76
137b769 @bbangert Doc updates
bbangert authored
77
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
78 This will leave a functional virtualenv and Pylons installation.
d4c2a18 @bbangert Whitespace
bbangert authored
79
80
137b769 @bbangert Doc updates
bbangert authored
81 Activate the virtual environment (scripts may also be run by specifying the
82 full path to the mydevenv/bin dir):
233b6c4 @bbangert Initial docs in progress
bbangert authored
83
84 .. code-block:: bash
137b769 @bbangert Doc updates
bbangert authored
85
86 $ source mydevenv/bin/activate
87
88 Or on Window to activate:
89
90 .. code-block:: text
d4c2a18 @bbangert Whitespace
bbangert authored
91
0dacdaa @pjenvey fix windows activate.bat path
pjenvey authored
92 > mydevenv\Scripts\activate.bat
233b6c4 @bbangert Initial docs in progress
bbangert authored
93
ef28651 @bbangert Update for RC2, deprecation warning fix
bbangert authored
94 .. note::
d4c2a18 @bbangert Whitespace
bbangert authored
95
ef28651 @bbangert Update for RC2, deprecation warning fix
bbangert authored
96 If you get an error such as::
d4c2a18 @bbangert Whitespace
bbangert authored
97
ef28651 @bbangert Update for RC2, deprecation warning fix
bbangert authored
98 ImportError: No module named _md5
d4c2a18 @bbangert Whitespace
bbangert authored
99
ef28651 @bbangert Update for RC2, deprecation warning fix
bbangert authored
100 during the install. It is likely that your Python installation is missing
101 standard libraries needed to run Pylons. Debian and other systems using
102 debian packages most frequently encounter this, make sure to install
103 the ``python-dev`` packages and ``python-hashlib`` packages.
104
233b6c4 @bbangert Initial docs in progress
bbangert authored
105
d4c2a18 @bbangert Whitespace
bbangert authored
106 Working Directly From the Source Code
6c22d75 @bbangert Updated for proper para settings
bbangert authored
107 =====================================
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
108
d4c2a18 @bbangert Whitespace
bbangert authored
109 `Mercurial <http://www.selenic.com/mercurial/wiki/>`_ must be installed to retrieve the latest development source for Pylons. `Mercurial packages <http://www.selenic.com/mercurial/wiki/index.cgi/BinaryPackages>`_ are also available for Windows, MacOSX, and other OS's.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
110
d4c2a18 @bbangert Whitespace
bbangert authored
111 Check out the latest code:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
112
d4c2a18 @bbangert Whitespace
bbangert authored
113 .. code-block:: bash
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
114
ef28651 @bbangert Update for RC2, deprecation warning fix
bbangert authored
115 $ hg clone http://bitbucket.org/bbangert/pylons/
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
116
d4c2a18 @bbangert Whitespace
bbangert authored
117 To tell setuptools to use the version in the ``Pylons`` directory:
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
118
d4c2a18 @bbangert Whitespace
bbangert authored
119 .. code-block:: bash
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
120
d4c2a18 @bbangert Whitespace
bbangert authored
121 $ cd pylons
122 $ python setup.py develop
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
123
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
124 The active version of Pylons is now the copy in this directory, and changes made there will be reflected for Pylons apps running.
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
125
126
6c22d75 @bbangert Updated for proper para settings
bbangert authored
127 *************************
233b6c4 @bbangert Initial docs in progress
bbangert authored
128 Creating a Pylons Project
6c22d75 @bbangert Updated for proper para settings
bbangert authored
129 *************************
233b6c4 @bbangert Initial docs in progress
bbangert authored
130
137b769 @bbangert Doc updates
bbangert authored
131 Create a new project named ``helloworld`` with the following command:
83378fa @bbangert More doc updates
bbangert authored
132
133 .. code-block:: bash
134
135 $ paster create -t pylons helloworld
136
d4c2a18 @bbangert Whitespace
bbangert authored
137 .. note::
138
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
139 Windows users must configure their ``PATH`` as described in :ref:`windows_notes`, otherwise they must specify the full path to the ``paster`` command (including the virtual environment bin directory).
83378fa @bbangert More doc updates
bbangert authored
140
271c917 @pjenvey remove references to the google_app_engine option
pjenvey authored
141 Running this will prompt for two choices:
b641223 @ches update 'Getting Started' doc for new Google App Engine option at project...
ches authored
142
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
143 1. which templating engine to use
fc4a383 @pjenvey update per latest template, shorten 'whether or not'
pjenvey authored
144 2. whether to include :term:`SQLAlchemy` support
b641223 @ches update 'Getting Started' doc for new Google App Engine option at project...
ches authored
145
d4c2a18 @bbangert Whitespace
bbangert authored
146 Hit enter at each prompt to accept the defaults (Mako templating, no :term:`SQLAlchemy`).
83378fa @bbangert More doc updates
bbangert authored
147
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
148 Here is the created directory structure with links to more information:
83378fa @bbangert More doc updates
bbangert authored
149
137b769 @bbangert Doc updates
bbangert authored
150 - helloworld
151 - MANIFEST.in
152 - README.txt
153 - development.ini - :ref:`run-config`
154 - docs
155 - ez_setup.py
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
156 - helloworld (See the nested :ref:`helloworld directory <helloworld_dir>`)
137b769 @bbangert Doc updates
bbangert authored
157 - helloworld.egg-info
158 - setup.cfg
159 - setup.py - :ref:`setup-config`
160 - test.ini
83378fa @bbangert More doc updates
bbangert authored
161
bfbe172 @bbangert Update docs for full latex building
bbangert authored
162 .. _helloworld_dir:
163
164 The nested ``helloworld directory`` looks like this:
165
166 - helloworld
167 - __init__.py
168 - config
169 - environment.py - :ref:`environment-config`
170 - middleware.py - :ref:`middleware-config`
171 - routing.py - :ref:`url-config`
172 - controllers - :ref:`controllers`
173 - lib
174 - app_globals.py - :term:`app_globals`
175 - base.py
176 - helpers.py - :ref:`helpers`
177 - model - :ref:`models`
178 - public
179 - templates - :ref:`templates`
180 - tests - :ref:`testing`
181 - websetup.py - :ref:`run-config`
182
183
83378fa @bbangert More doc updates
bbangert authored
184
6c22d75 @bbangert Updated for proper para settings
bbangert authored
185 ***********************
d1e7854 @bbangert Adding more module docs
bbangert authored
186 Running the application
6c22d75 @bbangert Updated for proper para settings
bbangert authored
187 ***********************
d1e7854 @bbangert Adding more module docs
bbangert authored
188
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
189 Run the web application:
c85feb4 @bbangert More doc updates
bbangert authored
190
d1e7854 @bbangert Adding more module docs
bbangert authored
191 .. code-block:: bash
192
193 $ cd helloworld
194 $ paster serve --reload development.ini
d4c2a18 @bbangert Whitespace
bbangert authored
195
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
196 The command loads the project's server configuration file in :file:`development.ini` and serves the Pylons application.
d1e7854 @bbangert Adding more module docs
bbangert authored
197
c85feb4 @bbangert More doc updates
bbangert authored
198 .. note::
d4c2a18 @bbangert Whitespace
bbangert authored
199
c85feb4 @bbangert More doc updates
bbangert authored
200 The ``--reload`` option ensures that the server is automatically reloaded
d4c2a18 @bbangert Whitespace
bbangert authored
201 if changes are made to Python files or the :file:`development.ini`
c85feb4 @bbangert More doc updates
bbangert authored
202 config file. This is very useful during development. To stop the server
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
203 press :command:`Ctrl+c` or the platform's equivalent.
d4c2a18 @bbangert Whitespace
bbangert authored
204
205 The paster serve command can be run anywhere, as long as the
ef28651 @bbangert Update for RC2, deprecation warning fix
bbangert authored
206 development.ini path is properly specified. Generally during development
207 it's run in the root directory of the project.
d1e7854 @bbangert Adding more module docs
bbangert authored
208
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
209 Visiting http://127.0.0.1:5000/ when the server is running will show the welcome page.
d1e7854 @bbangert Adding more module docs
bbangert authored
210
211
6c22d75 @bbangert Updated for proper para settings
bbangert authored
212 ***********
233b6c4 @bbangert Initial docs in progress
bbangert authored
213 Hello World
6c22d75 @bbangert Updated for proper para settings
bbangert authored
214 ***********
233b6c4 @bbangert Initial docs in progress
bbangert authored
215
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
216 To create the basic hello world application, first create a
c85feb4 @bbangert More doc updates
bbangert authored
217 :term:`controller` in the project to handle requests:
218
219 .. code-block:: bash
83378fa @bbangert More doc updates
bbangert authored
220
c85feb4 @bbangert More doc updates
bbangert authored
221 $ paster controller hello
d1e7854 @bbangert Adding more module docs
bbangert authored
222
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
223 Open the :file:`helloworld/controllers/hello.py` module that was created.
224 The default controller will return just the string 'Hello World':
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
225
226 .. code-block:: python
d1e7854 @bbangert Adding more module docs
bbangert authored
227
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
228 import logging
233b6c4 @bbangert Initial docs in progress
bbangert authored
229
c291c63 @pjenvey Backed out changeset 5ffbb270c8a3
pjenvey authored
230 from pylons import request, response, session, tmpl_context as c, url
231 from pylons.controllers.util import abort, redirect
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
232
233 from helloworld.lib.base import BaseController, render
234
235 log = logging.getLogger(__name__)
d4c2a18 @bbangert Whitespace
bbangert authored
236
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
237 class HelloController(BaseController):
238
239 def index(self):
240 # Return a rendered template
fc4a383 @pjenvey update per latest template, shorten 'whether or not'
pjenvey authored
241 #return render('/hello.mako')
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
242 # or, Return a response
243 return 'Hello World'
244
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
245 At the top of the module, some commonly used objects are imported automatically.
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
246
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
247 Navigate to http://127.0.0.1:5000/hello/index where there should be a short text string saying "Hello World" (start up the app if needed):
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
248
249 .. image:: _static/helloworld.png
250
f61636c Made some grammar changes.
jj@jjinux.jjinuxland authored
251 .. admonition:: Tip
d4c2a18 @bbangert Whitespace
bbangert authored
252
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
253 :ref:`url-config` explains how URL's get mapped to controllers and
254 their methods.
255
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
256 Add a template to render some of the information that's in the :term:`environ`.
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
257
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
258 First, create a :file:`hello.mako` file in the :file:`templates`
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
259 directory with the following contents:
260
261 .. code-block:: mako
262
2744e1f @bbangert Remove remaining 'you' references
bbangert authored
263 Hello World, the environ variable looks like: <br />
d4c2a18 @bbangert Whitespace
bbangert authored
264
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
265 ${request.environ}
266
e612af3 @bbangert Properly referencing template globals
bbangert authored
267 The :term:`request` variable in templates is used to get information about the current request. :ref:`Template globals <template-globals>` lists all the variables Pylons makes available for use in templates.
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
268
b368362 @gjhiggins Result of June sprint on documentation. Confluence "Official Python docs...
gjhiggins authored
269 Next, update the :file:`controllers/hello.py` module so that the
270 index method is as follows:
271
272 .. code-block:: python
8f25517 @bbangert Finishing up the getting started doc
bbangert authored
273
274 class HelloController(BaseController):
275
276 def index(self):
277 return render('/hello.mako')
278
279 Refreshing the page in the browser will now look similar to this:
280
b641223 @ches update 'Getting Started' doc for new Google App Engine option at project...
ches authored
281 .. image:: _static/hellotemplate.png
Something went wrong with that request. Please try again.