Web2py8.5plus3minus4plus24plus2minus2Full Stack Web Framework, 4th Edition Web2py Manual 4th.1

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 583

Download
Open PDF In Browser	View PDF

MASSIMO DI PIERRO

WEB2PY
F U L L - S TA C K W E B F R A M E W O R K , 4 T H E D I T I O N

EXPERTS4SOLUTIONS

Copyright 2008-2012 by Massimo Di Pierro. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted
in any form or by any means, electronic, mechanical, photocopying, recording, scanning,
or otherwise, except as permitted under Section 107 or 108 of the 1976 United States Copyright Act, without either the prior written permission of the Publisher, or authorization
through payment of the appropriate per-copy fee to the Copyright Clearance Center, Inc.,
222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 646-8600, or on the web at
www.copyright.com. Requests to the Copyright owner for permission should be addressed
to:
Massimo Di Pierro
School of Computing
DePaul University
243 S Wabash Ave
Chicago, IL 60604 (USA)
Email: massimo.dipierro@gmail.com

Limit of Liability/Disclaimer of Warranty: While the publisher and author have used their
best efforts in preparing this book, they make no representations or warranties with respect
to the accuracy or completeness of the contents of this book and specifically disclaim any
implied warranties of merchantability or fitness for a particular purpose. No warranty
may be created ore extended by sales representatives or written sales materials. The advice
and strategies contained herein may not be suitable for your situation. You should consult
with a professional where appropriate. Neither the publisher nor author shall be liable for
any loss of profit or any other commercial damages, including but not limited to special,
incidental, consequential, or other damages.

Library of Congress Cataloging-in-Publication Data:

ISBN: 978-0-578-09793-0
Build Date: December 9, 2011

to my family

Contents
1 Introduction
1.1 Principles . . . . . . . .
1.2 Web frameworks . . .
1.3 Model-View-Controller
1.4 Why web2py . . . . . .
1.5 Security . . . . . . . . .
1.6 In the box . . . . . . .
1.7 License . . . . . . . . .
1.8 Acknowledgments . .
1.9 About this book . . . .
1.10 Elements of style . . .
2 The Python language
2.1 About Python . . .
2.2 Starting up . . . . .
2.3 help, dir . . . . . .
2.4 Types . . . . . . . .
2.4.1 str . . . . .
2.4.2 list . . . . .
2.4.3 tuple . . . .
2.4.4 dict . . . . .
2.5 About indentation
2.6 for...in . . . . . . .
2.7 while . . . . . . . .
2.8 if...elif...else . .

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

21
23
24
26
29
31
34
35
37
38
40

.
.
.
.
.
.
.
.
.
.
.
.

43
43
44
45
46
46
47
49
50
51
52
53
53

6

. . . . . . .
. . . . . . . . . . . . . . . . .
2.10.1 lambda . . . . . . . . . . . . . . . .
class . . . . . . . . . . . . . . . . . . . . .
Special attributes, methods and operators
File input/output . . . . . . . . . . . . . .
exec, eval . . . . . . . . . . . . . . . . . . .
import . . . . . . . . . . . . . . . . . . . . .
2.15.1 os . . . . . . . . . . . . . . . . . . .
2.15.2 sys . . . . . . . . . . . . . . . . . .
2.15.3 datetime . . . . . . . . . . . . . . .
2.15.4 time . . . . . . . . . . . . . . . . . .
2.15.5 cPickle . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

54
56
58
60
62
63
64
65
65
66
67
67
68

3 Overview
3.1 Startup . . . . . . . . . . . . . . . . . . . .
3.2 Say hello . . . . . . . . . . . . . . . . . . .
3.3 Let’s count . . . . . . . . . . . . . . . . . .
3.4 Say my name . . . . . . . . . . . . . . . .
3.5 Postbacks . . . . . . . . . . . . . . . . . . .
3.6 An image blog . . . . . . . . . . . . . . . .
3.7 Adding CRUD . . . . . . . . . . . . . . . .
3.8 Adding Authentication . . . . . . . . . . .
3.8.1 Adding grids . . . . . . . . . . . .
3.9 Configuring the layout . . . . . . . . . . .
3.10 A wiki . . . . . . . . . . . . . . . . . . . .
3.10.1 On date, datetime and time format
3.11 More on admin . . . . . . . . . . . . . . .
3.11.1 site . . . . . . . . . . . . . . . . . .
3.11.2 about . . . . . . . . . . . . . . . . .
3.11.3 edit . . . . . . . . . . . . . . . . . .
3.11.4 errors . . . . . . . . . . . . . . . . .
3.11.5 Mercurial . . . . . . . . . . . . . . .
3.11.6 Admin wizard (experimental) . .
3.11.7 Configuring admin . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

69
69
73
78
79
81
84
98
99
102
103
104
115
116
116
119
119
122
126
127
129

2.9
2.10
2.11
2.12
2.13
2.14
2.15

try...except...else...finally
def...return

7

3.12 More on appadmin . . . . . . . . . . . . . . . . . . . . . . . . 130
4 The core
4.1 Command line options . . . . . . . . . . . . . . .
4.2 Workflow . . . . . . . . . . . . . . . . . . . . . . .
4.3 Dispatching . . . . . . . . . . . . . . . . . . . . .
4.4 Libraries . . . . . . . . . . . . . . . . . . . . . . .
4.5 Applications . . . . . . . . . . . . . . . . . . . . .
4.6 API . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1 Accessing the API from Python modules
4.7 request . . . . . . . . . . . . . . . . . . . . . . . .
4.8 response . . . . . . . . . . . . . . . . . . . . . . . .
4.9 session . . . . . . . . . . . . . . . . . . . . . . . .
4.9.1 Separate sessions . . . . . . . . . . . . . .
4.10 cache . . . . . . . . . . . . . . . . . . . . . . . . .
4.11 URL . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.11.1 Absolute urls . . . . . . . . . . . . . . . .
4.11.2 Digitally signed urls . . . . . . . . . . . .
4.12 HTTP and redirect . . . . . . . . . . . . . . . . . .
4.13 T and Internationalization . . . . . . . . . . . . .
4.14 Cookies . . . . . . . . . . . . . . . . . . . . . . . .
4.15 Application init . . . . . . . . . . . . . . . . . . .
4.16 URL rewrite . . . . . . . . . . . . . . . . . . . . .
4.16.1 Parameter-based system . . . . . . . . . .
4.16.2 Pattern-based system . . . . . . . . . . .
4.17 Routes on error . . . . . . . . . . . . . . . . . . .
4.18 Running tasks in the background . . . . . . . . .
4.18.1 Cron . . . . . . . . . . . . . . . . . . . . .
4.18.2 Homemade task queues . . . . . . . . . .
4.18.3 Scheduler (experimental) . . . . . . . . .
4.19 Third party modules . . . . . . . . . . . . . . . .
4.20 Execution environment . . . . . . . . . . . . . . .
4.21 Cooperation . . . . . . . . . . . . . . . . . . . . .
4.22 Logging . . . . . . . . . . . . . . . . . . . . . . . .
4.23 WSGI . . . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

133
133
137
139
143
149
151
152
155
160
164
166
166
169
172
172
173
175
178
179
179
180
182
186
187
188
191
192
195
197
198
199
200

8

4.23.1 External middleware . . . . . . . . . . . . . . . . . . . 201
4.23.2 Internal middleware . . . . . . . . . . . . . . . . . . . 201
4.23.3 Calling WSGI applications . . . . . . . . . . . . . . . 202
5 The views
5.1 Basic syntax . . . . . . . . . . . . . . .
5.1.1 for...in . . . . . . . . . . . . .
5.1.2 while . . . . . . . . . . . . . . .
5.1.3 if...elif...else . . . . . . . .
5.1.4 try...except...else...finally
5.1.5 def...return . . . . . . . . . . .
5.2 HTML helpers . . . . . . . . . . . . . .
5.2.1 XML . . . . . . . . . . . . . . . .
5.2.2 Built-in helpers . . . . . . . . .
5.2.3 Custom helpers . . . . . . . . .
5.3 BEAUTIFY . . . . . . . . . . . . . . . . . .
5.4 Server-side DOM and parsing . . . . .
5.4.1 elements . . . . . . . . . . . . .
5.4.2 components . . . . . . . . . . . .
5.4.3 parent . . . . . . . . . . . . . .
5.4.4 flatten . . . . . . . . . . . . . .
5.4.5 Parsing . . . . . . . . . . . . . .
5.5 Page layout . . . . . . . . . . . . . . . .
5.5.1 Default page layout . . . . . .
5.5.2 Customizing the default layout
5.5.3 Mobile development . . . . . .
5.6 Functions in views . . . . . . . . . . .
5.7 Blocks in views . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

203
205
205
206
206
207
208
209
211
212
227
229
229
229
231
231
231
232
232
236
240
240
241
242

6 The database abstraction layer
6.1 Dependencies . . . . . . . .
6.2 Connection strings . . . . .
6.2.1 Connection pooling
6.2.2 Connection failures .
6.2.3 Replicated databases

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

245
245
247
248
249
249

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

9

6.3
6.4
6.5
6.6
6.7
6.8
6.9
6.10

6.11
6.12
6.13
6.14
6.15
6.16
6.17

6.18

6.19

Reserved keywords . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
Record representation . . . . . . . . . . . . . . .
Migrations . . . . . . . . . . . . . . . . . . . . . .
Fixing broken migrations . . . . . . . . . . . . .
insert . . . . . . . . . . . . . . . . . . . . . . . . .
commit and rollback . . . . . . . . . . . . . . . . .
Raw sql . . . . . . . . . . . . . . . . . . . . . . . .
6.10.1 Timing queries . . . . . . . . . . . . . . .
6.10.2 executesql . . . . . . . . . . . . . . . . . .
6.10.3 _lastsql . . . . . . . . . . . . . . . . . . .
drop . . . . . . . . . . . . . . . . . . . . . . . . . .
Indexes . . . . . . . . . . . . . . . . . . . . . . . .
Legacy databases and keyed tables . . . . . . . .
Distributed transaction . . . . . . . . . . . . . . .
Manual uploads . . . . . . . . . . . . . . . . . . .
Query, Set, Rows . . . . . . . . . . . . . . . . . . . .
select . . . . . . . . . . . . . . . . . . . . . . . . .
6.17.1 Shortcuts . . . . . . . . . . . . . . . . . . .
6.17.2 Fetching a Row . . . . . . . . . . . . . . . .
6.17.3 Recursive selects . . . . . . . . . . . . . .
6.17.4 Serializing Rows in views . . . . . . . . . .
6.17.5 orderby, groupby, limitby, distinct . . . .
6.17.6 Logical operators . . . . . . . . . . . . . .
6.17.7 count, isempty, delete, update . . . . . . .
6.17.8 Expressions . . . . . . . . . . . . . . . . .
6.17.9 update_record . . . . . . . . . . . . . . . .
6.17.10 first and last . . . . . . . . . . . . . . . .
6.17.11 as_dict and as_list . . . . . . . . . . . . .
6.17.12 find, exclude, sort . . . . . . . . . . . . . .
Other methods . . . . . . . . . . . . . . . . . . .
6.18.1 update_or_insert . . . . . . . . . . . . . .
6.18.2 validate_and_insert, validate_and_update
6.18.3 smart_query (experimental) . . . . . . . .
Computed fields . . . . . . . . . . . . . . . . . .
DAL, Table, Field

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

249
250
251
257
259
260
261
261
262
262
262
263
263
263
264
265
266
266
268
269
270
271
273
275
275
276
277
277
277
278
279
279
280
280
281

10

6.20 Virtual fields . . . . . . . . . . . . . . . . . . . . . . . . .
6.20.1 Old style virtual fields . . . . . . . . . . . . . . .
6.20.2 New style virtual fields (experimental) . . . . .
6.21 One to many relation . . . . . . . . . . . . . . . . . . . .
6.21.1 Inner joins . . . . . . . . . . . . . . . . . . . . . .
6.21.2 Left outer join . . . . . . . . . . . . . . . . . . . .
6.21.3 Grouping and counting . . . . . . . . . . . . . .
6.22 Many to many . . . . . . . . . . . . . . . . . . . . . . . .
6.23 Many to many, list:, and contains . . . . . . . .
6.24 Other operators . . . . . . . . . . . . . . . . . . . . . . .
6.24.1 like, startswith, contains, upper, lower . . . . . .
6.24.2 year, month, day, hour, minutes, seconds . . . . . .
6.24.3 belongs . . . . . . . . . . . . . . . . . . . . . . . .
6.24.4 sum, min, max and len . . . . . . . . . . . . . . . .
6.24.5 Substrings . . . . . . . . . . . . . . . . . . . . . .
6.24.6 Default values with coalesce and coalesce_zero
6.25 Generating raw sql . . . . . . . . . . . . . . . . . . . . .
6.26 Exporting and importing data . . . . . . . . . . . . . . .
6.26.1 CSV (one Table at a time) . . . . . . . . . . . . .
6.26.2 CSV (all tables at once) . . . . . . . . . . . . . .
6.26.3 CSV and remote database synchronization . . .
6.26.4 HTML and XML (one Table at a time) . . . . . .
6.26.5 Data representation . . . . . . . . . . . . . . . .
6.27 Caching selects . . . . . . . . . . . . . . . . . . . . . . .
6.28 Self-Reference and aliases . . . . . . . . . . . . . . . . .
6.29 Advanced features . . . . . . . . . . . . . . . . . . . . .
6.29.1 Table inheritance . . . . . . . . . . . . . . . . . .
6.29.2 Common fields and multi-tenancy . . . . . . . .
6.29.3 Common filters . . . . . . . . . . . . . . . . . . .
6.29.4 Custom Field types (experimental) . . . . . . .
6.29.5 Using DAL without define tables . . . . . . . .
6.29.6 Copy data from one db into another . . . . . . .
6.29.7 Note on new DAL and adapters . . . . . . . . .
6.29.8 Gotchas . . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

281
282
284
285
286
287
288
289
290
292
292
293
294
294
295
295
296
296
297
297
298
300
301
302
303
304
304
305
306
307
307
308
309
312

11

7 Forms and validators
7.1 FORM . . . . . . . . . . . . . . . . . . . . . . . . .
7.1.1 The process and validate methods . . .
7.1.2 Hidden fields . . . . . . . . . . . . . . .
7.1.3 keepvalues . . . . . . . . . . . . . . . . .
7.1.4 onvalidation . . . . . . . . . . . . . . . .
7.1.5 Detect record change . . . . . . . . . . .
7.1.6 Forms and redirection . . . . . . . . . .
7.1.7 Multiple forms per page . . . . . . . . .
7.1.8 Sharing forms . . . . . . . . . . . . . . .
7.2 SQLFORM . . . . . . . . . . . . . . . . . . . . . . .
7.2.1 SQLFORM and insert/update/delete . . .
7.2.2 SQLFORM in HTML . . . . . . . . . . . . .
7.2.3 SQLFORM and uploads . . . . . . . . . . .
7.2.4 Storing the original filename . . . . . .
7.2.5 autodelete . . . . . . . . . . . . . . . . .
7.2.6 Links to referencing records . . . . . . .
7.2.7 Pre-populating the form . . . . . . . . .
7.2.8 Adding extra form elements to SQLFORM
7.2.9 SQLFORM without database IO . . . . . .
7.3 SQLFORM.factory . . . . . . . . . . . . . . . . . .
7.3.1 One form for multiple tables . . . . . .
7.4 CRUD . . . . . . . . . . . . . . . . . . . . . . . .
7.4.1 Settings . . . . . . . . . . . . . . . . . .
7.4.2 Messages . . . . . . . . . . . . . . . . . .
7.4.3 Methods . . . . . . . . . . . . . . . . . .
7.4.4 Record versioning . . . . . . . . . . . .
7.5 Custom forms . . . . . . . . . . . . . . . . . . .
7.5.1 CSS conventions . . . . . . . . . . . . .
7.5.2 Hide errors . . . . . . . . . . . . . . . .
7.6 Validators . . . . . . . . . . . . . . . . . . . . .
7.6.1 Validators . . . . . . . . . . . . . . . . .
7.6.2 Database validators . . . . . . . . . . .
7.6.3 Custom validators . . . . . . . . . . . .
7.6.4 Validators with dependencies . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

315
316
320
321
322
323
323
324
325
326
326
332
333
334
337
338
338
340
340
341
342
343
344
345
348
349
351
352
354
354
355
357
368
370
372

12

7.7
7.8

Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
7.7.1 Autocomplete widget . . . . . . . . . . . . . . . . . . 374
SQLFORM.grid and SQLFORM.smartgrid (experimental) . . . . . . 375

8 Email and SMS
8.1 Setting up email . . . . . . . . . . . . . . . . . . . .
8.1.1 Configuring email for Google App Engine
8.1.2 x509 and PGP Encryption . . . . . . . . . .
8.2 Sending emails . . . . . . . . . . . . . . . . . . . .
8.2.1 Simple text email . . . . . . . . . . . . . . .
8.2.2 HTML emails . . . . . . . . . . . . . . . . .
8.2.3 Combining text and HTML emails . . . . .
8.2.4 cc and bcc emails . . . . . . . . . . . . . . .
8.2.5 Attachments . . . . . . . . . . . . . . . . . .
8.2.6 Multiple attachments . . . . . . . . . . . . .
8.3 Sending SMS messages . . . . . . . . . . . . . . . .
8.4 Using the template system to generate messages .
8.5 Sending messages using a background task . . . .
9 Access Control
9.1 Authentication . . . . . . . . . . . . . . . . . . . .
9.1.1 Restrictions on registration . . . . . . . .
9.1.2 Integration with OpenID, Facebook, etc.
9.1.3 CAPTCHA and reCAPTCHA . . . . . . .
9.1.4 Customizing Auth . . . . . . . . . . . . . .
9.1.5 Renaming Auth tables . . . . . . . . . . .
9.1.6 Other login methods and login forms . .
9.2 Mail and Auth . . . . . . . . . . . . . . . . . . . .
9.3 Authorization . . . . . . . . . . . . . . . . . . . .
9.3.1 Decorators . . . . . . . . . . . . . . . . . .
9.3.2 Combining requirements . . . . . . . . .
9.3.3 Authorization and CRUD . . . . . . . . .
9.3.4 Authorization and downloads . . . . . .
9.3.5 Access Control and Basic Authentication
9.3.6 Manual Authentication . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.

383
383
384
384
384
385
385
385
386
386
386
386
387
388

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

391
393
396
397
399
400
402
402
409
410
412
413
414
415
416
416

13

9.4

9.3.7 Settings and messages . . . . . . . . . . . . . . . . . . 417
Central Authentication Service . . . . . . . . . . . . . . . . . 423
9.4.1 Using web2py to authorize non-web2py apps . . . . 425

10 Services
10.1 Rendering a dictionary . . . . . . . .
10.1.1 HTML, XML, and JSON . . .
10.1.2 Generic views . . . . . . . . .
10.1.3 Rendering Rows . . . . . . . .
10.1.4 Custom formats . . . . . . . .
10.1.5 RSS . . . . . . . . . . . . . . .
10.1.6 CSV . . . . . . . . . . . . . . .
10.2 Remote procedure calls . . . . . . .
10.2.1 XMLRPC . . . . . . . . . . . .
10.2.2 JSONRPC . . . . . . . . . . .
10.2.3 JSONRPC and Pyjamas . . .
10.2.4 Amfrpc . . . . . . . . . . . . .
10.2.5 SOAP . . . . . . . . . . . . . .
10.3 Low level API and other recipes . .
10.3.1 simplejson . . . . . . . . . . .
10.3.2 PyRTF . . . . . . . . . . . . .
10.3.3 ReportLab and PDF . . . . .
10.4 Restful Web Services . . . . . . . . .
10.4.1 parse_as_rest (experimental)
10.4.2 smart_query (experimental) .
10.4.3 Access Control . . . . . . . .
10.5 Services and Authentication . . . . .
11 jQuery and Ajax
11.1 web2py_ajax.html . . . . . . . . . .
11.2 jQuery effects . . . . . . . . . . . .
11.2.1 Conditional fields in forms
11.2.2 Confirmation on delete . .
11.3 The ajax function . . . . . . . . . .
11.3.1 Eval target . . . . . . . . . .

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

427
427
428
429
430
431
431
433
434
437
438
438
442
444
445
445
446
447
448
451
456
457
457

.
.
.
.
.
.

459
459
463
467
469
470
471

14

11.3.2 Auto-completion . . . . . . . . . . . . . . . . . . . . . 471
11.3.3 Ajax form submission . . . . . . . . . . . . . . . . . . 474
11.3.4 Voting and rating . . . . . . . . . . . . . . . . . . . . . 475
12 Components and plugins
12.1 Components . . . . . . . . . . . . . . . . . . . . . .
12.1.1 Client-Server component communications
12.1.2 Trapped Ajax links . . . . . . . . . . . . . .
12.2 Plugins . . . . . . . . . . . . . . . . . . . . . . . . .
12.2.1 Component plugins . . . . . . . . . . . . .
12.2.2 Plugin manager . . . . . . . . . . . . . . . .
12.2.3 Layout plugins . . . . . . . . . . . . . . . .
12.3 plugin_wiki . . . . . . . . . . . . . . . . . . . . . . .
12.3.1 MARKMIN syntax . . . . . . . . . . . . . . . . .
12.3.2 Page permissions . . . . . . . . . . . . . . .
12.3.3 Special pages . . . . . . . . . . . . . . . . .
12.3.4 Configuring plugin_wiki . . . . . . . . . .
12.3.5 Current widgets . . . . . . . . . . . . . . .
12.3.6 Extending widgets . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

479
479
485
487
487
491
493
494
495
498
500
501
503
503
510

13 Deployment recipes
13.0.7 anyserver.py . . . . . . . . . . . . .
13.1 Linux and Unix . . . . . . . . . . . . . . .
13.1.1 One step production deployment
13.1.2 Apache setup . . . . . . . . . . . .
13.1.3 mod_wsgi . . . . . . . . . . . . . .
13.1.4 mod_wsgi and SSL . . . . . . . . .
13.1.5 mod_proxy . . . . . . . . . . . . .
13.1.6 Start as Linux daemon . . . . . . .
13.1.7 Lighttpd . . . . . . . . . . . . . . .
13.1.8 Shared hosting with mod_python
13.1.9 Cherokee with FastCGI . . . . . .
13.1.10 Postgresql . . . . . . . . . . . . . .
13.2 Windows . . . . . . . . . . . . . . . . . . .
13.2.1 Apache and mod_wsgi . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

513
516
517
517
517
518
522
523
525
526
527
528
530
531
531

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

15

13.2.2 Start as Windows service . . . . . . . . . .
13.3 Securing sessions and admin . . . . . . . . . . . .
13.4 Efficiency and scalability . . . . . . . . . . . . . . .
13.4.1 Efficiency tricks . . . . . . . . . . . . . . . .
13.4.2 Sessions in database . . . . . . . . . . . . .
13.4.3 HAProxy a high availability load balancer
13.4.4 Cleaning up sessions . . . . . . . . . . . . .
13.4.5 Uploading files in database . . . . . . . . .
13.4.6 Collecting tickets . . . . . . . . . . . . . . .
13.4.7 Memcache . . . . . . . . . . . . . . . . . . .
13.4.8 Sessions in memcache . . . . . . . . . . . .
13.4.9 Caching with Redis . . . . . . . . . . . . .
13.4.10 Removing applications . . . . . . . . . . . .
13.4.11 Using replicated databases . . . . . . . . .
13.5 Deploying on Google App Engine . . . . . . . . .
13.5.1 Configuration . . . . . . . . . . . . . . . . .
13.5.2 Running and deployment . . . . . . . . . .
13.5.3 Configuring the handler . . . . . . . . . . .
13.5.4 Avoid the filesystem . . . . . . . . . . . . .
13.5.5 Memcache . . . . . . . . . . . . . . . . . . .
13.5.6 Datastore issues . . . . . . . . . . . . . . . .
13.5.7 GAE and https . . . . . . . . . . . . . . . .
13.6 Jython . . . . . . . . . . . . . . . . . . . . . . . . . .
14 Other recipes
14.1 Upgrading . . . . . . . . . . . . . . . . . . . . . .
14.2 How to distribute your applications as binaries
14.3 Building a minimalist web2py . . . . . . . . . . .
14.4 Fetching an external URL . . . . . . . . . . . . .
14.5 Pretty dates . . . . . . . . . . . . . . . . . . . . .
14.6 Geocoding . . . . . . . . . . . . . . . . . . . . . .
14.7 Pagination . . . . . . . . . . . . . . . . . . . . . .
14.8 httpserver.log and the Log File Format . . . . .
14.9 Populating database with dummy data . . . . .
14.10Accepting credit card payments . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

534
535
536
537
538
538
540
541
541
542
543
544
544
544
545
547
548
550
550
551
551
552
553

.
.
.
.
.
.
.
.
.
.

555
555
555
556
557
558
558
558
560
561
561

16

14.10.1 Google Wallet .
14.10.2 Paypal . . . . .
14.10.3 Stripe.com . . .
14.10.4 Authorize.Net .
14.11Dropbox API . . . . . .
14.12Twitter API . . . . . . .
14.13Streaming virtual files
Bibliography

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

562
564
564
565
567
568
568
571

CONTENTS

17

Preface
web2py was launched in 2007 and now, after four years of continuous
development, we have reached a very much needed fourth edition of this
book. During this time, web2py has managed to win the affection of thousands
of knowledgeable users and more than one hundred developers. Our
collective effort has created one of the most full-featured Open Source Web
Frameworks in existence.

I originally started web2py as a teaching tool because, I believe, the ability to
build high quality web applications is of critical importance for the growth
of a free and open society. It prevents the biggest players from monopolizing
the flow of information. This motivation continues to be valid and it is even
more important today.
In general, the purpose of any web framework is to make web development
easier, faster and prevent developers from making mistakes, especially in
matters related to security. In web2py we address these issues with our three
main goals:
Ease of use is the primary goal for web2py. For us, this means reducing the
learning and deployment time. This is why web2py is a full-stack framework
without dependencies. It requires no installation and has no configuration
files. Everything works out of the box, including a web server, database and a
web-based IDE that gives access to all the main features. The API includes
just 12 core objects, which are easy to work with and memorize. It can
interoperate with most web servers, database and all Python libraries.
Faster development is the secondary goal. Every function of

web2py

has a

20

web2py full-stack web framework, 4th edition

default behavior (which can be overridden). For example, as soon as you have
specified your data models, you will have access to a web-based database
administration panel. web2py also generates automatically forms for your
data and it allows you to easily expose the data in HTML, XML, JSON, RSS,
etc.
Security is at the heart of web2py, and our goal here is to lock everything
down to keep your systems and data safe. Therefore, our database layer
eliminates SQL Injections. The template language prevents Cross Site
Scripting vulnerabilities. The forms generated by web2py provide field
validation and block Cross Site Request Forgeries. Passwords are always
stored hashed. Sessions are stored server-side by default to prevent Cookie
Tampering and session cookies are uuid to prevent Cookie Stealing.
has always been built from the user perspective and is constantly
optimized internally to become faster and leaner, whilst always maintaining
backward compatibility.

web2py

is free for you to use. If you benefit from it, we hope you will feel a
little more like contributing back to society in whatever form you choose.
web2py

In 2011 InfoWorld magazine reviewed six of the most popular full-stack
Python based web frameworks and raked web2py highest. Also in 2011,
web2py won the Bossie Award for best Open Source Development Software.

1
Introduction
web2py [1] is a free, open-source web framework for agile development
of secure database-driven web applications; it is written in Python [2]
and programmable in Python. web2py is a full-stack framework, meaning
that it contains all the components you need to build fully functional web
applications. web2py is designed to guide a web developer to follow good
software engineering practices, such as using the Model View Controller
(MVC) pattern. web2py separates the data representation (the model) from
the data presentation (the view) and also from the application logic and
workflow (the controller). web2py provides libraries to help the developer
design, implement, and test each of these three parts separately, and
makes them work together. web2py is built for security. This means that
it automatically addresses many of the issues that can lead to security
vulnerabilities, by following well established practices. For example, it
validates all input (to prevent injections), escapes all output (to prevent
cross-site scripting), renames uploaded files (to prevent directory traversal
attacks). web2py leaves little choice to application developers in matters
related to security. web2py includes a Database Abstraction Layer (DAL)
that writes SQL [3] dynamically so that you, the developer, don’t have
to. The DAL knows how to generate SQL transparently for SQLite [4],
MySQL [6], PostgreSQL [5], MSSQL [7], FireBird [8], Oracle [9], IBM DB2 [10],
Informix [11], and Ingres [12]. The DAL can also generate function calls for
the Google Datastore when running on the Google App Engine (GAE) [13].

22

web2py full-stack web framework, 4th edition

Experimentally we support more databases. Please check on the web2py
web site and mailing list for more recent adapters. Once one or more
database tables are defined, web2py also generates a fully functional webbased database administration interface to access the database and the
tables. web2py differs from other web frameworks in that it is the only
framework to fully embrace the Web 2.0 paradigm, where the web is the
computer. In fact, web2py does not require installation or configuration;
it runs on any architecture that can run Python (Windows, Windows CE,
Mac OS X, iOS, and Unix/Linux), and the development, deployment, and
maintenance phases for the applications can be done via a local or remote
web interface. web2py runs with CPython (the C implementation) and
Jython (the Java implementation), on Python versions 2.4, 2.5, 2.6, and 2.7,
although "officially" it only supports 2.5 so that we can guarantee backward
compatibility for applications. web2py provides a ticketing system. If an
error occurs, a ticket is issued to the user, and the error is logged for the
administrator. web2py is open source and released under the LGPL version
3 license.
Another feature of web2py is that we, its developers, commit to maintain
backward compatibility in future versions. We have done so since the first
release of web2py in October, 2007. New features have been added and bugs
have been fixed, but if a program worked with web2py 1.0, that program will
still work today.
Here are some examples of web2py statements that illustrate its power and
simplicity. The following code:
1

db.define_table('person', Field('name'), Field('image', 'upload'))

creates a database table called "person" with two fields: "name", a string; and
"image", something that needs to be uploaded (the actual image). If the table
already exists but does not match this definition, it is altered appropriately.
Given the table defined above, the following code:
1

form = crud.create(db.person)

creates an insert form for this table that allows users to upload images. It
also validates a submitted form, renames the uploaded image in a secure

introduction

23

way, stores the image in a file, inserts the corresponding record in the
database, prevents double submission, and eventually modifies the form
itself by adding error messages if the data submitted by the user does not
pass validation.
The following code:
1
2

@auth.requires_permission('read','person')
def f(): ....

prevents visitors from accessing the function f unless the visitor is a member
of a group whose members have permissions to "read" records of table
"person". If the visitor is not logged in, he gets directed to a login page
(provided by default by web2py).
The following code embeds a page component.
1

{{=LOAD('other_controller','function.load',ajax=True, ajax_trap=True)}}

This instructs web2py to load in a view the content generated by the other
controller function (this works with any function). It loads the content via
Ajax, embeds it into the current page (using the current layout, not the layout
of the other_controller function), and traps all forms contained in the loaded
content so that they are also submitted via Ajax without reloading the page.
It can also LOAD content from non-web2py applications.
The LOAD helper allows very modular design of applications; it is discussed
in some detail in the last chapter of this book.

1.1

Principles

Python programming typically follows these basic principles:
• Don’t repeat yourself (DRY).
• There should be only one way of doing things.
• Explicit is better than implicit.
web2py fully embraces the first two principles by forcing the developer to
use sound software engineering practices that discourage repetition of code.

24

web2py full-stack web framework, 4th edition

web2py guides the developer through almost all the tasks common in web
application development (creating and processing forms, managing sessions,
cookies, errors, etc.).
web2py differs from other frameworks with regard to the third principle,
which sometimes conflicts with the other two. In particular, web2py does
not import user applications, but executes them in a predefined context. This
context exposes the Python keywords, as well as the web2py keywords.
To some this may appear as magic, but it should not. Simply, in practice,
some modules are already imported without you doing so. web2py is
trying to avoid the annoying characteristic of other frameworks that force
the developer to import the same modules at the top of every model and
controller. web2py, by importing its own modules, saves time and prevents
mistakes, thus following the spirit of "don’t repeat yourself" and "there
should be only one way of doing things".
If the developer wishes to use other Python modules or third-party modules,
those modules must be imported explicitly, as in any other Python program.

1.2

Web frameworks

At its most fundamental level, a web application consists of a set of programs
(or functions) that are executed when the corresponding URL is visited. The
output of the program is returned to the visitor and rendered by the browser.
The purpose of web frameworks is to allow developers to build new apps
quickly, easily and without mistakes. This is done by providing APIs and
tools that reduce and simplify the amount of coding that is required.
The two classic approaches for developing web applications are:
• Generating HTML [14, 15] programmatically.
• Embedding code into HTML pages.
The first model is the one that was followed, for example, by early CGI
scripts. The second model is followed, for example, by PHP [16] (where the
code is in PHP, a C-like language), ASP (where the code is in Visual Basic),

introduction

25

and JSP (where the code is in Java).
Here is an example of a PHP program that, when executed, retrieves data
from a database and returns an HTML page showing the selected records:
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Records
$name
Phone:$phone


";
$i++;
}
?>

The problem with this approach is that code is embedded into HTML, but
the very same code also needs to generate additional HTML and to generate
SQL statements to query the database, entangling multiple layers of the
application and making it difficult to read and maintain. The situation is
even worse for Ajax applications, and the complexity grows with the number
of pages (files) that make up the application.
The functionality of the above example can be expressed in web2py with two
lines of Python code:
1
2

def index():
return HTML(BODY(H1('Records'), db().select(db.contacts.ALL)))

In this simple example, the HTML page structure is represented
programmatically by the HTML, BODY, and H1 objects; the database db is queried
by the select command; finally, everything is serialized into HTML. Notice
that db is not a keyword but a user defined variable. We will use this name
consistently to refer to a database connection to avoid confusion.
Web frameworks are typically categorized as one of two types: A "glued"
framework is built by assembling (gluing together) several third-party
components. A "full-stack" framework is built by creating components
designed specifically to be tightly integrated and work together. web2py is a

26

web2py full-stack web framework, 4th edition

full-stack framework. Almost all of its components are built from scratch and
are designed to work together, but they function just as well outside of the
complete web2py framework. For example, the Database Abstraction Layer
(DAL) or the template language can be used independently of the web2py
framework by importing gluon.dal or gluon.template into your own Python
applications. gluon is the name of the web2py module that contains system
libraries. Some web2py libraries, such as building and processing forms from
database tables, have dependencies on other portions of web2py. web2py
can also work with third-party Python libraries, including other template
languages and DALs, but they will not be as tightly integrated as the original
components.

1.3

Model-View-Controller

web2py encourages the developer to separate data representation (the
model), data presentation (the view) and the application workflow (the
controller). Let’s consider again the previous example and see how to build
a web2py application around it. Here is an example of the web2py MVC edit
interface:

The typical workflow of a request in web2py is described in the following
diagram:

introduction

27

In the diagram:
• The Server can be the web2py built-in web server or a third-party server,
such as Apache. The Server handles multi-threading.
• "main" is the main WSGI application. It performs all common tasks and
wraps user applications. It deals with cookies, sessions, transactions, URL
routing and reverse routing, and dispatching.
It can serve and stream static files if the web server is not doing it already.
• The Models, Views and Controller components make up the user
application.
• Multiple applications can be hosted in the same web2py instance.
• The dashed arrows represent communication with the database engine(s).
The database queries can be written in raw SQL (discouraged) or by using
the web2py Database Abstraction Layer (recommended), so that web2py
application code is not dependent on the specific database engine.
• The dispatcher maps the requested URL to a function call in the controller.
The output of the function can be a string or a dictionary of symbols (a
hash table). The data in the dictionary is rendered by a view. If the visitor
requests an HTML page (the default), the dictionary is rendered into an
HTML page. If the visitor requests the same page in XML, web2py tries

28

web2py full-stack web framework, 4th edition

to find a view that can render the dictionary in XML. The developer can
create views to render pages in any of the already supported protocols
(HTML, XML, JSON, RSS, CSV, RTF) or in additional custom protocols.
• All calls are wrapped into a transaction, and any uncaught exception
causes the transaction to be rolled back. If the request succeeds, the
transaction is committed.
• web2py also handles sessions and session cookies automatically, and when
a transaction is committed, the session is also stored, unless specified
otherwise.
• It is possible to register recurrent tasks (via cron) to run at scheduled times
and/or after the completion of certain actions. In this way it is possible to
run long and compute-intensive tasks in the background without slowing
down navigation.
Here is a minimal and complete MVC application, consisting of three files:
"db.py" is the model:
1
2
3
4

db = DAL('sqlite://storage.sqlite')
db.define_table('contact',
Field('name'),
Field('phone'))

It connects to the database (in this example a SQLite database stored in the
storage.sqlite file) and defines a table called contact. If the table does not
exist, web2py creates it and, transparently and in the background, generates
SQL code in the appropriate SQL dialect for the specific database engine
used. The developer can see the generated SQL but does not need to change
the code if the database back-end, which defaults to SQLite, is replaced with
MySQL, PostgreSQL, MSSQL, FireBird, Oracle, DB2, Informix, Interbase,
Ingres, and the Google App Engine (both SQL and NoSQL).
Once a table is defined and created, web2py also generates a fully functional
web-based database administration interface, called appadmin, to access the
database and the tables.
"default.py" is the controller:
1

def contacts():

introduction

29

grid=SQLFORM.grid(db.contact, user_signature=False)
return locals()

2
3

In web2py, URLs are mapped to Python modules and function calls. In this
case, the controller contains a single function (or "action") called contacts. An
action may return a string (the returned web page) or a Python dictionary
(a set of key:value pairs) or the set of local variables (as in this example). If
the function returns a dictionary, it is passed to a view with the same name
as the controller/function, which in turn renders the page. In this example,
the function contacts generates a select/search/create/update/delete grid
for table db.contact and returns the grid to the view.
"default/contacts.html" is the view:
1
2
3

{{extend 'layout.html'}}
Manage My Contacts
{{=grid}}

This view is called automatically by web2py after the associated controller
function (action) is executed. The purpose of this view is to render the
variables in the returned dictionary (in our case grid) into HTML. The view
file is written in HTML, but it embeds Python code delimited by the special
{{ and }} delimiters. This is quite different from the PHP code example,
because the only code embedded into the HTML is "presentation layer" code.
The "layout.html" file referenced at the top of the view is provided by web2py
and constitutes the basic layout for all web2py applications. The layout file
can easily be modified or replaced.

1.4

Why web2py

web2py is one of many web application frameworks, but it has compelling
and unique features. web2py was originally developed as a teaching tool,
with the following primary motivations:
• Easy for users to learn server-side web development without
compromising functionality.
For this reason, web2py requires no
installation and no configuration, has no dependencies (except for the

30

web2py full-stack web framework, 4th edition

source code distribution, which requires Python 2.5 and its standard
library modules), and exposes most of its functionality via a Web browser
interface.
• web2py has been stable from day one because it follows a top-down
design; i.e., its API was designed before it was implemented. Even as
new functionality has been added, web2py has never broken backwards
compatibility, and it will not break compatibility when additional
functionality is added in the future.
• web2py proactively addresses the most important security issues which
plague many modern web applications, as determined by OWASP [19]
below.
• web2py is lightweight.
Its core libraries, including the Database
Abstraction Layer, the template language, and all the helpers amount to
1.4MB. The entire source code including sample applications and images
amounts to 10.4MB.
• web2py has a small footprint and is very fast. It uses the Rocket [22]
WSGI web server developed By Timothy Farrell. It is 30% faster than
Apache with mod_proxy. Our tests also indicate that, on an average PC,
it serves an average dynamic page without database access in about 10ms.
The DAL has very low overhead, typically less than 3%.
• web2py uses Python syntax for models, controllers, and views, but does
not import models and controllers (as all the other Python frameworks
do) - instead it executes them. This means that apps can be installed,
uninstalled, and modified without having to restart the web server (even
in production), and different apps can cohexist without their modules
interfering with one another.
• web2py uses a Database Abstraction Layer (DAL) instead of an Object
Relational Mapper (ORM). From a conceptual point of view, this means
that different database tables are mapped into different instances of one
Table class and not into different classes, while records are mapped into
instances of one Row class, not into instances of the corresponding table
class. From a practical point of view, it means that SQL syntax maps

introduction

31

almost one-to-one into DAL syntax, and there is no complex metaclass
programming going on under the hood as in popular ORMs, which would
add latency.
WSGI [17, 18] (Web Server Gateway Interface) is an emerging Python
standard for communication between a web server and Python applications).
Here is a screenshot of the main web2py admin interface:

1.5

Security

The Open Web Application Security Project [19] (OWASP) is a free and open
worldwide community focused on improving the security of application
software.
OWASP has listed the top ten security issues that put web applications at
risk. That list is reproduced here, along with a description of how each issue
is addressed by web2py:
• "Cross Site Scripting (XSS): XSS flaws occur whenever an application takes
user supplied data and sends it to a web browser without first validating
or encoding that content. XSS allows attackers to execute scripts in the
victim’s browser which can hijack user sessions, deface web sites, possibly
introduce worms, etc." web2py, by default, escapes all variables rendered in the
view, preventing XSS.
• "Injection Flaws: Injection flaws, particularly SQL injection, are common
in web applications. Injection occurs when user-supplied data is sent to

32

web2py full-stack web framework, 4th edition

an interpreter as part of a command or query. The attacker’s hostile data
tricks the interpreter into executing unintended commands or changing
data." web2py includes a Database Abstraction Layer that makes SQL injection
impossible. Normally, SQL statements are not written by the developer. Instead,
SQL is generated dynamically by the DAL, ensuring that all inserted data is
properly escaped.
• "Malicious File Execution: Code vulnerable to remote file inclusion
(RFI) allows attackers to include hostile code and data, resulting in
devastating attacks, such as total server compromise." web2py allows only
exposed functions to be executed, preventing malicious file execution. Imported
functions are never exposed; only actions are exposed. web2py uses a Web-based
administration interface which makes it very easy to keep track of what is exposed
and what is not.
• "Insecure Direct Object Reference: A direct object reference occurs when a
developer exposes a reference to an internal implementation object, such
as a file, directory, database record, or key, as a URL or form parameter.
Attackers can manipulate those references to access other objects without
authorization." web2py does not expose any internal objects; moreover, web2py
validates all URLs, thus preventing directory traversal attacks. web2py also
provides a simple mechanism to create forms that automatically validate all input
values.
• "Cross Site Request Forgery (CSRF): A CSRF attack forces a logged-on
victim’s browser to send a pre-authenticated request to a vulnerable web
application, which then forces the victim’s browser to perform a hostile
action to the benefit of the attacker. CSRF can be as powerful as the web
application that it attacks." web2py prevents CSRF as well as accidental double
submission of forms by assigning a one-time random token to each form. Moreover
web2py uses UUID for session cookie.
• "Information Leakage and Improper Error Handling: Applications
can unintentionally leak information about their configuration, internal
workings, or violate privacy through a variety of application problems.
Attackers use this weakness to steal sensitive data, or conduct more
serious attacks." web2py includes a ticketing system. No error can result in

introduction

33

code being exposed to the users. All errors are logged and a ticket is issued to the
user that allows error tracking. But errors and source code are accessible only to
the administrator.
• "Broken Authentication and Session Management: Account credentials
and session tokens are often not properly protected.
Attackers
compromise passwords, keys, or authentication tokens to assume other
users’ identities." web2py provides a built-in mechanism for administrator
authentication, and it manages sessions independently for each application. The
administrative interface also forces the use of secure session cookies when the client
is not "localhost". For applications, it includes a powerful Role Based Access
Control API.
• "Insecure Cryptographic Storage:
Web applications rarely use
cryptographic functions properly to protect data and credentials.
Attackers use weakly protected data to conduct identity theft and other
crimes, such as credit card fraud." web2py uses the MD5 or the HMAC+SHA512 hash algorithms to protect stored passwords. Other algorithms are also
available.
• "Insecure Communications: Applications frequently fail to encrypt
network traffic when it is necessary to protect sensitive communications."
web2py includes the SSL-enabled [21] Rocket WSGI server, but it can also use
Apache or Lighttpd and mod_ssl to provide SSL encryption of communications.
• "Failure to Restrict URL Access: Frequently an application only protects
sensitive functionality by preventing the display of links or URLs to
unauthorized users. Attackers can use this weakness to access and
perform unauthorized operations by accessing those URLs directly."
web2py maps URL requests to Python modules and functions. web2py provides
a mechanism for declaring which functions are public and which require
authentication and authorization. The included Role Based Access Control
API allow developers to restrict access to any function based on login, group
membership or group based permissions. The permissions are very granular and
can be combined with CRUD to allow, for example, to give access to specific tables
and/or records. web2py also allows digitally signed URL and provides API to
digitally sign ajax callbacks.

34

web2py full-stack web framework, 4th edition

web2py was reviewed for security and you can find the result of the review
in ref. [20].

1.6

In the box

You can download web2py from the official web site:
1

http://www.web2py.com

web2py is composed of the following components:
• libraries: provide core functionality of web2py and are accessible
programmatically.
• web server: the Rocket WSGI web server.
• the admin application: used to create, design, and manage other
web2py applications. admin provide a complete web-based Integrated
Development Environment (IDE) for building web2py applications. It also
includes other functionality, such as web-based testing and a web-based
shell.
• the examples application: contains documentation and interactive
examples. examples is a clone of the official web2py.com web site, and
includes epydoc documentation.
• the welcome application: the basic scaffolding template for any other
application. By default it includes a pure CSS cascading menu and user
authentication (discussed in Chapter 9).
web2py is distributed in source code, and in binary form for Microsoft
Windows and for Mac OS X.
The source code distribution can be used in any platform where Python
runs and includes the above-mentioned components. To run the source
code, you need Python 2.5 pre-installed on the system. You also need one
of the supported database engines installed. For testing and light-demand
applications, you can use the SQLite database, included with Python 2.5.

introduction

35

The binary versions of web2py (for Windows and Mac OS X) include a
Python 2.5 interpreter and the SQLite database. Technically, these two are not
components of web2py. Including them in the binary distributions enables
you to run web2py out of the box.
The following image depicts the overall web2py structure:

1.7

License

web2py is licensed under the LGPL version 3 License. The full text of the
license if available in ref. [31].
In accordance with LGPL you may:
• redistribute web2py with your apps (including official web2py binary
versions)
• release your applications which use official web2py libraries under any
license you wish
Yet you must:
• make clear in the documentation that your application uses web2py
• release any modification of the web2py libraries under the LGPLv3 license

36

web2py full-stack web framework, 4th edition

The license includes the usual disclaimer:
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT
PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST
OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR
ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE
PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY
TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE
PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
Earlier versions
Earlier versions of web2py, 1.0.*-1.90.*, were released under the GPL2 license
plus a commercial exception which, for practical purposes, was very similar
to the current LPGLv3.
Third party software distributed with web2py web2py contains third party
software under the gluon/contrib/ folder and various JavaScript and CSS
files. These files are distributed with web2py under their original licenses, as
stated in the files.

introduction

1.8

37

Acknowledgments

web2py was originally developed by and copyrighted by Massimo Di Pierro.
The first version (1.0) was released in October, 2007. Since then it has been
adopted by many users, some of whom have also contributed bug reports,
testing, debugging, patches, and proofreading of this book.
Some of the major contributors are, in alphabetical order by first name:
Alexey Nezhdanov, Alvaro Justen, Andrew Willimott, Angelo Compagnucci,
Anthony Bastardi, Antonio Ramos, Arun K. Rajeevan, Attila Csipa, Bill
Ferret, Boris Manojlovic, Branko Vukelic, Brian Meredyk, Bruno Rocha,
Carlos Galindo, Carsten Haese, Chris Clark, Chris Steel, Christian Foster
Howes, Christopher Smiga, CJ Lazell, Cliff Kachinske, Craig Younkins,
Daniel Lin, David Harrison, David Wagner, Denes Lengyel, Douglas Soares
de Andrade, Eric Vicenti, Falko Krause, Farsheed Ashouri, Fran Boon,
Francisco Gama, Fred Yanowski, Gilson Filho, Graham Dumpleton, Gyuris
Szabolcs, Hamdy Abdel-Badeea, Hans Donner, Hans Murx, Hans C. v.
Stockhausen, Ian Reinhart Geiser, Ismael Serratos, Jan Beilicke, Jonathan
Benn, Jonathan Lundell, Josh Goldfoot, Jose Jachuf, Josh Jaques, José
Vicente de Sousa, Keith Yang, Kenji Hosoda, Kyle Smith, Limodou, Lucas
D’Ávila, Marcel Leuthi, Marcel Hellkamp, Marcello Della Longa, Mariano
Reingart, Mark Larsen, Mark Moore, Markus Gritsch, Martin Hufsky, Martin
Mulone, Mateusz Banach, Miguel Lopez, Michael Willis, Michele Comitini,
Nathan Freeze, Niall Sweeny, Niccolo Polo, Nicolas Bruxer, Olaf Ferger,
Omi Chiba, Ondrej Such, Ovidio Marinho Falcao Neto, Pai, Paolo Caruccio,
Patrick Breitenbach, Phyo Arkar Lwin, Pierre Thibault, Ramjee Ganti, Robin
Bhattacharyya, Ross Peoples, Ruijun Luo, Ryan Seto, Scott Roberts, Sergey
Podlesnyi, Sharriff Aina, Simone Bizzotto, Sriram Durbha, Sterling Hankins,
Stuart Rackham, Telman Yusupov, Thadeus Burgess, Tim Michelsen, Timothy
Farrell, Yair Eshel, Yarko Tymciurak, Younghyun Jo, Vidul Nikolaev Petrov,
Vinicius Assef, Zahariash.
I am sure I forgot somebody, so I apologize.
I particularly thank Jonathan, Mariano, Bruno, Martin, Nathan, Simone,
Thadeus, Tim, Iceberg, Denes, Hans, Christian, Fran and Patrick for

38

web2py full-stack web framework, 4th edition

their major contributions to web2py and Anthony, Alvaro, Bruno, Denes,
Felipe, Graham, Jonathan, Hans, Kyle, Mark, Michele, Richard, Robin,
Roman, Scott, Shane, Sharriff, Sriram, Sterling, Stuart, Thadeus (and others)
for proofreading various versions of this book. Their contribution was
invaluable. If you find any errors in this book, they are exclusively my fault,
probably introduced by a last-minute edit. I also thank Ryan Steffen of Wiley
Custom Learning Solutions for help with publishing the first edition of this
book. web2py contains code from the following authors, whom I would like
to thank:
Guido van Rossum for Python [2], Peter Hunt, Richard Gordon, Timothy
Farrell for the Rocket [22] web server, Christopher Dolivet for EditArea [23],
Bob Ippolito for simplejson [25], Simon Cusack and Grant Edwards for
pyRTF [26], Dalke Scientific Software for pyRSS2Gen [27], Mark Pilgrim for
feedparser [28], Trent Mick for markdown2 [29], Allan Saddi for fcgi.py, Evan
Martin for the Python memcache module [30], John Resig for jQuery [32].
The cover of this book was designed by Peter Kirchner at Young Designers.
I thank Helmut Epp (provost of DePaul University), David Miller (Dean of
the College of Computing and Digital Media of DePaul University), and
Estia Eichten (Member of MetaCryption LLC), for their continuous trust and
support.
Finally, I wish to thank my wife, Claudia, and my son, Marco, for putting up
with me during the many hours I have spent developing web2py, exchanging
emails with users and collaborators, and writing this book. This book is
dedicated to them.

1.9

About this book

This book includes the following chapters, besides this introduction:
• Chapter 2 is a minimalist introduction to Python. It assumes knowledge of
both procedural and object-oriented programming concepts such as loops,
conditions, function calls and classes, and covers basic Python syntax. It
also covers examples of Python modules that are used throughout the

introduction

39

book. If you already know Python, you may skip Chapter 2.
• Chapter 3 shows how to start web2py, discusses the administrative
interface, and guides the reader through various examples of increasing
complexity: an application that returns a string, a counter application, an
image blog, and a full blown wiki application that allows image uploads
and comments, provides authentication, authorization, web services and
an RSS feed. While reading this chapter, you may need to refer to Chapter
2 for general Python syntax and to the following chapters for a more
detailed reference about the functions that are used.
• Chapter 4 covers more systematically the core structure and libraries: URL
mapping, request, response, sessions, caching, cron, internationalization
and general workflow.
• Chapter 5 is a reference for the template language used to build views. It
shows how to embed Python code into HTML, and demonstrates the use
of helpers (objects that can generate HTML).
• Chapter 6 covers the Database Abstraction Layer, or DAL. The syntax of
the DAL is presented through a series of examples.
• Chapter 7 covers forms, form validation and form processing. FORM is
the low level helper for form building. SQLFORM is the high level form
builder. In Chapter 7 we also discuss the Create/Read/Update/Delete
(CRUD) API.
• Chapter 8 covers communication with as sending emails and SMSes.
• Chapter 9 covers authentication, authorization and the extensible RoleBased Access Control mechanism available in web2py. Mail configuration
and CAPTCHA are also discussed here, since they are used for
authentication. In the third edition of the book we have added extensive
coverage of integration with third-party authentication mechanisms such
as OpenID, OAuth, Google, Facebook, LinkedIn, etc.
• Chapter 10 is about creating web services in web2py. We provide examples
of integration with the Google Web Toolkit via Pyjamas, and with Adobe
Flash via PyAMF.

40

web2py full-stack web framework, 4th edition

• Chapter 11 is about web2py and jQuery recipes. web2py is designed
mainly for server-side programming, but it includes jQuery, since we have
found it to be the best open-source JavaScript library available for effects
and Ajax. In this chapter, we discuss how to effectively use jQuery with
web2py.
• Chapter 12 discusses web2py components and plugins as a way to build
modular applications. We provide an example of a plugin that implements
many commonly used functionality, such as charting, comments, tagging,
and wiki.
• Chapter 13 is about production deployment of web2py applications. We
mainly address three possible production scenarios: on a Linux web
server or a set of servers (which we consider the main deployment
alternative), running as a service on a Microsoft Windows environment,
and deployment on the Google Applications Engine. In this chapter, we
also discuss security and scalability issues.
• Chapter 14 contains a variety of other recipes to solve specific tasks,
including upgrades, geocoding, pagination, the Twitter API, and more.
This book only covers basic web2py functionalities and the API that ships
with web2py. This book does not cover web2py appliances (i.e. ready made
applications).
You can download web2py appliances from the corresponding web site [34].
You can find additional topics discussed on AlterEgo [35], the interactive
web2py FAQ.
This book has been written using the markmin syntax and automatically
converted to HTML, LaTeX and PDF.

1.10 Elements of style
PEP8 [36] contains good style practices when programming with Python.
You will find that web2py does not always follow these rules. This is not
because of omissions or negligence; it is our belief that the users of web2py

introduction

41

should follow these rules and we encourage it. We chose not to follow some
of those rules when defining web2py helper objects in order to minimize the
probability of name conflict with objects defined by the user.
For example, the class that represents a 
 is called DIV, while according
to the Python style reference it should have been called Div. We believe that,
for this specific example that using an all-upper-case "DIV" is a more natural
choice. Moreover, this approach leaves programmers free to create a class
called "Div" if they choose to do so. Our syntax also maps naturally into the
DOM notation of most browsers (including, for example, Firefox).
According to the Python style guide, all-upper-case strings should be
used for constants and not variables. Continuing with our example, even
considering that DIV is a class, it is a special class that should never
be modified by the user because doing so would break other web2py
applications. Hence, we believe this qualifies the DIV class as something that
should be treated as a constant, further justifying our choice of notation.
In summary, the following conventions are followed:
• HTML helpers and validators are all upper case for the reasons discussed
above (for example DIV, A, FORM, URL).
• The translator object T is upper case despite the fact that it is an instance
of a class and not a class itself. Logically the translator object performs
an action similar to the HTML helpers, it affects rendering part of the
presentation. Also, T needs to be easy to locate in the code and must have
a short name.
• DAL classes follow the Python style guide (first letter capitalized), for
example Table, Field, Query, Row, Rows, etc.
In all other cases we believe we have followed, as much as possible, the
Python Style Guide (PEP8). For example all instance objects are lower-case
(request, response, session, cache), and all internal classes are capitalized.
In all the examples of this book, web2py keywords are shown in bold, while
strings and comments are shown in italic.

2
The Python language

2.1

About Python

Python is a general-purpose high-level programming language. Its design
philosophy emphasizes programmer productivity and code readability. It
has a minimalist core syntax with very few basic commands and simple
semantics, but it also has a large and comprehensive standard library,
including an Application Programming Interface (API) to many of the
underlying operating system (OS) functions. Python code, while minimalist,
defines built-in objects such as linked lists (list), tuples (tuple), hash tables
(dict), and arbitrarily long integers (long).
Python supports multiple programming paradigms, including objectoriented (class), imperative (def), and functional (lambda) programming.
Python has a dynamic type system and automatic memory management
using reference counting (similar to Perl, Ruby, and Scheme).
Python was first released by Guido van Rossum in 1991. The language has
an open, community-based development model managed by the non-profit
Python Software Foundation. There are many interpreters and compilers that
implement the Python language, including one in Java (Jython) but, in this
brief review, we refer to the reference C implementation created by Guido.
You can find many tutorials, the official documentation and library references

44

web2py full-stack web framework, 4th edition

of the language on the official Python website. [2]
For additional Python references, we can recommend the books in ref. [37]
and ref. [38].
You may skip this chapter if you are already familiar with the Python
language.

2.2

Starting up

The binary distributions of web2py for Microsoft Windows or Apple OS X
come packaged with the Python interpreter built into the distribution file
itself.
You can start it on Windows with the following command (type at the DOS
prompt):
1

web2py.exe -S welcome

On Apple OS X, enter the following command type in a Terminal window
(assuming you’re in the same folder as web2py.app):
1

./web2py.app/Contents/MacOS/web2py -S welcome

On a Linux or other Unix box, chances are that you have Python already
installed. If so, at a shell prompt type:
1

python web2py.py -S welcome

If you do not have Python 2.5 (or later 2.x) already installed, you will have to
download and install it before running web2py.
The -S welcome command line option instructs web2py to run the interactive
shell as if the commands were executed in a controller for the welcome
application, the web2py scaffolding application. This exposes almost all
web2py classes, objects and functions to you. This is the only difference
between the web2py interactive command line and the normal Python
command line.
The admin interface also provides a web-based shell for each application.
You can access the one for the "welcome" application at.

the python language

1

45

http://127.0.0.1:8000/admin/shell/index/welcome

You can try all the examples in this chapter using the normal shell or the
web-based shell.

2.3

help, dir

The Python language provides two commands to obtain documentation
about objects defined in the current scope, both built-in and user-defined.
We can ask for help about an object, for example "1":
1
2

>>> help(1)
Help on int object:

3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

class int(object)
| int(x[, base]) -> integer
|
| Convert a string or number to an integer, if possible. A floating point
| argument will be truncated towards zero (this does not include a string
| representation of a floating point number!) When converting a string, use
| the optional base. It is an error to supply a base when converting a
| non-string. If the argument is outside the integer range a long object
| will be returned instead.
|
| Methods defined here:
|
| __abs__(...)
|
x.__abs__() <==> abs(x)
...

and, since "1" is an integer, we get a description about the int class and all
its methods. Here the output has been truncated because it is very long and
detailed.
Similarly, we can obtain a list of methods of the object "1" with the command
dir:
1
2
3
4
5
6

>>> dir(1)
['__abs__', '__add__', '__and__', '__class__', '__cmp__', '__coerce__',
'__delattr__', '__div__', '__divmod__', '__doc__', '__float__',
'__floordiv__', '__getattribute__', '__getnewargs__', '__hash__', '__hex__',
'__index__', '__init__', '__int__', '__invert__', '__long__', '__lshift__',
'__mod__', '__mul__', '__neg__', '__new__', '__nonzero__', '__oct__',

46

7
8
9
10
11

web2py full-stack web framework, 4th edition

'__or__', '__pos__', '__pow__', '__radd__', '__rand__', '__rdiv__',
'__rdivmod__', '__reduce__', '__reduce_ex__', '__repr__', '__rfloordiv__',
'__rlshift__', '__rmod__', '__rmul__', '__ror__', '__rpow__', '__rrshift__',
'__rshift__', '__rsub__', '__rtruediv__', '__rxor__', '__setattr__',
'__str__', '__sub__', '__truediv__', '__xor__']

2.4

Types

Python is a dynamically typed language, meaning that variables do not have
a type and therefore do not have to be declared. Values, on the other hand,
do have a type. You can query a variable for the type of value it contains:
1
2
3
4
5
6
7
8
9

>>> a = 3
>>> print type(a)

>>> a = 3.14
>>> print type(a)

>>> a = 'hello python'
>>> print type(a)


Python also includes, natively, data structures such as lists and dictionaries.

2.4.1

str

Python supports the use of two different types of strings: ASCII strings
and Unicode strings. ASCII strings are delimited by ’...’, "..." or by ’..’ or
"""...""". Triple quotes delimit multiline strings. Unicode strings start with a u
followed by the string containing Unicode characters. A Unicode string can
be converted into an ASCII string by choosing an encoding for example:
1
2
3

>>> a = 'this is an ASCII string'
>>> b = u'This is a Unicode string'
>>> a = b.encode('utf8')

After executing these three commands, the resulting a is an ASCII string
storing UTF8 encoded characters. By design, web2py uses UTF8 encoded
strings internally.

the python language

47

It is also possible to write variables into strings in various ways:
1
2
3
4
5
6

>>> print
number is
>>> print
number is
>>> print
number is

'number is ' + str(3)
3
'number is %s' % (3)
3
'number is %(number)s' % dict(number=3)
3

The last notation is more explicit and less error prone, and is to be preferred.
Many Python objects, for example numbers, can be serialized into strings
using str or repr. These two commands are very similar but produce slightly
different output. For example:
1
2
3
4

>>> for i in [3, 'hello']:
print str(i), repr(i)
3 3
hello 'hello'

For user-defined classes, str and repr can be defined/redefined using the
special operators __str__ and __repr__. These are briefly described later on;
for more, refer to the official Python documentation [39]. repr always has a
default value.
Another important characteristic of a Python string is that, like a list, it is an
iterable object.
1
2
3
4
5
6
7

>>> for i in 'hello':
print i
h
e
l
l
o

2.4.2

list

The main methods of a Python list are append, insert, and delete:
1
2
3
4

>>> a = [1, 2, 3]
>>> print type(a)

>>> a.append(8)

48

5
6
7
8
9
10

>>>
>>>
>>>
[2,
>>>
4

web2py full-stack web framework, 4th edition

a.insert(2, 7)
del a[0]
print a
7, 3, 8]
print len(a)

Lists can be sliced:
1
2
3
4
5
6

>>>
[2,
>>>
[7,
>>>
[3,

print a[:3]
7, 3]
print a[1:]
3, 8]
print a[-2:]
8]

and concatenated:
1
2
3
4

>>>
>>>
>>>
[2,

a = [2, 3]
b = [5, 6]
print a + b
3, 5, 6]

A list is iterable; you can loop over it:
1
2
3
4
5
6

>>> a = [1, 2, 3]
>>> for i in a:
print i
1
2
3

The elements of a list do not have to be of the same type; they can be any
type of Python object.
There is a very common situation for which a list comprehension can be used.
Consider the following code:
1
2
3
4
5
6
7

>>> a = [1,2,3,4,5]
>>> b = []
>>> for x in a:
if x % 2 == 0:
b.append(x * 3)
>>> b
[6, 12]

the python language

49

This code clearly processes a list of items, selects and modifies a subset of the
input list, and creates a new result list, and this code can be entirely replaced
with the following list comprehension:
1
2
3
4

>>>
>>>
>>>
[6,

a = [1,2,3,4,5]
b = [x * 3 for x in a if x % 2 == 0]
b
12]

2.4.3

tuple

A tuple is like a list, but its size and elements are immutable, while in a list
they are mutable. If a tuple element is an object, the object attributes are
mutable. A tuple is delimited by round brackets.
1

>>> a = (1, 2, 3)

So while this works for a list:
1
2
3
4

>>>
>>>
>>>
[1,

a = [1, 2, 3]
a[1] = 5
print a
5, 3]

the element assignment does not work for a tuple:
1
2
3
4
5
6
7

>>> a = (1, 2, 3)
>>> print a[1]
2
>>> a[1] = 5
Traceback (most recent call last):
File "", line 1, in 
TypeError: 'tuple' object does not support item assignment

A tuple, like a list, is an iterable object. Notice that a tuple consisting of a
single element must include a trailing comma, as shown below:
1
2
3
4
5
6

>>> a = (1)
>>> print type(a)

>>> a = (1,)
>>> print type(a)


50

web2py full-stack web framework, 4th edition

Tuples are very useful for efficient packing of objects because of their
immutability, and the brackets are often optional:
1
2
3
4
5
6

>>> a = 2, 3, 'hello'
>>> x, y, z = a
>>> print x
2
>>> print z
hello

2.4.4

dict

A Python dict-ionary is a hash table that maps a key object to a value object.
For example:
1
2
3
4
5
6
7
8
9

>>> a = {'k':'v', 'k2':3}
>>> a['k']
v
>>> a['k2']
3
>>> a.has_key('k')
True
>>> a.has_key('v')
False

Keys can be of any hashable type (int, string, or any object whose class
implements the __hash__ method). Values can be of any type. Different keys
and values in the same dictionary do not have to be of the same type. If the
keys are alphanumeric characters, a dictionary can also be declared with the
alternative syntax:
1
2
3
4
5

>>> a = dict(k='v', h2=3)
>>> a['k']
v
>>> print a
{'k':'v', 'h2':3}

Useful methods are has_key, keys, values and items:
1
2
3
4
5

>>> a = dict(k='v', k2=3)
>>> print a.keys()
['k', 'k2']
>>> print a.values()
['v', 3]

the python language

6
7

51

>>> print a.items()
[('k', 'v'), ('k2', 3)]

The items method produces a list of tuples, each containing a key and its
associated value.
Dictionary elements and list elements can be deleted with the command del:
1
2
3
4
5
6
7
8

>>> a = [1, 2, 3]
>>> del a[1]
>>> print a
[1, 3]
>>> a = dict(k='v', h2=3)
>>> del a['h2']
>>> print a
{'k':'v'}

Internally, Python uses the hash operator to convert objects into integers, and
uses that integer to determine where to store the value.
1
2

>>> hash("hello world")
-1500746465

2.5

About indentation

Python uses indentation to delimit blocks of code. A block starts with a
line ending in colon, and continues for all lines that have a similar or higher
indentation as the next line. For example:
1
2
3
4
5
6
7
8

>>> i = 0
>>> while i < 3:
>>>
print i
>>>
i = i + 1
>>>
0
1
2

It is common to use four spaces for each level of indentation. It is a good
policy not to mix tabs with spaces, which can result in (invisible) confusion.

52

2.6

web2py full-stack web framework, 4th edition

for...in

In Python, you can loop over iterable objects:
1
2
3
4
5
6
7

>>> a = [0, 1, 'hello', 'python']
>>> for i in a:
print i
0
1
hello
python

One common shortcut is xrange, which generates an iterable range without
storing the entire list of elements.
1
2
3
4
5
6

>>> for i in xrange(0, 4):
print i
0
1
2
3

This is equivalent to the C/C++/C#/Java syntax:
1

for(int i=0; i<4; i=i+1) { print(i); }

Another useful command is enumerate, which counts while looping:
1
2
3
4
5
6
7

>>> a = [0, 1, 'hello', 'python']
>>> for i, j in enumerate(a):
print i, j
0 0
1 1
2 hello
3 python

There is also a keyword range(a, b, c) that returns a list of integers starting
with the value a, incrementing by c, and ending with the last value smaller
than b, a defaults to 0 and c defaults to 1. xrange is similar but does not
actually generate the list, only an iterator over the list; thus it is better for
looping.
You can jump out of a loop using break
1
2

>>> for i in [1, 2, 3]:
print i

the python language

break

3
4

53

1

You can jump to the next loop iteration without executing the entire code
block with continue
1
2
3
4
5
6
7

>>> for i in [1, 2, 3]:
print i
continue
print 'test'
1
2
3

2.7

while

The while loop in Python works much as it does in many other programming
languages, by looping an indefinite number of times and testing a condition
before each iteration. If the condition is False, the loop ends.
1
2
3
4
5

>>> i = 0
>>> while i < 10:
i = i + 1
>>> print i
10

There is no loop...until construct in Python.

2.8

if...elif...else

The use of conditionals in Python is intuitive:
1
2
3
4
5
6
7
8
9
10

>>> for
>>>
>>>
>>>
>>>
>>>
>>>
zero
one
other

i in range(3):
if i == 0:
print 'zero'
elif i == 1:
print 'one'
else:
print 'other'

54

web2py full-stack web framework, 4th edition

"elif" means "else if". Both elif and else clauses are optional. There can be
more than one elif but only one else statement. Complex conditions can be
created using the not, and and or operators.
1
2
3

>>> for i in range(3):
>>>
if i == 0 or (i == 1 and i + 1 == 2):
>>>
print '0 or 1'

2.9

try...except...else...finally

Python can throw - pardon, raise - Exceptions:
1
2
3
4
5
6
7
8
9
10

>>> try:
>>>
a = 1 / 0
>>> except Exception, e:
>>>
print 'oops: %s' % e
>>> else:
>>>
print 'no problem here'
>>> finally:
>>>
print 'done'
oops: integer division or modulo by zero
done

If the exception is raised, it is caught by the except clause, which is executed,
while the else clause is not. If no exception is raised, the except clause is not
executed, but the else one is. The finally clause is always executed.
There can be multiple except clauses for different possible exceptions:
1
2
3
4
5
6
7

>>> try:
>>>
raise SyntaxError
>>> except ValueError:
>>>
print 'value error'
>>> except SyntaxError:
>>>
print 'syntax error'
syntax error

The else and finally clauses are optional.
Here is a list of built-in Python exceptions + HTTP (defined by web2py)
1
2
3

BaseException
+-- HTTP (defined by web2py)
+-- SystemExit

the python language

4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

+-- KeyboardInterrupt
+-- Exception
+-- GeneratorExit
+-- StopIteration
+-- StandardError
|
+-- ArithmeticError
|
|
+-- FloatingPointError
|
|
+-- OverflowError
|
|
+-- ZeroDivisionError
|
+-- AssertionError
|
+-- AttributeError
|
+-- EnvironmentError
|
|
+-- IOError
|
|
+-- OSError
|
|
+-- WindowsError (Windows)
|
|
+-- VMSError (VMS)
|
+-- EOFError
|
+-- ImportError
|
+-- LookupError
|
|
+-- IndexError
|
|
+-- KeyError
|
+-- MemoryError
|
+-- NameError
|
|
+-- UnboundLocalError
|
+-- ReferenceError
|
+-- RuntimeError
|
|
+-- NotImplementedError
|
+-- SyntaxError
|
|
+-- IndentationError
|
|
+-- TabError
|
+-- SystemError
|
+-- TypeError
|
+-- ValueError
|
|
+-- UnicodeError
|
|
+-- UnicodeDecodeError
|
|
+-- UnicodeEncodeError
|
|
+-- UnicodeTranslateError
+-- Warning
+-- DeprecationWarning
+-- PendingDeprecationWarning
+-- RuntimeWarning
+-- SyntaxWarning
+-- UserWarning
+-- FutureWarning
+-- ImportWarning
+-- UnicodeWarning

55

56

web2py full-stack web framework, 4th edition

For a detailed description of each of them, refer to the official Python
documentation. web2py exposes only one new exception, called HTTP. When
raised, it causes the program to return an HTTP error page (for more on this
refer to Chapter 4).
Any object can be raised as an exception, but it is good practice to raise
objects that extend one of the built-in exception classes.

2.10

def...return

Functions are declared using def. Here is a typical Python function:
1
2
3
4

>>> def f(a, b):
return a + b
>>> print f(4, 2)
6

There is no need (or way) to specify types of the arguments or the return
type(s). In this example, a function f is defined that can take two arguments.
Functions are the first code syntax feature described in this chapter to
introduce the concept of scope, or namespace. In the above example, the
identifiers a and b are undefined outside of the scope of function f:
1
2
3
4
5
6
7
8
9

>>> def f(a):
return a + 1
>>> print f(1)
2
>>> print a
Traceback (most recent call last):
File "", line 1, in 
print a
NameError: name 'a' is not defined

Identifiers defined outside of function scope are accessible within the
function; observe how the identifier a is handled in the following code:
1
2
3
4
5
6

>>> a = 1
>>> def f(b):
return a + b
>>> print f(1)
2
>>> a = 2

the python language

7
8
9
10
11
12
13
14
15
16

57

>>> print f(1) # new value of a is used
3
>>> a = 1 # reset a
>>> def g(b):
a = 2 # creates a new local a
return a + b
>>> print g(2)
4
>>> print a # global a is unchanged
1

If a is modified, subsequent function calls will use the new value of the global
a because the function definition binds the storage location of the identifier
a, not the value of a itself at the time of function declaration; however, if a
is assigned-to inside function g, the global a is unaffected because the new
local a hides the global value. The external-scope reference can be used in
the creation of closures:
1
2
3
4
5
6
7
8
9
10
11
12
13

>>> def f(x):
def g(y):
return x * y
return g
>>> doubler = f(2) # doubler is a new function
>>> tripler = f(3) # tripler is a new function
>>> quadrupler = f(4) # quadrupler is a new function
>>> print doubler(5)
10
>>> print tripler(5)
15
>>> print quadrupler(5)
20

Function f creates new functions; and note that the scope of the name
entirely internal to f. Closures are extremely powerful.

g

is

Function arguments can have default values, and can return multiple results:
1
2
3
4
5
6
7

>>> def f(a, b=2):
return a + b, a - b
>>> x, y = f(5)
>>> print x
7
>>> print y
3

58

web2py full-stack web framework, 4th edition

Function arguments can be passed explicitly by name, and this means that
the order of arguments specified in the caller can be different than the order
of arguments with which the function was defined:
1
2
3
4
5
6
7

>>> def f(a, b=2):
return a + b, a - b
>>> x, y = f(b=5, a=2)
>>> print x
7
>>> print y
-3

Functions can also take a runtime-variable number of arguments:
1
2
3
4
5
6
7

>>> def f(*a, **b):
return a, b
>>> x, y = f(3, 'hello', c=4, test='world')
>>> print x
(3, 'hello')
>>> print y
{'c':4, 'test':'world'}

Here arguments not passed by name (3, ’hello’) are stored in the tuple a, and
arguments passed by name (c and test) are stored in the dictionary b.
In the opposite case, a list or tuple can be passed to a function that requires
individual positional arguments by unpacking them:
1
2
3
4
5

>>> def f(a, b):
return a + b
>>> c = (1, 2)
>>> print f(*c)
3

and a dictionary can be unpacked to deliver keyword arguments:
1
2
3
4
5

>>> def f(a, b):
return a + b
>>> c = {'a':1, 'b':2}
>>> print f(**c)
3

2.10.1
lambda

lambda

provides a way to create a very short unnamed function very easily:

the python language

1
2
3

59

>>> a = lambda b: b + 2
>>> print a(3)
5

The expression "lambda [a]:[b]" literally reads as "a function with arguments
[a] that returns [b]". The lambda expression is itself unnamed, but the function
acquires a name by being assigned to identifier a. The scoping rules for def
apply to lambda equally, and in fact the code above, with respect to a, is
identical to the function declaration using def:
1
2
3
4

>>> def a(b):
return b + 2
>>> print a(3)
5

The only benefit of lambda is brevity; however, brevity can be very convenient
in certain situations. Consider a function called map that applies a function to
all items in a list, creating a new list:
1
2
3

>>> a = [1, 7, 2, 5, 4, 8]
>>> map(lambda x: x + 2, a)
[3, 9, 4, 7, 6, 10]

This code would have doubled in size had def been used instead of lambda.
The main drawback of lambda is that (in the Python implementation) the
syntax allows only for a single expression; however, for longer functions,
def can be used and the extra cost of providing a function name decreases as
the length of the function grows. Just like def, lambda can be used to curry
functions: new functions can be created by wrapping existing functions such
that the new function carries a different set of arguments:
1
2
3
4

>>> def f(a, b): return a + b
>>> g = lambda a: f(a, 3)
>>> g(2)
5

There are many situations where currying is useful, but one of those is
directly useful in web2py: caching. Suppose you have an expensive function
that checks whether its argument is prime:
1
2
3

def isprime(number):
for p in range(2, number):
if (number % p) == 0:

60

4
5

web2py full-stack web framework, 4th edition

return False
return True

This function is obviously time consuming.
Suppose you have a caching function cache.ram that takes three arguments: a
key, a function and a number of seconds.
1

value = cache.ram('key', f, 60)

The first time it is called, it calls the function f(), stores the output in a
dictionary in memory (let’s say "d"), and returns it so that value is:
1

value = d['key']=f()

The second time it is called, if the key is in the dictionary and not older
than the number of seconds specified (60), it returns the corresponding value
without performing the function call.
1

value = d['key']

How would you cache the output of the function isprime for any input? Here
is how:
1
2
3
4
5
6

>>> number = 7
>>> seconds = 60
>>> print cache.ram(str(number), lambda: isprime(number), seconds)
True
>>> print cache.ram(str(number), lambda: isprime(number), seconds)
True

The output is always the same, but the first time
is called; the second time it is not.

cache.ram

is called,

isprime

Python functions, created with either def or lambda allow re-factoring existing
functions in terms of a different set of arguments. cache.ram and cache.disk
are web2py caching functions.

2.11

class

Because Python is dynamically typed, Python classes and objects may seem
odd. In fact, you do not need to define the member variables (attributes)

the python language

61

when declaring a class, and different instances of the same class can have
different attributes. Attributes are generally associated with the instance, not
the class (except when declared as "class attributes", which is the same as
"static member variables" in C++/Java).
Here is an example:
1
2
3
4
5

>>>
>>>
>>>
>>>
3

class MyClass(object): pass
myinstance = MyClass()
myinstance.myvariable = 3
print myinstance.myvariable

Notice that pass is a do-nothing command. In this case it is used to define a
class MyClass that contains nothing. MyClass() calls the constructor of the class
(in this case the default constructor) and returns an object, an instance of the
class. The (object) in the class definition indicates that our class extends the
built-in object class. This is not required, but it is good practice.
Here is a more complex class:
1
2
3
4
5
6
7
8
9

>>> class MyClass(object):
>>>
z = 2
>>>
def __init__(self, a, b):
>>>
self.x = a, self.y = b
>>>
def add(self):
>>>
return self.x + self.y + self.z
>>> myinstance = MyClass(3, 4)
>>> print myinstance.add()
9

Functions declared inside the class are methods. Some methods have special
reserved names. For example, __init__ is the constructor. All variables are
local variables of the method except variables declared outside methods. For
example, z is a class variable, equivalent to a C++ static member variable that
holds the same value for all instances of the class.
Notice that __init__ takes 3 arguments and add takes one, and yet we call
them with 2 and 0 arguments respectively. The first argument represents,
by convention, the local name used inside the method to refer to the current
object. Here we use self to refer to the current object, but we could have used
any other name. self plays the same role as *this in C++ or this in Java, but
self is not a reserved keyword.

62

web2py full-stack web framework, 4th edition

This syntax is necessary to avoid ambiguity when declaring nested classes,
such as a class that is local to a method inside another class.

2.12 Special attributes, methods and operators
Class attributes, methods, and operators starting with a double underscore
are usually intended to be private (i.e. to be used internally but not exposed
outside the class) although this is a convention that is not enforced by the
interpreter.
Some of them are reserved keywords and have a special meaning.
Here, as an example, are three of them:
•

__len__

•

__getitem__

•

__setitem__

They can be used, for example, to create a container object that acts like a list:
1
2
3
4
5
6
7
8
9
10
11

>>>
>>>
>>>
>>>
>>>
>>>
>>>
4
>>>
>>>
[3,

class MyList(object):
def __init__(self, *a): self.a = list(a)
def __len__(self): return len(self.a)
def __getitem__(self, i): return self.a[i]
def __setitem__(self, i, j): self.a[i] = j
b = MyList(3, 4, 5)
print b[1]
b.a[1] = 7
print b.a
7, 5]

Other special operators include __getattr__ and __setattr__, which define the
get and set attributes for the class, and __sum__ and __sub__, which overload
arithmetic operators. For the use of these operators we refer the reader to
more advanced books on this topic. We have already mentioned the special
operators __str__ and __repr__.

the python language

63

2.13 File input/output
In Python you can open and write in a file with:
1
2
3

>>> file = open('myfile.txt', 'w')
>>> file.write('hello world')
>>> file.close()

Similarly, you can read back from the file with:
1
2
3

>>> file = open('myfile.txt', 'r')
>>> print file.read()
hello world

Alternatively, you can read in binary mode with "rb", write in binary mode
with "wb", and open the file in append mode "a", using standard C notation.
The read command takes an optional argument, which is the number of bytes.
You can also jump to any location in a file using seek.
You can read back from the file with read
1
2
3

>>> print file.seek(6)
>>> print file.read()
world

and you can close the file with:
1

>>> file.close()

In the standard distribution of Python, which is known as CPython, variables
are reference-counted, including those holding file handles, so CPython knows
that when the reference count of an open file handle decreases to zero, the file
may be closed and the variable disposed. However, in other implementations of
Python such as PyPy, garbage collection is used instead of reference counting,
and this means that it is possible that there may accumulate too many open file
handles at one time, resulting in an error before the gc has a chance to close
and dispose of them all. Therefore it is best to explicitly close file handles when
they are no longer needed. web2py provides two helper functions, read_file()
and write_file() inside the gluon.fileutils namespace that encapsulate the
file access and ensure that the file handles being used are properly closed.

64

web2py full-stack web framework, 4th edition

When using web2py, you do not know where the current directory is, because
it depends on how web2py is configured. The variable request.folder contains
the path to the current application. Paths can be concatenated with the
command os.path.join, discussed below.

2.14

exec, eval

Unlike Java, Python is a truly interpreted language. This means it has the
ability to execute Python statements stored in strings. For example:
1
2
3

>>> a = "print 'hello world'"
>>> exec(a)
'hello world'

What just happened? The function exec tells the interpreter to call itself and
execute the content of the string passed as argument. It is also possible to
execute the content of a string within a context defined by the symbols in a
dictionary:
1
2
3
4

>>> a = "print b"
>>> c = dict(b=3)
>>> exec(a, {}, c)
3

Here the interpreter, when executing the string a, sees the symbols defined
in c (b in the example), but does not see c or a themselves. This is different
than a restricted environment, since exec does not limit what the inner code
can do; it just defines the set of variables visible to the code.
A related function is eval, which works very much like exec except that it
expects the argument to evaluate to a value, and it returns that value.
1
2
3
4

>>> a = "3*4"
>>> b = eval(a)
>>> print b
12

the python language

2.15

65

import

The real power of Python is in its library modules. They provide a large and
consistent set of Application Programming Interfaces (APIs) to many system
libraries (often in a way independent of the operating system).
For example, if you need to use a random number generator, you can do:
1
2
3

>>> import random
>>> print random.randint(0, 9)
5

This prints a random integer between 0 and 9 (including 9), 5 in the example.
The function randint is defined in the module random. It is also possible to
import an object from a module into the current namespace:
1
2

>>> from random import randint
>>> print randint(0, 9)

or import all objects from a module into the current namespace:
1
2

>>> from random import *
>>> print randint(0, 9)

or import everything in a newly defined namespace:
1
2

>>> import random as myrand
>>> print myrand.randint(0, 9)

In the rest of this book, we will mainly use objects defined in modules
and cPickle.

os,

sys, datetime, time

All of the web2py objects are accessible via a module called gluon, and that is
the subject of later chapters. Internally, web2py uses many Python modules
(for example thread), but you rarely need to access them directly.
In the following subsections we consider those modules that are most useful.

2.15.1

os

This module provides an interface to the operating system API. For example:

66

1
2
3

web2py full-stack web framework, 4th edition

>>> import os
>>> os.chdir('..')
>>> os.unlink('filename_to_be_deleted')

Some of the os functions, such as
because they are not thread-safe.

chdir,

MUST NOT be used in web2py

is very useful; it allows the concatenation of paths in an OSindependent way:

os.path.join

1
2
3
4

>>> import os
>>> a = os.path.join('path', 'sub_path')
>>> print a
path/sub_path

System environment variables can be accessed via:
1

>>> print os.environ

which is a read-only dictionary.

2.15.2

sys

The sys module contains many variables and functions, but the one we use
the most is sys.path. It contains a list of paths where Python searches for
modules. When we try to import a module, Python looks for it in all the
folders listed in sys.path. If you install additional modules in some location
and want Python to find them, you need to append the path to that location
to sys.path.
1
2

>>> import sys
>>> sys.path.append('path/to/my/modules')

When running web2py, Python stays resident in memory, and there is only
one sys.path, while there are many threads servicing the HTTP requests. To
avoid a memory leak, it is best to check if a path is already present before
appending:
1
2
3

>>> path = 'path/to/my/modules'
>>> if not path in sys.path:
sys.path.append(path)

the python language

2.15.3

67

datetime

The use of the datetime module is best illustrated by some examples:
1
2
3
4
5

>>> import datetime
>>> print datetime.datetime.today()
2008-07-04 14:03:90
>>> print datetime.date.today()
2008-07-04

Occasionally you may need to time-stamp data based on the UTC time as
opposed to local time. In this case you can use the following function:
1
2
3

>>> import datetime
>>> print datetime.datetime.utcnow()
2008-07-04 14:03:90

The datetime module contains various classes: date, datetime, time and
timedelta. The difference between two date or two datetime or two time
objects is a timedelta:
1
2
3
4
5

>>>
>>>
>>>
>>>
1

a = datetime.datetime(2008, 1, 1, 20, 30)
b = datetime.datetime(2008, 1, 2, 20, 30)
c = b - a
print c.days

In web2py, date and datetime are used to store the corresponding SQL types
when passed to or returned from the database.

2.15.4

time

The time module differs from date and datetime because it represents time as
seconds from the epoch (beginning of 1970).
1
2
3

>>> import time
>>> t = time.time()
1215138737.571

Refer to the Python documentation for conversion functions between time in
seconds and time as a datetime.

68

web2py full-stack web framework, 4th edition

2.15.5

cPickle

This is a very powerful module. It provides functions that can serialize
almost any Python object, including self-referential objects. For example,
let’s build a weird object:
1
2
3
4

>>>
>>>
>>>
>>>

class MyClass(object): pass
myinstance = MyClass()
myinstance.x = 'something'
a = [1 ,2, {'hello':'world'}, [3, 4, [myinstance]]]

and now:
1
2
3

>>> import cPickle
>>> b = cPickle.dumps(a)
>>> c = cPickle.loads(b)

In this example, b is a string representation of a, and c is a copy of a generated
by de-serializing b. cPickle can also serialize to and de-serialize from a file:
1
2

>>> cPickle.dump(a, open('myfile.pickle', 'wb'))
>>> c = cPickle.load(open('myfile.pickle', 'rb'))

3
Overview

3.1

Startup

web2py comes in binary packages for Windows and Mac OS X. They include
the Python interpreter so you do not need to have it pre-installed. There
is also a source code version that runs on Windows, Mac, Linux, and other
Unix systems. The Windows and OS X binary versions include the necessary
Python interpreter. The source code package assumes that Python is already
installed on the computer. web2py requires no installation. To get started,
unzip the downloaded zip file for your specific operating system and execute
the corresponding web2py file.
On Windows, run:
1

web2py.exe

On OS X, run:
1

open web2py.app

On Unix and Linux, run from source by typing:
1

python2.5 web2py.py

To run web2py on Windows from source install first Mark Hammond’s "Python for
Windows extensions, then run:

70

1

web2py full-stack web framework, 4th edition

python2.5 web2py.py

The web2py program accepts various command line options which are
discussed later.
By default, at startup, web2py displays a startup window and then displays
a GUI widget that asks you to choose a one-time administrator password,
the IP address of the network interface to be used for the web server, and a
port number from which to serve requests. By default, web2py runs its web
server on 127.0.0.1:8000 (port 8000 on localhost), but you can run it on any
available IP address and port. You can query the IP address of your network
interface by opening a command line and typing ipconfig on Windows or
ifconfig on OS X and Linux. From now on we assume web2py is running
on localhost (127.0.0.1:8000). Use 0.0.0.0:80 to run web2py publicly on any of
your network interfaces.

If you do not provide an administrator password, the administration interface
is disabled. This is a security measure to prevent publicly exposing the admin
interface.
The administrative interface, admin, is only accessible from localhost unless
you run web2py behind Apache with mod_proxy. If admin detects a proxy,
the session cookie is set to secure and admin login does not work unless the
communication between the client and the proxy goes over HTTPS; this is a
security measure. All communications between the client and admin must
always be local or encrypted; otherwise an attacker would be able to perform
a man-in-the middle attack or a replay attack and execute arbitrary code on

overview

71

the server.
After the administration password has been set, web2py starts up the web
browser at the page:
1

http://127.0.0.1:8000/

If the computer does not have a default browser, open a web browser and
enter the URL.

Clicking on "administrative interface" takes you to the login page for the
administration interface.

The administrator password is the password you chose at startup. Notice
that there is only one administrator, and therefore only one administrator
password. For security reasons, the developer is asked to choose a new
password every time web2py starts unless the  option is specified.

72

web2py full-stack web framework, 4th edition

This is distinct from the authentication mechanism in web2py applications.
After the administrator logs into web2py, the browser is redirected to the
"site" page.

This page lists all installed web2py applications and allows the administrator
to manage them. web2py comes with three applications:
• An admin application, the one you are using right now.
• An examples application, with the online interactive documentation and
a replica of the web2py official website.
• A welcome application. This is the basic template for any other web2py
application. It is referred to as the scaffolding application. This is also the
application that welcomes a user at startup.
Ready-to-use web2py applications are referred to as web2py appliances. You
can download many freely available appliances from [34]. web2py users are
encouraged to submit new appliances, either in open-source or closed-source
(compiled and packed) form.
From the admin application’s site page, you can perform the following
operations:
• install an application by completing the form on the bottom right of the

overview

73

page. Give a name to the application, select the file containing a packaged
application or the URL where the application is located, and click "submit".
• uninstall an application by clicking the corresponding button. There is a
confirmation page.
• create a new application by choosing a name and clicking "create".
• package an application for distribution by clicking on the corresponding
button. A downloaded application is a tar file containing everything,
including the database. You should not untar this file; it is automatically
unpackaged by web2py when installed with admin.
• clean up an application’s temporary files, such as sessions, errors and
cache files.
• EDIT an application.
When you create a new application using admin, it starts as a clone of
the "welcome" scaffolding app with a "models/db.py" that creates a SQLite
database, connects to it, instantiates Auth, Crud and Service, configures
them. It also provides a "controller/default.py" which exposes actions "index",
"download", "user" for user management, and "call" for services. In the
following, we assume that these files have been removed; we will be creating
apps from scratch.
web2py also comes with a wizard, described later in this chapter, that can write
an alternate scaffolding code for you based on layouts and plugins available on
the web and based on high level description of the models.

3.2

Say hello

Here, as an example, we create a simple web app that displays the message
"Hello from MyApp" to the user. We will call this application "myapp". We
will also add a counter that counts how many times the same user visits the
page.
You can create a new application simply by typing its name in the form on
the top right of the site page in admin.

74

web2py full-stack web framework, 4th edition

After you press [create], the application is created as a copy of the built-in
welcome application.

To run the new application, visit:
1

http://127.0.0.1:8000/myapp

Now you have a copy of the welcome application.
To edit an application, click on the design button for the newly created
application.
The Edit page tells you what is inside the application. Every web2py
application consists of certain files, most of which fall into one of isx
categories:
• models: describe the data representation.
• controllers: describe the application logic and workflow.

overview

75

• views: describe the data presentation.
• languages: describe how to translate the application presentation to other
languages.
• modules: Python modules that belong to the application.
• static files: static images, CSS files [40, 41, 42], JavaScript files [43, 44], etc.
• plugins: groups of files designed to work together.
Everything is neatly organized following the Model-View-Controller design
pattern. Each section in the edit page corresponds to a subfolder in the
application folder.
Notice that section headings will toggle their content. Folder names under
static files are also collapsible.
Each file listed in the section corresponds to a file physically located in the
subfolder. Any operation performed on a file via the admin interface (create,
edit, delete) can be performed directly from the shell using your favorite editor.
The application contains other types of files (database, session files, error
files, etc.), but they are not listed on the edit page because they are not
created or modified by the administrator; they are created and modified by
the application itself.
The controllers contain the logic and workflow of the application. Every
URL gets mapped into a call to one of the functions in the controllers
(actions). There are two default controllers: "appadmin.py" and "default.py".
appadmin provides the database administrative interface; we do not need
it now. "default.py" is the controller that you need to edit, the one that is
called by default when no controller is specified in the URL. Edit the "index"
function as follows:

1
2

def index():
return "Hello from MyApp"

Here is what the online editor looks like:

76

web2py full-stack web framework, 4th edition

Save it and go back to the edit page. Click on the index link to visit the newly
created page.
When you visit the URL
1

http://127.0.0.1:8000/myapp/default/index

the index action in the default controller of the myapp application is called.
It returns a string that the browser displays for us. It should look like this:

Now, edit the "index" function as follows:
1
2

def index():
return dict(message="Hello from MyApp")

Also from the edit page, edit the view "default/index.html" (the view file
associated with the action) and completely replace the existing contents of
that file with the following:
1
2




overview

3
4
5
6

77


{{=message}}



Now the action returns a dictionary defining a message. When an action
returns a dictionary, web2py looks for a view with the name
and executes it. Here [extension] is the
requested extension. If no extension is specified, it defaults to "html", and
that is what we will assume here. Under this assumption, the view is an
HTML file that embeds Python code using special {{ }} tags. In particular,
in the example, the {{=message}} instructs web2py to replace the tagged code
with the value of the message returned by the action. Notice that message here
is not a web2py keyword but is defined in the action. So far we have not used
any web2py keywords.

[controller]/[function].[extension]

If web2py does not find the requested view, it uses the "generic.html" view
that comes with every application.
If an extension other than "html" is specified ("json" for example), and the
view file "[controller]/[function].json" is not found, web2py looks for the view
"generic.json". web2py comes with generic.html, generic.json, generic.xml,
and generic.rss. These generic views can be modified for each application
individually, and additional views can be added easily.
Generic views are a development tool. In production every action should have
its own view. In fact, by default, generic views are only enabled from localhost.
You can also specify a view with response.view

= ’default/something.html’

Read more on this topic in Chapter 10.
If you go back to "EDIT" and click on index, you will now see the following
HTML page:

78

web2py full-stack web framework, 4th edition

For debugging purposes you can always append
1

{{=response.toolbar()}}

to the code in a view and it will show you some useful information, including
the request, response and session objects, and list all db queries with their
timing.

3.3

Let’s count

Let’s now add a counter to this page that will count how many times the
same visitor displays the page. web2py automatically and transparently
tracks visitors using sessions and cookies. For each new visitor, it creates
a session and assigns a unique "session_id". The session is a container for
variables that are stored server-side. The unique id is sent to the browser via
a cookie. When the visitor requests another page from the same application,
the browser sends the cookie back, it is retrieved by web2py, and the
corresponding session is restored.
To use the session, modify the default controller:
1
2
3
4
5
6

def index():
if not session.counter:
session.counter = 1
else:
session.counter += 1
return dict(message="Hello from MyApp", counter=session.counter)

Notice that counter is not a web2py keyword but session is. We are asking
web2py to check whether there is a counter variable in the session and, if not,
to create one and set it to 1. If the counter is there, we ask web2py to increase
the counter by 1. Finally we pass the value of the counter to the view.
A more compact way to code the same function is this:
1
2
3

def index():
session.counter = (session.counter or 0) + 1
return dict(message="Hello from MyApp", counter=session.counter)

Now modify the view to add a line that displays the value of the counter:

overview

1
2
3
4
5
6
7

79




{{=message}}
Number of visits: {{=counter}}



When you visit the index page again (and again) you should get the following
HTML page:

The counter is associated with each visitor, and is incremented each time the
visitor reloads the page. Different visitors see different counters.

3.4

Say my name

Now create two pages (first and second), where the first page creates a form,
asks the visitor’s name, and redirects to the second page, which greets the
visitor by name.

Write the corresponding actions in the default controller:
1
2

def first():
return dict()

3
4
5

def second():
return dict()

80

web2py full-stack web framework, 4th edition

Then create a view "default/first.html" for the first action, and enter:

1
2
3
4
5
6

{{extend 'layout.html'}}
What is your name?





Finally, create a view "default/second.html" for the second action:

1
2

{{extend 'layout.html'}}
Hello {{=request.vars.visitor_name}}

In both views we have extended the basic "layout.html" view that comes with
web2py. The layout view keeps the look and feel of the two pages coherent.
The layout file can be edited and replaced easily, since it mainly contains
HTML code.
If you now visit the first page, type your name:

and submit the form, you will receive a greeting:

overview

3.5

81

Postbacks

The mechanism for form submission that we used before is very common, but
it is not good programming practice. All input should be validated and, in
the above example, the burden of validation would fall on the second action.
Thus the action that performs the validation is different from the action that
generated the form. This tends to cause redundancy in the code.
A better pattern for form submission is to submit forms to the same action
that generated them, in our example the "first". The "first" action should
receive the variables, process them, store them server-side, and redirect the
visitor to the "second" page, which retrieves the variables. This mechanism
is called a postback.

Modify the default controller to implement self-submission:
1

def first():

82

2
3
4
5

web2py full-stack web framework, 4th edition

if request.vars.visitor_name:
session.visitor_name = request.vars.visitor_name
redirect(URL('second'))
return dict()

6
7
8

def second():
return dict()

Then modify the "default/first.html" view:
1
2
3
4
5
6

{{extend 'layout.html'}}
What is your name?





and the "default/second.html" view needs to retrieve the data from the
session instead of from the request.vars:
1
2

{{extend 'layout.html'}}
Hello {{=session.visitor_name or "anonymous"}}

From the point of view of the visitor, the self-submission behaves exactly the
same as the previous implementation. We have not added validation yet, but
it is now clear that validation should be performed by the first action.
This approach is better also because the name of the visitor stays in the
session, and can be accessed by all actions and views in the applications
without having to be passed around explicitly.
Note that if the "second" action is ever called before a visitor name is set, it
will display "Hello anonymous" because session.visitor_name returns None.
Alternatively we could have added the following code in the controller
(inside the second function):
1
2

if not request.function=='first' and not session.visitor_name:
redirect(URL('first'))

This is a general mechanism that you can use to enforce authorization on
controllers, though see Chapter 9 for a more powerful method.
With web2py we can move one step further and ask web2py to generate the
form for us, including validation. web2py provides helpers (FORM, INPUT,

overview

83

TEXTAREA, and SELECT/OPTION) with the same names as the equivalent
HTML tags. They can be used to build forms either in the controller or in the
view.
For example, here is one possible way to rewrite the first action:
1
2
3
4
5
6
7

def first():
form = FORM(INPUT(_name='visitor_name', requires=IS_NOT_EMPTY()),
INPUT(_type='submit'))
if form.process().accepted:
session.visitor_name = form.vars.visitor_name
redirect(URL('second'))
return dict(form=form)

where we are saying that the FORM tag contains two INPUT tags. The
attributes of the input tags are specified by the named arguments starting
with underscore. The requires argument is not a tag attribute (because it does
not start by underscore) but it sets a validator for the value of visitor_name.
Here is yet another better wat to create the same form:
1
2
3
4
5
6

def first():
form = SQLFORM.factory(Field('visitor_name', requires=IS_NOT_EMPTY()))
if form.process().accepted:
session.visitor_name = form.vars.visitor_name
redirect(URL('second'))
return dict(form=form)

The form object can be easily serialized in HTML by embedding it in the
"default/first.html" view.
1
2
3

{{extend 'layout.html'}}
What is your name?
{{=form}}

The form.process() method applies the validators and returns the form itself.
The form.accepted variable is set to True if the form was processed and passed
validation. If the self-submitted form passes validation, it stores the variables
in the session and redirects as before. If the form does not pass validation,
error messages are inserted into the form and shown to the user, as below:

84

web2py full-stack web framework, 4th edition

In the next section we will show how forms can be generated automatically
from a model.

3.6

An image blog

Here, as another example, we wish to create a web application that allows the
administrator to post images and give them a name, and allows the visitors
of the web site to view the named images and submit comments.
As before, from the site page in admin, create a new application called images,
and navigate to the edit page:

overview

85

We start by creating a model, a representation of the persistent data in the
application (the images to upload, their names, and the comments). First,
you need to create/edit a model file which, for lack of imagination, we call
"db.py". We assume the code below will replace any existing code in "db.py".
Models and controllers must have a .py extension since they are Python code.
If the extension is not provided, it is appended by web2py. Views instead
have a .html extension since they mainly contain HTML code.
Edit the "db.py" file by clicking the corresponding "edit" button:

and enter the following:
1

db = DAL("sqlite://storage.sqlite")

2
3
4

db.define_table('image',
Field('title', unique=True),

86

5
6

web2py full-stack web framework, 4th edition

Field('file', 'upload'),
format = '%(title)s')

7
8
9
10
11
12

db.define_table('comment',
Field('image_id', db.image),
Field('author'),
Field('email'),
Field('body', 'text'))

13
14
15
16
17
18

db.image.title.requires = IS_NOT_IN_DB(db, db.image.title)
db.comment.image_id.requires = IS_IN_DB(db, db.image.id, '%(title)s')
db.comment.author.requires = IS_NOT_EMPTY()
db.comment.email.requires = IS_EMAIL()
db.comment.body.requires = IS_NOT_EMPTY()

19
20

db.comment.image_id.writable = db.comment.image_id.readable = False

Let’s analyze this line by line.
Line 1 defines a global variable called db that represents the database
connection. In this case it is a connection to a SQLite database stored in
the file "applications/images/databases/storage.sqlite". In the SQLite case,
if the database does not exist, it is created. You can change the name of the
file, as well as the name of the global variable db, but it is convenient to give
them the same name, to make it easy to remember.
Lines 3-5 define a table "image". define_table is a method of the db object.
The first argument, "image", is the name of the table we are defining. The
other arguments are the fields belonging to that table. This table has a field
called "title", a field called "file", and a field called "id" that serves as the table
primary key ("id" is not explicitly declared because all tables have an id field
by default). The field "title" is a string, and the field "file" is of type "upload".
"upload" is a special type of field used by the web2py Data Abstraction Layer
(DAL) to store the names of uploaded files. web2py knows how to upload
files (via streaming if they are large), rename them safely, and store them.
When a table is defined, web2py takes one of several possible actions:
• if the table does not exist, the table is created;
• if the table exists and does not correspond to the definition, the table is
altered accordingly, and if a field has a different type, web2py tries to

overview

87

convert its contents;
• if the table exists and corresponds to the definition, web2py does nothing.
This behavior is called "migration". In web2py migrations are automatic, but
can be disabled for each table by passing migrate=False as the last argument
of define_table.
Line 6 defines a format string for the table. It determines how a record
should be represented as a string. Notice that the format argument can also
be a function that takes a record and returns a string. For example:
1

format=lambda row: row.title

Lines 8-12 define another table called "comment". A comment has an
"author", an "email" (we intend to store the email address of the author of
the comment), a "body" of type "text" (we intend to use it to store the actual
comment posted by the author), and an "image_id" field of type reference
that points to db.image via the "id" field.
In line 14, db.image.title represents the field "title" of table "image". The
attribute requires allows you to set requirements/constraints that will be
enforced by web2py forms. Here we require that the "title" is unique:
IS_NOT_IN_DB(db, db.image.title)

Notice this is optional because it is set automatically given that

Field(’title’,

unique=True).

The objects representing these constraints are called validators. Multiple
validators can be grouped in a list. Validators are executed in the order they
appear. IS_NOT_IN_DB(a, b) is a special validator that checks that the value of
a field b for a new record is not already in a.
Line 15 requires that the field "image_id" of table "comment" is in db.image.id.
As far as the database is concerned, we had already declared this when we
defined the table "comment". Now we are explicitly telling the model that
this condition should be enforced by web2py, too, at the form processing
level when a new comment is posted, so that invalid values do not propagate
from input forms to the database. We also require that the "image_id" be
represented by the "title", ’%(title)s’, of the corresponding record.

88

web2py full-stack web framework, 4th edition

Line 20 indicates that the field "image_id" of table "comment" should
not be shown in forms, writable=False and not even in readonly forms,
readable=False.
The meaning of the validators in lines 15-17 should be obvious.
Notice that the validator
1

db.comment.image_id.requires = IS_IN_DB(db, db.image.id, '%(title)s')

can be omitted (and would be automatic) if we specify a format for referenced
table:
1

db.define_table('image', ..., format='%(title)s')

where the format can be a string or a function that takes a record and returns
a string.
Once a model is defined, if there are no errors, web2py creates an application
administration interface to manage the database. You access it via the
"database administration" link in the edit page or directly:
1

http://127.0.0.1:8000/images/appadmin

Here is a screenshot of the appadmin interface:

overview

89

This interface is coded in the controller called "appadmin.py" and the
corresponding view "appadmin.html". From now on, we will refer to this
interface simply as appadmin. It allows the administrator to insert new
database records, edit and delete existing records, browse tables, and perform
database joins.
The first time appadmin is accessed, the model is executed and the tables are
created. The web2py DAL translates Python code into SQL statements that
are specific to the selected database back-end (SQLite in this example). You
can see the generated SQL from the edit page by clicking on the "sql.log" link
under "models". Notice that the link is not present until the tables have been
created.

If you were to edit the model and access appadmin again, web2py would
generate SQL to alter the existing tables. The generated SQL is logged into
"sql.log".
Now go back to appadmin and try to insert a new image record:

90

web2py full-stack web framework, 4th edition

web2py has translated the db.image.file "upload" field into an upload form
for the file. When the form is submitted and an image file is uploaded, the
file is renamed in a secure way that preserves the extension, it is saved with
the new name under the application "uploads" folder, and the new name is
stored in the db.image.file field. This process is designed to prevent directory
traversal attacks.
Notice that each field type is rendered by a widget. Default widgets can be
overridden.
When you click on a table name in appadmin, web2py performs a select of
all records on the current table, identified by the DAL query

1

db.image.id > 0

and renders the result.

overview

91

You can select a different set of records by editing the SQL query and pressing
[Submit].
To edit or delete a single record, click on the record id number.
Because of the IS_IN_DB validator, the reference field "image_id" is rendered
by a drop-down menu. The items in the drop-down are stored as keys
(db.image.id), but are represented by their db.image.title, as specified by
the validator.
Validators are powerful objects that know how to represent fields, filter field
values, generate errors, and format values extracted from the field.
The following figure shows what happens when you submit a form that does
not pass validation:

92

web2py full-stack web framework, 4th edition

The same forms that are automatically generated by appadmin can also be
generated programmatically via the SQLFORM helper and embedded in user
applications. These forms are CSS-friendly, and can be customized.
Every application has its own appadmin; therefore, appadmin itself can be
modified without affecting other applications.
So far, the application knows how to store data, and we have seen how to
access the database via appadmin. Access to appadmin is restricted to the
administrator, and it is not intended as a production web interface for the
application; hence the next part of this walk-through. Specifically we want to
create:
• An "index" page that lists all available images sorted by title and links to
detail pages for the images.
• A "show/[id]" page that shows the visitor the requested image and allows
the visitor to view and post comments.
• A "download/[name]" action to download uploaded images.
This is represented schematically here:

overview

93

Go back to the edit page and edit the "default.py" controller, replacing its
contents with the following:
1
2
3

def index():
images = db().select(db.image.ALL, orderby=db.image.title)
return dict(images=images)

This action returns a dictionary. The keys of the items in the dictionary are
interpreted as variables passed to the view associated to the action. When
developing, if there is no view, the action is rendered by the "generic.html"
view that is provided with every web2py application.
The index action performs a select of all fields (db.image.ALL) from table
image, ordered by db.image.title. The result of the select is a Rows object
containing the records. Assign it to a local variable called images returned by
the action to the view. images is iterable and its elements are the selected rows.
For each row the columns can be accessed as dictionaries: images[0][’title’]
or equivalently as images[0].title.
If you do not write a view, the dictionary is rendered by "views/generic.html"
and a call to the index action would look like this:

You have not created a view for this action yet, so web2py renders the set of
records in plain tabular form.
Proceed to create a view for the index action. Return to admin, edit
"default/index.html" and replace its content with the following:

94

1
2
3
4
5
6
7

web2py full-stack web framework, 4th edition

{{extend 'layout.html'}}
Current Images

{{for image in images:}}
{{=LI(A(image.title, _href=URL("show", args=image.id)))}}
{{pass}}


The first thing to notice is that a view is pure HTML with special {{...}} tags.
The code embedded in {{...}} is pure Python code with one caveat: indentation
is irrelevant. Blocks of code start with lines ending in colon (:) and end in
lines beginning with the keyword pass. In some cases the end of a block is
obvious from context and the use of pass is not required.
Lines 5-7 loop over the image rows and for each row image display:
1

LI(A(image.title, _href=URL('show', args=image.id))

This is a 
...
 tag that contains an ... tag which
contains the image.title. The value of the hypertext reference (href attribute)
is:
1

URL('show', args=image.id)

i.e., the URL within the same application and controller as the current
request that calls the function called "show", passing a single argument to
the function, args=image.id. LI, A, etc. are web2py helpers that map to
the corresponding HTML tags. Their unnamed arguments are interpreted
as objects to be serialized and inserted in the tag’s innerHTML. Named
arguments starting with an underscore (for example _href) are interpreted
as tag attributes but without the underscore. For example _href is the href
attribute, _class is the class attribute, etc.
As an example, the following statement:
1

{{=LI(A('something', _href=URL('show', args=123))}}

is rendered as:
1

something

A handful of helpers (INPUT,

TEXTAREA, OPTION

and

SELECT)

also support some

overview

95

special named attributes not starting with underscore (value, and requires).
They are important for building custom forms and will be discussed later.
Go back to the edit page. It now indicates that "default.py exposes index". By
clicking on "index", you can visit the newly created page:
1

http://127.0.0.1:8000/images/default/index

which looks like:

If you click on the image name link, you are directed to:
1

http://127.0.0.1:8000/images/default/show/1

and this results in an error, since you have not yet created an action called
"show" in controller "default.py".
Let’s edit the "default.py" controller and replace its content with:
1
2
3

def index():
images = db().select(db.image.ALL, orderby=db.image.title)
return dict(images=images)

4
5
6
7
8
9
10
11
12

def show():
image = db(db.image.id==request.args(0)).select().first()
db.comment.image_id.default = image.id
form = SQLFORM(db.comment)
if form.process().accepted:
response.flash = 'your comment is posted'
comments = db(db.comment.image_id==image.id).select()
return dict(image=image, comments=comments, form=form)

13
14
15

def download():
return response.download(request, db)

96

web2py full-stack web framework, 4th edition

The controller contains two actions: "show" and "download". The "show"
action selects the image with the id parsed from the request args and all
comments related to the image. "show" then passes everything to the view
"default/show.html".
The image id referenced by:
1

URL('show', args=image.id)

in "default/index.html", can be accessed as:
action.

request.args(0)

from the "show"

The "download" action expects a filename in request.args(0), builds a path
to the location where that file is supposed to be, and sends it back to the
client. If the file is too large, it streams the file without incurring any memory
overhead.
Notice the following statements:
• Line 7 creates an insert form SQLFORM for the db.comment table using only
the specified fields.
• Line 8 sets the value for the reference field, which is not part of the input
form because it is not in the list of fields specified above.
• Line 9 processes the submitted form (the submitted form variables are in
request.vars) within the current session (the session is used to prevent
double submissions, and to enforce navigation). If the submitted form
variables are validated, the new comment is inserted in the db.comment
table; otherwise the form is modified to include error messages (for
example, if the author’s email address is invalid). This is all done in line
9!.
• Line 10 is only executed if the form is accepted, after the record is
inserted into the database table. response.flash is a web2py variable that
is displayed in the views and used to notify the visitor that something
happened.
• Line 11 selects all comments that reference the current image.
The "download" action is already defined in the "default.py" controller of the

overview

97

scaffolding application.
The "download" action does not return a dictionary, so it does not need a
view. The "show" action, though, should have a view, so return to admin
and create a new view called "default/show.html".
Edit this new file and replace its content with the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{{extend 'layout.html'}}
Image: {{=image.title}}



{{if len(comments):}}
Comments


{{for comment in comments:}}
{{=comment.author}} says {{=comment.body}}
{{pass}}

{{else:}}
No comments posted yet
{{pass}}
Post a comment
{{=form}}

This view displays the image.file by calling the "download" action inside an
 tag. If there are comments, it loops over them and displays each
one.
Here is how everything will appear to a visitor.

98

web2py full-stack web framework, 4th edition

When a visitor submits a comment via this page, the comment is stored in
the database and appended at the bottom of the page.

3.7

Adding CRUD

web2py also provides a CRUD (Create/Read/Update/Delete) API that
simplifies forms even more. To use CRUD it is necessary to define it
somewhere, such as in file "db.py":
1
2

from gluon.tools import Crud
crud = Crud(db)

These two lines are already in the scaffolding application.
The crud object provides high-level methods, for example:
1

form = crud.create(table)

that can be used to replace the programming pattern:
1
2
3
4

form = SQLFORM(table)
if form.process().accepted:
session.flash = '...'
redirect('...')

overview

99

Here, we rewrite the previous "show" action using crud and making some
more improvements:
1
2
3
4
5
6
7
8

def show():
image = db.image(request.args(0)) or redirect(URL('index'))
db.comment.image_id.default = image.id
form = crud.create(db.comment,
message='your comment is posted',
next=URL(args=image.id))
comments = db(db.comment.image_id==image.id).select()
return dict(image=image, comments=comments, form=form)

First of all notice we have used the syntax
1

db.image(request.args(0)) or redirect(...)

to fetch the required record. Since ‘table(id) returns None if the record is
not found, we can use or redirect(...) in this case in one line.
The next argument of crud.create is the URL to redirect to after the form is
accepted. The message argument is the one to be displayed upon acceptance.
You can read more about CRUD in Chapter 7.

3.8

Adding Authentication

The web2py API for Role-Based Access Control is quite sophisticated, but
for now we will limit ourselves to restricting access to the show action to
authenticated users, deferring a more detailed discussion to Chapter 9.
To limit access to authenticated users, we need to complete three steps. In a
model, for example "db.py", we need to add:
1
2
3

from gluon.tools import Auth
auth = Auth(db)
auth.define_tables()

In our controller, we need to add one action:
1
2

def user():
return dict(form=auth())

100

web2py full-stack web framework, 4th edition

This is sufficient to enable login, register, logout, etc. pages. The default
layout will also show options to the corresponding pages in the top right
corner.

We can now decorate the functions that we want to restrict, for example:
1
2
3
4
5
6
7
8

@auth.requires_login()
def show():
image = db.image(request.args(0)) or redirect(URL('index'))
db.comment.image_id.default = image.id
form = crud.create(db.comment, next=URL(args=image.id),
message='your comment is posted')
comments = db(db.comment.image_id==image.id).select()
return dict(image=image, comments=comments, form=form)

Any attempt to access
1

http://127.0.0.1:8000/images/default/show/[image_id]

will require login. If the user is not logged it, the user will be redirected to
1

http://127.0.0.1:8000/images/default/user/login

overview

101

The user function also exposes, among others, the following actions:

1
2
3
4
5
6
7
8
9
10

http://127.0.0.1:8000/images/default/user/logout
http://127.0.0.1:8000/images/default/user/register
http://127.0.0.1:8000/images/default/user/profile
http://127.0.0.1:8000/images/default/user/change_password
http://127.0.0.1:8000/images/default/user/request_reset_password
http://127.0.0.1:8000/images/default/user/retrieve_username
http://127.0.0.1:8000/images/default/user/retrieve_password
http://127.0.0.1:8000/images/default/user/verify_email
http://127.0.0.1:8000/images/default/user/impersonate
http://127.0.0.1:8000/images/default/user/not_authorized

Now, a first-time user needs to register in order to be able to log in and read
or post comments.
Both the auth object and the user function are already defined in the scaffolding
application. The auth object is highly customizable and can deal with email
verification, registration approvals, CAPTCHA, and alternate login methods
via plugins.

102

3.8.1

web2py full-stack web framework, 4th edition

Adding grids

We can improve this further using the SQLFORM.grid and SQLFORM.smartgrid
gadgets to create a management interface for our application:
1
2
3
4

@auth.requires_membership('manager')
def manage():
grid = SQLFORM.smartgrid(db.image)
return dict(grid=grid)

with associated "views/default/manage.html"
1
2
3

{{extend 'layout.html'}}
Management Interface
{{=grid}}

Using appadmin create a group "manager" and make some users members
of the group. They will not be able to access
1

http://127.0.0.1:8000/images/default/manage

and browse, search:

create, update and delete images and their comments:

overview

3.9

103

Configuring the layout

You can configure the default layout by editing "views/layout.html" but you
can also configure it without editing the HTML. In fact, the "static/base.css"
stylesheet is well documented and described in Chapter 5. You can change
color, columns, size, borders and background without editing the HTML. If
you want to edit the menu, the title or the subtitle, you can do so in any
model file. The scaffolding app, sets default values of these parameters in
the file "models/menu.py":
1
2
3
4
5
6

response.title = request.application
response.subtitle = T('customize me!')
response.meta.author = 'you'
response.meta.description = 'describe your app'
response.meta.keywords = 'bla bla bla'
response.menu = [ [ 'Index', False, URL('index') ] ]

104

web2py full-stack web framework, 4th edition

3.10 A wiki
In this section, we build a wiki, from scratch and without using the extended
functionality provided by plugin_wiki which is described in chapter 12. The
visitor will be able to create pages, search them (by title), and edit them.
The visitor will also be able to post comments (exactly as in the previous
applications), and also post documents (as attachments to the pages) and
link them from the pages. As a convention, we adopt the Markmin syntax
for our wiki syntax. We will also implement a search page with Ajax, an RSS
feed for the pages, and a handler to search the pages via XML-RPC [46].
The following diagram lists the actions that we need to implement and the
links we intend to build among them.

overview

105

Start by creating a new scaffolding app, naming it "mywiki".
The model must contain three tables: page, comment, and document. Both
comment and document reference page because they belong to page. A
document contains a file field of type upload as in the previous images
application.
Here is the complete model:
1

db = DAL('sqlite://storage.sqlite')

2
3
4
5
6

from gluon.tools import *
auth = Auth(db)
auth.define_tables()
crud = Crud(db)

7
8
9
10
11
12
13

db.define_table('page',
Field('title'),
Field('body', 'text'),
Field('created_on', 'datetime', default=request.now),
Field('created_by', db.auth_user, default=auth.user_id),
format='%(title)s')

14
15
16
17
18
19

db.define_table('comment',
Field('page_id', db.page),
Field('body', 'text'),
Field('created_on', 'datetime', default=request.now),
Field('created_by', db.auth_user, default=auth.user_id))

20
21
22
23
24
25
26
27

db.define_table('document',
Field('page_id', db.page),
Field('name'),
Field('file', 'upload'),
Field('created_on', 'datetime', default=request.now),
Field('created_by', db.auth_user, default=auth.user_id),
format='%(name)s')

28
29
30
31
32

db.page.title.requires = IS_NOT_IN_DB(db, 'page.title')
db.page.body.requires = IS_NOT_EMPTY()
db.page.created_by.readable = db.page.created_by.writable = False
db.page.created_on.readable = db.page.created_on.writable = False

33
34
35
36
37

db.comment.body.requires = IS_NOT_EMPTY()
db.comment.page_id.readable = db.comment.page_id.writable = False
db.comment.created_by.readable = db.comment.created_by.writable = False
db.comment.created_on.readable = db.comment.created_on.writable = False

38
39

db.document.name.requires = IS_NOT_IN_DB(db, 'document.name')

106

40
41
42

web2py full-stack web framework, 4th edition

db.document.page_id.readable = db.document.page_id.writable = False
db.document.created_by.readable = db.document.created_by.writable = False
db.document.created_on.readable = db.document.created_on.writable = False

Edit the controller "default.py" and create the following actions:
• index: list all wiki pages
• create: post another wiki page
• show: show a wiki page and its comments, and append comments
• edit: edit an existing page
• documents: manage the documents attached to a page
• download: download a document (as in the images example)
• search: display a search box and, via an Ajax callback, return all matching
titles as the visitor types
• callback: the Ajax callback function. It returns the HTML that gets
embedded in the search page while the visitor types.
Here is the "default.py" controller:
1
2
3
4
5
6
7
8

def index():
""" this controller returns a dictionary rendered by the view
it lists all wiki pages
>>> index().has_key('pages')
True
"""
pages = db().select(db.page.id,db.page.title,orderby=db.page.title)
return dict(pages=pages)

9
10
11
12
13
14

@auth.requires_login()
def create():
"creates a new empty wiki page"
form = crud.create(db.page, next=URL('index'))
return dict(form=form)

15
16
17
18
19
20
21
22

def show():
"shows a wiki page"
this_page = db.page(request.args(0)) or redirect(URL('index'))
db.comment.page_id.default = this_page.id
form = crud.create(db.comment) if auth.user else None
pagecomments = db(db.comment.page_id==this_page.id).select()
return dict(page=this_page, comments=pagecomments, form=form)

overview

107

23
24
25
26
27
28
29
30

@auth.requires_login()
def edit():
"edit an existing wiki page"
this_page = db.page(request.args(0)) or redirect(URL('index'))
form = crud.update(db.page, this_page,
next=URL('show',args=request.args))
return dict(form=form)

31
32
33
34
35
36
37
38
39

@auth.requires_login()
def documents():
"browser, edit all documents attached to a certain page"
page = db.page(request.args(0)) or redirect(URL('index'))
db.document.page_id.default = page.id
db.document.page_id.writable = False
grid = SQLFORM.grid(db.document.page_id==page.id,args=[page.id])
return dict(page=page, grid=grid)

40
41
42

def user():
return dict(form=auth())

43
44
45
46

def download():
"allows downloading of documents"
return response.download(request, db)

47
48
49
50
51
52

def search():
"an ajax wiki search page"
return dict(form=FORM(INPUT(_id='keyword',_name='keyword',
_onkeyup="ajax('callback', ['keyword'], 'target');")),
target_div=DIV(_id='target'))

53
54
55
56
57
58
59

def callback():
"an ajax callback that returns a 
 of links to wiki pages"
query = db.page.title.contains(request.vars.keyword)
pages = db(query).select(orderby=db.page.title)
links = [A(p.title, _href=URL('show',args=p.id)) for p in pages]
return UL(*links)

Lines 2-6 provide a comment for the index action. Lines 4-5 inside the
comment are interpreted by python as test code (doctest). Tests can be run
via the admin interface. In this case the tests verify that the index action runs
without errors.
Lines 18, 27, and 35 try to fetch a page record with the id in request.args(0).
Lines 13, 20 define and process create forms for a new page and a new
comment and.

108

web2py full-stack web framework, 4th edition

Line 28 defines and processes an update form for a wiki page.
Line 38 creates a grid object that allows to browser, add and update the
comments linked to a page.
Some magic happens in line 51. The onkeyup attribute of the INPUT tag
"keyword" is set. Every time the visitor releases a key, the JavaScript code
inside the onkeyup attribute is executed, client-side. Here is the JavaScript
code:

1

ajax('callback', ['keyword'], 'target');

is a JavaScript function defined in the file "web2py.js" which is included
by the default "layout.html". It takes three parameters: the URL of the action
that performs the synchronous callback, a list of the IDs of variables to be
sent to the callback (["keyword"]), and the ID where the response has to be
inserted ("target").

ajax

As soon as you type something in the search box and release a key, the
client calls the server and sends the content of the ’keyword’ field, and,
when the sever responds, the response is embedded in the page itself as
the innerHTML of the ’target’ tag.
The ’target’ tag is a DIV defined in line 52. It could have been defined in the
view as well.
Here is the code for the view "default/create.html":

1
2
3

{{extend 'layout.html'}}
Create new wiki page
{{=form}}

If you visit the create page, you see the following:

overview

Here is the code for the view "default/index.html":

1
2
3
4
5
6
7

{{extend 'layout.html'}}
Available wiki pages
[ {{=A('search', _href=URL('search'))}} ]

{{for page in pages:}}
{{=LI(A(page.title, _href=URL('show', args=page.id)))}}
{{pass}}
[ {{=A('create page', _href=URL('create'))}} ]

It generates the following page:

109

110

web2py full-stack web framework, 4th edition

Here is the code for the view "default/show.html":
1
2
3
4
5
6
7
8
9
10
11
12

{{extend 'layout.html'}}
{{=page.title}}
[ {{=A('edit', _href=URL('edit', args=request.args))}}
| {{=A('documents', _href=URL('documents', args=request.args))}} ]

{{=MARKMIN(page.body)}}
Comments
{{for comment in comments:}}
{{=db.auth_user[comment.created_by].first_name}} on {{=comment.created_on}}
says {{=comment.body}}
{{pass}}
Post a comment
{{=form}}

If you wish to use markdown syntax instead of markmin syntax:
1

from gluon.contrib.markdown import WIKI

and use WIKI instead of the MARKMIN helper. Alternatively, you can choose to
accept raw HTML instead of markmin syntax. In this case you would replace:
1

{{=MARKMIN(page.body)}}

with:
1

{{=XML(page.body)}}

overview

111

(so that the XML does not get escaped, as by default web2py behavior).
This can be done better with:
1

{{=XML(page.body, sanitize=True)}}

By setting sanitize=True, you tell web2py to escape unsafe XML tags such as
"')


Un-escaped executable input such as this (for example, entered in the body
of a comment in a blog) is unsafe, because it can be used to generate Cross
Site Scripting (XSS) attacks against other visitors to the page.
The web2py XML helper can sanitize our text to prevent injections and escape
all tags except those that you explicitly allow. Here is an example:
1
2

>>> print XML('', sanitize=True)
<script>alert("unsafe!")</script>

The XML constructors, by default, consider the content of some tags and some
of their attributes safe. You can override the defaults using the optional
permitted_tags and allowed_attributes arguments.
Here are the default
values of the optional arguments of the XML helper.
1
2
3
4
5

XML(text, sanitize=False,
permitted_tags=['a', 'b', 'blockquote', 'br/', 'i', 'li',
'ol', 'ul', 'p', 'cite', 'code', 'pre', 'img/'],
allowed_attributes={'a':['href', 'title'],
'img':['src', 'alt'], 'blockquote':['type']})

5.2.2

Built-in helpers

A

This helper is used to build links.
1
2
3

>>> print A('', XML('me'),
_href='http://www.web2py.com')
<click>me/b>

Instead of _href you can pass the URL using the
example in a view:
1

{{=A('click me', callback=URL('myaction'))}}

callback

argument. For

the views

213

and the effect of pressing the link will be an ajax call to "myaction" instead of
a redirection. In this case, optionally you can specify two more arguments:
target and delete:
1
2

{{=A('click me', callback=URL('myaction'), target="t")}}


and the response of the ajax callback will be stored in the DIV with id equal
to "t".
1

{{=A('click me', callback=URL('myaction'), delete='div#b")}}

and upon response, the closest tag matching "div#b" will be deleted. In this
case, the button will be deleted. A typical application is:
1

{{=A('click me', callback=URL('myaction'), delete='tr")}}

in a table. Pressing the button will perform the callback and delete the table
row.
callback

and delete can be combined.

Tha A helper takes a special argument called cid. It works as follows:
1
2

{{=A('linked page', _href='http://example.com', cid='myid')}}


and a click on the link causes the content to be loaded in the div. This
is similar but more powerful than the above syntax since it is designed to
refresh page components. We discuss applications of cid in more detail in
Chapter 12, in the context of components.
These ajax features require jQuery and "static/js/web2py_ajax.js", which
are automatically included by placing {{include ’web2py_ajax.html’}} in the
layout head. "views/web2py_ajax.html" defines some variables based on
request and includes all necessary js and css files.
B

This helper makes its contents bold.
1
2

>>> print B('', XML('world'), _class='test', _id=0)
<hello>world

214

web2py full-stack web framework, 4th edition

BODY

This helper makes the body of a page.
1
2

>>> print BODY('', XML('world'), _bgcolor='red')
<hello>world

BR

This helper creates a line break.
1
2

>>> print BR()



CAT

(1.98.1 and up)

This helper concatenates other helpers, same as TAG[”].
1

2

>>> print CAT('Here is a ', A('link',_href=URL()), ', and here is some ', B('bold
text'), '.')
Here is a link, and here is some bold text.

CENTER

This helper centers its content.
1
2
3

>>> print CENTER('', XML('world'),
_class='test', _id=0)
>>>
<hello>world

CODE

This helper performs syntax highlighting for Python, C, C++, HTML and
web2py code, and is preferable to PRE for code listings. CODE also has the
ability to create links to the web2py API documentation.
Here is an example of highlighting sections of Python code.
1
2
3
4
5
6
7
8
9
10

>>> print CODE('print "hello"', language='python').xml()
1.
print 
"hello"


Here is a similar example for HTML
1
2
3

1
2
3

>>> print CODE(
>>>
'{{=request.env.remote_add}}',
>>>
language='html')
......
{{=request.env.remote_add}}
......

These are the default arguments for the CODE helper:
1

CODE("print 'hello world'", language='python', link=None, counter=1, styles={})

Supported values for the language argument are "python", "html_plain", "c",
"cpp", "web2py", and "html". The "html" language interprets {{ and }} tags as
"web2py" code, while "html_plain" doesn’t.
If a link value is specified, for example "/examples/global/vars/", web2py
API references in the code are linked to documentation at the link URL.
For example "request" would be linked to "/examples/global/vars/request".
In the above example, the link URL is handled by the "vars" action in the
"global.py" controller that is distributed as part of the web2py "examples"
application.
The counter argument is used for line numbering. It can be set to any of
three different values. It can be None for no line numbers, a numerical value
specifying the start number, or a string. If the counter is set to a string, it is
interpreted as a prompt, and there are no line numbers.
The styles argument is a bit tricky. If you look at the generated HTML
above, it contains a table with two columns, and each column has its own

216

web2py full-stack web framework, 4th edition

style declared inline using CSS. The
those two CSS styles. For example:
1

styles

attributes allows you to override

{{=CODE(...,styles={'CODE':'margin: 0;padding: 5px;border: none;'})}}

The

attribute must be a dictionary, and it allows two possible keys:
CODE for the style of the actual code, and LINENUMBERS for the style of the left
column, which contains the line numbers. Mind that these styles completely
replace the default styles and are not simply added to them.
styles

COL
1
2

>>> print COL('a','b')
ab

COLGROUP
1
2

>>> print COLGROUP('a','b')
ab

DIV

All helpers apart from XML are derived from DIV and inherit its basic methods.
1
2

>>> print DIV('', XML('world'), _class='test', _id=0)
<hello>world

EM

Emphasizes its content.
1
2

>>> print EM('', XML('world'), _class='test', _id=0)
<hello>world

FIELDSET

This is used to create an input field together with its label.
1
2

>>> print FIELDSET('Height:', INPUT(_name='height'), _class='test')
Height:

FORM

This is one of the most important helpers. In its simple form, it just makes a
...
 tag, but because helpers are objects and have knowledge of
what they contain, they can process submitted forms (for example, perform
validation of the fields). This will be discussed in detail in Chapter 7.

the views

1
2
3

217

>>> print FORM(INPUT(_type='submit'), _action='', _method='post')



The "enctype" is "multipart/form-data" by default.
The constructor of a FORM, and of SQLFORM, can also take a special argument
called . When a dictionary is passed as , its items are translated into "hidden"
INPUT fields. For example:
1
2
3

>>> print FORM(hidden=dict(a='b'))



H1, H2, H3, H4, H5, H6

These helpers are for paragraph headings and subheadings:
1
2

>>> print H1('', XML('world'), _class='test', _id=0)
<hello>world

HEAD

For tagging the HEAD of an HTML page.
1
2

>>> print HEAD(TITLE('', XML('world')))


HTML

This helper is a little different. In addition to making the
prepends the tag with a doctype string [54, 55, 56].
1
2
3
4



tags, it

>>> print HTML(BODY('', XML('world')))

<hello>world

The HTML helper also takes some additional optional arguments that have
the following default:
1

HTML(..., lang='en', doctype='transitional')

where doctype can be ’strict’, ’transitional’, ’frameset’, ’html5’, or a full
doctype string.

218

web2py full-stack web framework, 4th edition

XHTML

XHTML is similar to HTML but it creates an XHTML doctype instead.
1

XHTML(..., lang='en', doctype='transitional', xmlns='http://www.w3.org/1999/xhtml')

where doctype can be ’strict’, ’transitional’, ’frameset’, or a full doctype
string.
HR

This helper creates a horizontal line in an HTML page
1
2

>>> print HR()


I

This helper makes its contents italic.
1
2

>>> print I('', XML('world'), _class='test', _id=0)
<hello>world

INPUT

Creates an  tag. An input tag may not contain other tags, and is
closed by /> instead of >. The input tag has an optional attribute _type that
can be set to "text" (the default), "submit", "checkbox", or "radio".
1
2

>>> print INPUT(_name='test', _value='a')


It also takes an optional special argument called "value", distinct from
"_value". The latter sets the default value for the input field; the former
sets its current value. For an input of type "text", the former overrides the
latter:
1
2

>>> print INPUT(_name='test', _value='a', value='b')


For radio buttons, INPUT selectively sets the "checked" attribute:
1
2
3
4
5

>>> for v in ['a', 'b', 'c']:
>>>
print INPUT(_type='radio', _name='test', _value=v, value='b'), v
 a
 b
 c

the views

219

and similarly for checkboxes:
1
2
3
4

>>> print INPUT(_type='checkbox', _name='test', _value='a', value=True)

>>> print INPUT(_type='checkbox', _name='test', _value='a', value=False)


IFRAME

This helper includes another web page in the current page. The url of the
other page is specified via the "_src" attribute.
1
2

>>> print IFRAME(_src='http://www.web2py.com')


IMG

It can be used to embed images into HTML:
1
2

>>> IMG(_src='http://example.com/image.png',_alt='test')


Here is a combination of A, IMG, and URL helpers for including a static
image with a link:
1
2
3
4
5

>>> A(IMG(_src=URL('static','logo.png'), _alt="My Logo"),
_href=URL('default','index'))




LABEL

It is used to create a LABEL tag for an INPUT field.
1
2

>>> print LABEL('', XML('world'), _class='test', _id=0)
<hello>world

LEGEND

It is used to create a legend tag for a field in a form.
1
2

>>> print LEGEND('Name', _for='myfield')
Name

LI

It makes a list item and should be contained in a UL or OL tag.

220

1
2

web2py full-stack web framework, 4th edition

>>> print LI('', XML('world'), _class='test', _id=0)
<hello>world

META

To be used for building META tags in the HTML head. For example:
1
2

>>> print META(_name='security', _content='high')


MARKMIN

Implements the markmin wiki syntax. It converts the input text into output
html according to the markmin rules described in the example below:
1

2
3

>>> print MARKMIN("this is **bold** or ''italic'' and this [[a link http://web2py.
com]]")
this is bold or italic and
this a link

The markmin syntax is described in this file that ships with web2py:
1

http://127.0.0.1:8000/examples/static/markmin.html

and some examples are shown in chapter 12 in the context of plugin_wiki,
which uses MARKMIN extensively.
You can use markmin to generate HTML, LaTeX and PDF documents:
1
2
3
4
5
6
7

m = "Hello **world** [[link http://web2py.com]]"
from gluon.contrib.markmin.markmin2html import markmin2html
print markmin2html(m)
from gluon.contrib.markmin.markmin2latex import markmin2latex
print markmin2latex(m)
from gluon.contrib.markmin.markmin2pdf import markmin2pdf
print markmin2pdf(m) # requires pdflatex

(the MARKMIN helper is a shortcut for markmin2html)
Here is a basic syntax primer:

the views

221

SOURCE

OUTPUT

# title
## section
### subsection
**bold**
”italic”
“verbatim“
http://google.com
http://...
http://...png
http://...mp3
http://...mp4
qr:http://...
embed:http://...
[[click me #myanchor]]
$$\int_ab̂ sin(x)dx$$

title
section
subsection
bold
italic
verbatim
http://google.com
http:...





click me
Rb
a sin ( x ) dx

Simply including a link to an image, a videos or an audio files without
markup result in the corresponding image, video or audio file beling
included automatically (for audio and video it uses html 

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 583
Page Mode                       : UseOutlines
Has XFA                         : No
Author                          : Massimo Di Pierro
Title                           : web2py8.5plus3minus4plus24plus2minus2Full-Stack Web Framework, 4th Edition
Subject                         : 
Creator                         : LaTeX with hyperref package
Producer                        : pdfTeX-1.40.11
Create Date                     : 2011:12:09 10:55:18-06:00
Modify Date                     : 2012:06:12 18:16:30-03:00
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.1415926-1.40.11-2.2 (TeX Live 2010) kpathsea version 6.0.0