The Pyramid Web Application

Development Framework

Version 1.3

Chris McDonough

CONTENTS

Front Matter	i
Copyright, Trademarks, and Attributions	iii
Attributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	iv
Print Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	iv
Contacting The Publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	iv
HTML Version and Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	iv
Typographical Conventions	v
Author Introduction	vii
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	vii
Book Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	viii
The Genesis of repoze.bfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	viii
The Genesis of Pyramid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	ix
Thanks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	ix

I	Narrative Documentation		1
1	Pyramid Introduction		3
	1.1 What Makes Pyramid Unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		4
	1.1.1	Single-file applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	5
	1.1.2	Decorator-based configuration . . . . . . . . . . . . . . . . . . . . . . . . . . .	5
	1.1.3	URL generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	6
	1.1.4	Static file serving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	6
	1.1.5	Debug Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	6
	1.1.6	Debugging settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	7
	1.1.7	Add-ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	7

		1.1.8	Class-based and function-based views . . . . . . . . . . . . . . . . . . . . . . .	7
		1.1.9	Asset specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	8
		1.1.10	Extensible templating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	9
		1.1.11	Rendered views can return dictionaries . . . . . . . . . . . . . . . . . . . . . .	9
		1.1.12	Event system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	10
		1.1.13	Built-in internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . .	10
		1.1.14	HTTP caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	10
		1.1.15	Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	11
		1.1.16	Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	11
		1.1.17	Exception views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	11
		1.1.18	No singletons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	12
		1.1.19	View predicates and many views per route . . . . . . . . . . . . . . . . . . . . .	12
		1.1.20	Transaction management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	12
		1.1.21	Configuration conflict detection . . . . . . . . . . . . . . . . . . . . . . . . . .	13
		1.1.22	Configuration extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	13
		1.1.23	Flexible authentication and authorization . . . . . . . . . . . . . . . . . . . . .	14
		1.1.24	Traversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	14
		1.1.25	Tweens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	14
		1.1.26	View response adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	15
		1.1.27	“Global” response object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	17
		1.1.28	Automating repetitive configuration . . . . . . . . . . . . . . . . . . . . . . . .	17
		1.1.29	Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	18
		1.1.30	Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	18
		1.1.31	Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	19
	1.2	What Is The Pylons Project? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		19
	1.3	Pyramid and Other Web Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . .		19
2	Installing Pyramid			21
	2.1	Before You Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		21
		2.1.1	If You Don’t Yet Have A Python Interpreter (UNIX) . . . . . . . . . . . . . . .	21
		2.1.2	If You Don’t Yet Have A Python Interpreter (Windows) . . . . . . . . . . . . . .	23
	2.2	Installing Pyramid on a UNIX System . . . . . . . . . . . . . . . . . . . . . . . . . . .		23
		2.2.1	Installing the virtualenv Package . . . . . . . . . . . . . . . . . . . . . . .	24
		2.2.2	Creating the Virtual Python Environment . . . . . . . . . . . . . . . . . . . . .	24
		2.2.3	Installing Pyramid Into the Virtual Python Environment . . . . . . . . . . . . .	25
	2.3	Installing Pyramid on a Windows System . . . . . . . . . . . . . . . . . . . . . . . . .		25
	2.4	What Gets Installed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		26
3	Application Configuration			27
	3.1	Imperative Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		27
	3.2	Declarative Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		28
	3.3	Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		29
4 Creating Your First Pyramid Application				31

	4.1	Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		31
		4.1.1	Imports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	32
		4.1.2	View Callable Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	33
		4.1.3	Application Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	33
		4.1.4	Configurator Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	33
		4.1.5	Adding Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	34
		4.1.6	WSGI Application Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . .	34
		4.1.7	WSGI Application Serving . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	35
		4.1.8	Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	35
	4.2	References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		35
5 Creating a Pyramid Project				37
	5.1	Scaffolds Included with Pyramid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		37
	5.2	Creating the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		38
	5.3	Installing your Newly Created Project for Development . . . . . . . . . . . . . . . . . .		39
	5.4	Running The Tests For Your Application . . . . . . . . . . . . . . . . . . . . . . . . . .		40
	5.5	Running The Project Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		41
		5.5.1	Reloading Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	43
	5.6	Viewing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		43
		5.6.1	The Debug Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	44
	5.7	The Project Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		46
	5.8	The MyProject Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		47
		5.8.1	development.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	48
		5.8.2	production.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	50
		5.8.3	MANIFEST.in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	51
		5.8.4	setup.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	51
		5.8.5	setup.cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	53
	5.9	The myproject Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		54
		5.9.1 __init__.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		55
		5.9.2	views.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	55
		5.9.3	static . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	57
		5.9.4	templates/mytemplate.pt . . . . . . . . . . . . . . . . . . . . . . . . .	57
		5.9.5	tests.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	57
	5.10	Modifying Package Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		58
	5.11	Using the Interactive Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		58
	5.12	What Is This pserve Thing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		59
	5.13	Using an Alternate WSGI Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		59
6	Startup			61
	6.1	The Startup Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		61
	6.2	Deployment Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		64
7	Request Processing			65

8	URL Dispatch			71
	8.1	High-Level Operational Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		71
	8.2	Route Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		71
		8.2.1 Configuring a Route to Match a View . . . . . . . . . . . . . . . . . . . . . . .		72
		8.2.2	Route Pattern Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	73
		8.2.3	Route Declaration Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . .	77
		8.2.4	Route Configuration Arguments . . . . . . . . . . . . . . . . . . . . . . . . . .	78
	8.3	Route Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		78
		8.3.1	The Matchdict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	79
		8.3.2	The Matched Route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	79
	8.4	Routing Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		80
		8.4.1	Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	80
		8.4.2	Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	80
		8.4.3	Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	81
	8.5	Matching the Root URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		82
	8.6	Generating Route URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		82
	8.7	Static Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		84
	8.8	Redirecting to Slash-Appended Routes . . . . . . . . . . . . . . . . . . . . . . . . . . .		85
	8.9	Debugging Route Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		86
	8.10	Using a Route Prefix to Compose Applications . . . . . . . . . . . . . . . . . . . . . .		87
	8.11	Custom Route Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		89
	8.12	Route Factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		92
	8.13	Using Pyramid Security With URL Dispatch . . . . . . . . . . . . . . . . . . . . . . . .		93
	8.14	Route View Callable Registration and Lookup Details . . . . . . . . . . . . . . . . . . .		94
	8.15	References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		94
9	Views			95
	9.1	View Callables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		95
	9.2	Defining a View Callable as a Function . . . . . . . . . . . . . . . . . . . . . . . . . . .		96
	9.3	Defining a View Callable as a Class . . . . . . . . . . . . . . . . . . . . . . . . . . . .		96
	9.4	View Callable Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		97
	9.5	Using Special Exceptions In View Callables . . . . . . . . . . . . . . . . . . . . . . . .		98
		9.5.1	HTTP Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	98
		9.5.2 How Pyramid Uses HTTP Exceptions . . . . . . . . . . . . . . . . . . . . . . .		99
	9.6	Custom Exception Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		100
	9.7	Using a View Callable to Do an HTTP Redirect . . . . . . . . . . . . . . . . . . . . . .		101
	9.8	Handling Form Submissions in View Callables (Unicode and Character Set Issues) . . .		102
	9.9	Alternate View Callable Argument/Calling Conventions . . . . . . . . . . . . . . . . . .		104
	9.10	Pylons-1.0-Style “Controller” Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . .		105
10	Renderers			107
	10.1	Writing View Callables Which Use a Renderer . . . . . . . . . . . . . . . . . . . . . .		108
	10.2	Built-In Renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		109
		10.2.1	string: String Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	109

	10.2.2	json: JSON Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	110
10.3	JSONP	Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	110
	10.3.1	*.pt or *.txt: Chameleon Template Renderers . . . . . . . . . . . . . . . .	112
	10.3.2	*.mak or *.mako: Mako Template Renderer . . . . . . . . . . . . . . . . . .	113
10.4	Varying Attributes of Rendered Responses . . . . . . . . . . . . . . . . . . . . . . . . .		114
10.5	Deprecated Mechanism to Vary Attributes of Rendered Responses . . . . . . . . . . . .		115
10.6	Adding and Changing Renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		116
	10.6.1	Adding a New Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	116
	10.6.2	Changing an Existing Renderer . . . . . . . . . . . . . . . . . . . . . . . . . .	118
10.7	Overriding A Renderer At Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . .		119
11 Templates			121
11.1	Using Templates Directly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		121
11.2	System Values Used During Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . .		125
11.3	Templates Used as Renderers via Configuration . . . . . . . . . . . . . . . . . . . . . .		126
11.4	Chameleon ZPT Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		128
	11.4.1	A Sample ZPT Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	129
	11.4.2	Using ZPT Macros in Pyramid . . . . . . . . . . . . . . . . . . . . . . . . . . .	129
11.5	Templating with Chameleon Text Templates . . . . . . . . . . . . . . . . . . . . . . . .		130
11.6	Side Effects of Rendering a Chameleon Template . . . . . . . . . . . . . . . . . . . . .		131
11.7	Debugging Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		131
11.8	Chameleon Template Internationalization . . . . . . . . . . . . . . . . . . . . . . . . .		132
11.9	Templating With Mako Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		132
	11.9.1	A Sample Mako Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	133
11.10Automatically Reloading Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . .			133
11.11Available Add-On Template System Bindings . . . . . . . . . . . . . . . . . . . . . . .			134
12 View Configuration			135
12.1	Mapping a Resource or URL Pattern to a View Callable . . . . . . . . . . . . . . . . . .		135
	12.1.1	View Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . .	136
	12.1.2	Adding View Configuration Using the @view_config Decorator . . . . . . .	142
	12.1.3	Adding View Configuration Using add_view() . . . . . . . . . . . . . . . .	145
12.2	@view_defaults Class Decorator . . . . . . . . . . . . . . . . . . . . . . . . . . .		146
	12.2.1	Configuring View Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	149
	12.2.2	NotFound Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	150
12.3	Influencing HTTP Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		150
12.4	Debugging View Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		151
13 Static Assets			153
13.1	Understanding Asset Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . .		153
13.2	Serving Static Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		154
	13.2.1	Generating Static Asset URLs . . . . . . . . . . . . . . . . . . . . . . . . . . .	156
13.3	Advanced: Serving Static Assets Using a View Callable . . . . . . . . . . . . . . . . . .		157
	13.3.1	Root-Relative Custom Static View (URL Dispatch Only) . . . . . . . . . . . . .	158

	13.3.2 Registering A View Callable to Serve a “Static” Asset . . . . . . . . . . . . . .		159
13.4	Overriding Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		160
	13.4.1	The override_asset API . . . . . . . . . . . . . . . . . . . . . . . . . . .	160
14 Request and Response Objects			163
14.1	Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		164
	14.1.1 Special Attributes Added to the Request by Pyramid . . . . . . . . . . . . . . .		165
	14.1.2	URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	165
	14.1.3	Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	165
	14.1.4	Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	166
	14.1.5	Multidict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	166
	14.1.6 Dealing With A JSON-Encoded Request Body . . . . . . . . . . . . . . . . . .		166
	14.1.7 Cleaning Up After a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . .		168
	14.1.8	More Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	168
14.2	Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		169
	14.2.1	Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	170
	14.2.2	Instantiating the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	170
	14.2.3	Exception Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	170
	14.2.4	More Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	170
15 Sessions			171
15.1	Using The Default Session Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		171
15.2	Using a Session Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		172
15.3	Using Alternate Session Factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		173
15.4	Creating Your Own Session Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . .		174
15.5	Flash Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		174
	15.5.1 Using the session.flash Method . . . . . . . . . . . . . . . . . . . . . . .		174
	15.5.2 Using the session.pop_flash Method . . . . . . . . . . . . . . . . . . . .		175
	15.5.3 Using the session.peek_flash Method . . . . . . . . . . . . . . . . . . .		175
15.6	Preventing Cross-Site Request Forgery Attacks . . . . . . . . . . . . . . . . . . . . . .		176
	15.6.1 Using the session.get_csrf_token Method . . . . . . . . . . . . . . . .		176
	15.6.2 Using the session.new_csrf_token Method . . . . . . . . . . . . . . . .		177
16 Using Events			179
16.1	Configuring an Event Listener Imperatively . . . . . . . . . . . . . . . . . . . . . . . .		179
16.2	Configuring an Event Listener Using a Decorator . . . . . . . . . . . . . . . . . . . . .		180
16.3	An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		181
17 Environment Variables and .ini File Settings			183
17.1	Reloading Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		184
17.2	Reloading Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		184
17.3	Debugging Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		184
17.4	Debugging Not Found Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		185
17.5	Debugging Route Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		185

17.6	Preventing HTTP Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		185
17.7	Debugging All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		185
17.8	Reloading All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		186
17.9	Default Locale Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		186
17.10Including Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			186
	17.10.1 pyramid.includes vs. pyramid.config.Configurator.include()187
17.11Explicit Tween Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			188
	17.11.1 PasteDeploy Configuration vs. Plain-Python Configuration . . . . . . . . . . . .		189
17.12Mako Template Render Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			190
	17.12.1 Mako Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		190
	17.12.2 Mako Module Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		190
	17.12.3 Mako Input Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		190
	17.12.4 Mako Error Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		191
	17.12.5 Mako Default Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		191
	17.12.6 Mako Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		191
	17.12.7 Mako Strict Undefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		191
	17.12.8 Mako Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		192
17.13Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			192
17.14Understanding the Distinction Between reload_templates and reload_assets			193
17.15Adding A Custom Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			194
18 Logging			197
18.1	Logging Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		197
18.2	Sending Logging Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		200
18.3	Filtering log messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		201
18.4	Advanced Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		202
18.5	Logging Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		202
18.6	Request Logging with Paste’s TransLogger . . . . . . . . . . . . . . . . . . . . . . . .		203
19 PasteDeploy Configuration Files			207
19.1	PasteDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		207
	19.1.1 Entry Points and PasteDeploy .ini Files . . . . . . . . . . . . . . . . . . . . .		208
	19.1.2 [DEFAULTS] Section of a PasteDeploy .ini File . . . . . . . . . . . . . . .		210
20 Command-Line Pyramid			211
20.1	Displaying Matching Views for a Given URL . . . . . . . . . . . . . . . . . . . . . . .		211
20.2	The Interactive Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		213
	20.2.1	Extending the Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	214
	20.2.2	IPython or bpython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	216
20.3	Displaying All Application Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		216
20.4	Displaying “Tweens” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		217
20.5	Invoking a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		218
20.6	Writing a Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		219
	20.6.1	Changing the Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	222

		20.6.2	Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	222
		20.6.3	Setting Up Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	223
	20.7	Making Your Script into a Console Script . . . . . . . . . . . . . . . . . . . . . . . . .		223
21	Internationalization and Localization			229
	21.1	Creating a Translation String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		229
		21.1.1 Using The TranslationString Class . . . . . . . . . . . . . . . . . . . .		229
		21.1.2 Using the TranslationStringFactory Class . . . . . . . . . . . . . . .		231
	21.2	Working With gettext Translation Files . . . . . . . . . . . . . . . . . . . . . . . . .		232
		21.2.1 Installing Babel and Lingua . . . . . . . . . . . . . . . . . . . . . . . . . . . .		233
		21.2.2 Extracting Messages from Code and Templates . . . . . . . . . . . . . . . . . .		235
		21.2.3 Initializing a Message Catalog File . . . . . . . . . . . . . . . . . . . . . . . . .		236
		21.2.4 Updating a Catalog File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		237
		21.2.5 Compiling a Message Catalog File . . . . . . . . . . . . . . . . . . . . . . . . .		237
	21.3	Using a Localizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		238
		21.3.1	Performing a Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	238
		21.3.2	Performing a Pluralization . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	239
	21.4	Obtaining the Locale Name for a Request . . . . . . . . . . . . . . . . . . . . . . . . .		240
	21.5	Performing Date Formatting and Currency Formatting . . . . . . . . . . . . . . . . . .		240
	21.6	Chameleon Template Support for Translation Strings . . . . . . . . . . . . . . . . . . .		241
	21.7	Mako Pyramid I18N Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		242
	21.8	Localization-Related Deployment Settings . . . . . . . . . . . . . . . . . . . . . . . . .		242
	21.9	“Detecting” Available Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		243
	21.10Activating Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			244
		21.10.1 Adding a Translation Directory . . . . . . . . . . . . . . . . . . . . . . . . . .		244
		21.10.2 Setting the Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		245
	21.11Locale Negotiators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			245
		21.11.1 The Default Locale Negotiator . . . . . . . . . . . . . . . . . . . . . . . . . . .		246
		21.11.2 Using a Custom Locale Negotiator . . . . . . . . . . . . . . . . . . . . . . . . .		246
22 Virtual Hosting				249
	22.1	Hosting an Application Under a URL Prefix . . . . . . . . . . . . . . . . . . . . . . . .		249
	22.2	Virtual Root Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		250
	22.3	Further Documentation and Examples . . . . . . . . . . . . . . . . . . . . . . . . . . .		251
23	Unit, Integration, and Functional Testing			253
	23.1	Test Set Up and Tear Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		254
		23.1.1	What? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	256
	23.2	Using the Configurator and pyramid.testing APIs in Unit Tests . . . . . . . .		256
	23.3	Creating Integration Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		258
	23.4	Creating Functional Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		259
24 Resources				261
	24.1	Defining a Resource Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		262

24.2	Location-Aware Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	263
24.3	Generating The URL Of A Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . .	264
	24.3.1 Overriding Resource URL Generation . . . . . . . . . . . . . . . . . . . . . . .	265
24.4	Generating the Path To a Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	266
24.5	Finding a Resource by Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	267
24.6	Obtaining the Lineage of a Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . .	268
24.7	Determining if a Resource is In The Lineage of Another Resource . . . . . . . . . . . .	268
24.8	Finding the Root Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	269
24.9	Resources Which Implement Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . .	269
24.10Finding a Resource With a Class or Interface in Lineage . . . . . . . . . . . . . . . . .		271
24.11Pyramid API Functions That Act Against Resources . . . . . . . . . . . . . . . . . . . .		272
25 Much Ado About Traversal		273
25.1	URL Dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	274
25.2	Historical Refresher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	275
25.3	Traversal (aka Resource Location) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	275
25.4	What Is a “Resource”? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	276
25.5	View Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	277
25.6	Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	278
26 Traversal		281
26.1	Traversal Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	281
26.2	The Resource Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	283
26.3	The Traversal Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	285
	26.3.1 A Description of The Traversal Algorithm . . . . . . . . . . . . . . . . . . . . .	285
	26.3.2 Traversal Algorithm Examples . . . . . . . . . . . . . . . . . . . . . . . . . . .	288
	26.3.3 Using Resource Interfaces In View Configuration . . . . . . . . . . . . . . . . .	290
26.4	References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	292
27 Security		293
27.1	Enabling an Authorization Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	294
	27.1.1 Enabling an Authorization Policy Imperatively . . . . . . . . . . . . . . . . . .	294
27.2	Protecting Views with Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	295
	27.2.1 Setting a Default Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . .	296
27.3	Assigning ACLs to your Resource Objects . . . . . . . . . . . . . . . . . . . . . . . . .	296
27.4	Elements of an ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	297
27.5	Special Principal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	299
27.6	Special Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	300
27.7	Special ACEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	300
27.8	ACL Inheritance and Location-Awareness . . . . . . . . . . . . . . . . . . . . . . . . .	300
27.9	Changing the Forbidden View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	301
27.10Debugging View Authorization Failures . . . . . . . . . . . . . . . . . . . . . . . . . .		301
27.11Debugging Imperative Authorization Failures . . . . . . . . . . . . . . . . . . . . . . .		302
27.12Creating Your Own Authentication Policy . . . . . . . . . . . . . . . . . . . . . . . . .		302

27.13Creating Your Own Authorization Policy . . . . . . . . . . . . . . . . . . . . . . . . .			. 303
28 Combining Traversal and URL Dispatch			305
28.1	A Review of Non-Hybrid Applications . . . . . . . . . . . . . . . . . . . . . . . . . .		. 305
	28.1.1	URL Dispatch Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 306
	28.1.2	Traversal Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 306
28.2	Hybrid Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 307
	28.2.1 The Root Object for a Route Match . . . . . . . . . . . . . . . . . . . . . . .		. 308
	28.2.2 Using *traverse In a Route Pattern . . . . . . . . . . . . . . . . . . . . .		. 308
	28.2.3 Using the traverse Argument In a Route Definition . . . . . . . . . . . . .		. 312
	28.2.4 Using *subpath in a Route Pattern . . . . . . . . . . . . . . . . . . . . . .		. 313
28.3	Corner Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 313
	28.3.1 Registering a Default View for a Route That Has a view Attribute . . . . . . .		. 313
	28.3.2	Binding Extra Views Against a Route Configuration that Doesn’t Have	a
		*traverse Element In Its Pattern . . . . . . . . . . . . . . . . . . . . . . .	. 314
29 Using Hooks			317
29.1	Changing the Not Found View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 317
29.2	Changing the Forbidden View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 320
29.3	Changing the Request Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 321
29.4	Using The Before Render Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 322
29.5	Adding Renderer Globals (Deprecated) . . . . . . . . . . . . . . . . . . . . . . . . .		. 323
29.6	Using Response Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 324
29.7	Using Finished Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 325
29.8	Changing the Traverser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 326
29.9	Changing How pyramid.request.Request.resource_url() Generates a URL 327
29.10Changing How Pyramid Treats View Responses . . . . . . . . . . . . . . . . . . . . .			. 328
29.11Using a View Mapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			. 330
29.12Registering Configuration Decorators . . . . . . . . . . . . . . . . . . . . . . . . . .			. 332
29.13Registering “Tweens” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .			. 334
	29.13.1 Creating a Tween Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 334
	29.13.2 Registering an Implicit Tween Factory . . . . . . . . . . . . . . . . . . . . . .		. 335
	29.13.3 Suggesting Implicit Tween Ordering . . . . . . . . . . . . . . . . . . . . . . .		. 336
	29.13.4 Explicit Tween Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 338
	29.13.5 Tween Conflicts and Ordering Cycles . . . . . . . . . . . . . . . . . . . . . .		. 339
	29.13.6 Displaying Tween Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 339
30 Pyramid Configuration Introspection			341
30.1	Using the Introspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 341
30.2	Introspectable Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 342
30.3	Pyramid Introspection Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 343
30.4	Introspection in the Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 354
30.5	Disabling Introspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		. 354

31 Extending An Existing Pyramid Application			355
31.1	The Difference Between “Extensible” and “Pluggable” Applications . . . . . . . . . . .		355
31.2	Rules for Building An Extensible Application . . . . . . . . . . . . . . . . . . . . . . .		356
	31.2.1	Fundamental Plugpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	357
31.3	Extending an Existing Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		357
	31.3.1 If The Application Has Configuration Decorations . . . . . . . . . . . . . . . .		357
	31.3.2	Extending the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	358
	31.3.3	Overriding Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	359
	31.3.4	Overriding Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	360
	31.3.5	Overriding Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	360
32 Advanced Configuration			361
32.1	Conflict Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		361
	32.1.1	Manually Resolving Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . .	363
	32.1.2	Automatic Conflict Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . .	366
	32.1.3 Methods Which Provide Conflict Detection . . . . . . . . . . . . . . . . . . . .		366
32.2	Including Configuration from External Sources . . . . . . . . . . . . . . . . . . . . . .		366
32.3	Two-Phase Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		367
33 Extending Pyramid Configuration			369
33.1	Adding Methods to the Configurator via add_directive . . . . . . . . . . . . . . .		369
33.2	Using config.action in a Directive . . . . . . . . . . . . . . . . . . . . . . . . . .		370
33.3	Adding Configuration Introspection . . . . . . . . . . . . . . . . . . . . . . . . . . . .		373
	33.3.1	Introspectable Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . .	374
34 Thread Locals			377
34.1	Why and How Pyramid Uses Thread Local Variables . . . . . . . . . . . . . . . . . . .		377
34.2	Why You Shouldn’t Abuse Thread Locals . . . . . . . . . . . . . . . . . . . . . . . . .		378
35 Using the Zope Component Architecture in Pyramid			381
35.1	Using the ZCA Global API in a Pyramid Application . . . . . . . . . . . . . . . . . . .		382
	35.1.1 Disusing the Global ZCA API . . . . . . . . . . . . . . . . . . . . . . . . . . .		382
	35.1.2 Enabling the ZCA Global API by Using hook_zca . . . . . . . . . . . . . . .		383
	35.1.3 Enabling the ZCA Global API by Using The ZCA Global Registry . . . . . . . .		384

II Tutorials			387
36 ZODB + Traversal Wiki Tutorial			389
36.1	Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		389
36.2	Design	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	390
	36.2.1	Overall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	390
	36.2.2	Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	390
	36.2.3	Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	390

	36.2.4	Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	391
	36.2.5	Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	391
36.3	Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		393
	36.3.1	Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	393
	36.3.2	Make a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	395
	36.3.3 Install the Project in “Development Mode” . . . . . . . . . . . . . . . . . . . .		396
	36.3.4	Run the Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	396
	36.3.5 Expose Test Coverage Information . . . . . . . . . . . . . . . . . . . . . . . . .		397
	36.3.6	Start the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	397
	36.3.7 Visit the Application in a Browser . . . . . . . . . . . . . . . . . . . . . . . . .		398
	36.3.8 Decisions the zodb Scaffold Has Made For You . . . . . . . . . . . . . . . . .		398
36.4	Basic Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		398
	36.4.1 Application Configuration with __init__.py . . . . . . . . . . . . . . . . .		399
	36.4.2 Resources and Models with models.py . . . . . . . . . . . . . . . . . . . . .		400
	36.4.3	Views With views.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	401
	36.4.4	Configuration in development.ini . . . . . . . . . . . . . . . . . . . . . .	402
36.5	Defining the Domain Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		403
	36.5.1	Delete the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	403
	36.5.2	Edit models.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	404
	36.5.3 Look at the Result of Our Edits to models.py . . . . . . . . . . . . . . . . . .		404
	36.5.4 View the Application in a Browser . . . . . . . . . . . . . . . . . . . . . . . . .		405
36.6	Defining Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		405
	36.6.1 Declaring Dependencies in Our setup.py File . . . . . . . . . . . . . . . . .		406
	36.6.2	Adding View Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	408
	36.6.3 Viewing the Result of all Our Edits to views.py . . . . . . . . . . . . . . . .		411
	36.6.4	Adding Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	412
	36.6.5 Viewing the Application in a Browser . . . . . . . . . . . . . . . . . . . . . . .		416
36.7	Adding Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		417
	36.7.1 Add Authentication and Authorization Policies . . . . . . . . . . . . . . . . . .		417
	36.7.2	Add security.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	419
	36.7.3 Give Our Root Resource an ACL . . . . . . . . . . . . . . . . . . . . . . . . .		419
	36.7.4 Add Login and Logout Views . . . . . . . . . . . . . . . . . . . . . . . . . . .		420
	36.7.5	Change Existing Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	422
	36.7.6 Add permission Declarations to our view_config Decorators . . . . . . .		422
	36.7.7 Add the login.pt Template . . . . . . . . . . . . . . . . . . . . . . . . . . .		423
	36.7.8 Change view.pt and edit.pt . . . . . . . . . . . . . . . . . . . . . . . . .		424
	36.7.9 See Our Changes To views.py and our Templates . . . . . . . . . . . . . . .		425
	36.7.10 View the Application in a Browser . . . . . . . . . . . . . . . . . . . . . . . . .		430
36.8	Adding Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		431
	36.8.1	Test the Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	431
	36.8.2	Test the Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	431
	36.8.3	Functional tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	431
	36.8.4 View the results of all our edits to tests.py . . . . . . . . . . . . . . . . . .		432

	36.8.5	Run the Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	436
36.9	Distributing Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		438
37 SQLAlchemy + URL Dispatch Wiki Tutorial			439
37.1	Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		439
37.2	Design	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	440
	37.2.1	Overall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	440
	37.2.2	Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	440
	37.2.3	Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	440
	37.2.4	Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	441
	37.2.5	Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	441
37.3	Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		443
	37.3.1	Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	443
	37.3.2	Making a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	444
	37.3.3 Installing the Project in “Development Mode” . . . . . . . . . . . . . . . . . . .		445
	37.3.4	Running the Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	445
	37.3.5 Exposing Test Coverage Information . . . . . . . . . . . . . . . . . . . . . . .		446
	37.3.6	Initializing the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	447
	37.3.7	Starting the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	448
	37.3.8 Decisions the alchemy Scaffold Has Made For You . . . . . . . . . . . . . . .		448
37.4	Basic Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		449
	37.4.1 Application Configuration with __init__.py . . . . . . . . . . . . . . . . .		449
	37.4.2 View Declarations via views.py . . . . . . . . . . . . . . . . . . . . . . . . .		451
	37.4.3 Content Models with models.py . . . . . . . . . . . . . . . . . . . . . . . .		452
37.5	Defining the Domain Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		454
	37.5.1 Making Edits to models.py . . . . . . . . . . . . . . . . . . . . . . . . . . .		455
	37.5.2	Changing scripts/initializedb.py . . . . . . . . . . . . . . . . . . .	456
	37.5.3	Reinitializing the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	457
	37.5.4 Viewing the Application in a Browser . . . . . . . . . . . . . . . . . . . . . . .		458
37.6	Defining Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		459
	37.6.1 Declaring Dependencies in Our setup.py File . . . . . . . . . . . . . . . . .		459
	37.6.2	Running setup.py develop . . . . . . . . . . . . . . . . . . . . . . . . .	461
	37.6.3 Changing the views.py File . . . . . . . . . . . . . . . . . . . . . . . . . . .		461
	37.6.4	Adding Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	467
	37.6.5 Adding Routes to __init__.py . . . . . . . . . . . . . . . . . . . . . . . . .		470
	37.6.6 Viewing the Application in a Browser . . . . . . . . . . . . . . . . . . . . . . .		472
37.7	Adding Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		472
	37.7.1 Adding A Root Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		473
	37.7.2 Add an Authorization Policy and an Authentication Policy . . . . . . . . . . . .		474
	37.7.3 Adding an authentication policy callback . . . . . . . . . . . . . . . . . . . . .		475
	37.7.4 Adding Login and Logout Views . . . . . . . . . . . . . . . . . . . . . . . . . .		476
	37.7.5	Changing Existing Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	478
	37.7.6 Adding the login.pt Template . . . . . . . . . . . . . . . . . . . . . . . . .		479

	37.7.7 Add a “Logout” link when logged in . . . . . . . . . . . . . . . . . . . . . . . .		480
	37.7.8 Seeing Our Changes To views.py and our Templates . . . . . . . . . . . . . .		481
	37.7.9 Viewing the Application in a Browser . . . . . . . . . . . . . . . . . . . . . . .		486
37.8	Adding Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		487
	37.8.1	Testing the Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	487
	37.8.2	Testing the Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	487
	37.8.3	Functional tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	488
	37.8.4 Viewing the results of all our edits to tests.py . . . . . . . . . . . . . . . . .		488
	37.8.5	Running the Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	493
37.9	Distributing Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .		495
38 Converting a repoze.bfg Application to Pyramid			497
39 Running a Pyramid Application under mod_wsgi			501

III	API Reference		505
40	pyramid.authorization		507
41	pyramid.authentication		509
	41.1	Authentication Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	509
	41.2	Helper Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	513
42	pyramid.chameleon_text		515
43	pyramid.chameleon_zpt		517
44	pyramid.config		519
45	pyramid.events		561
	45.1	Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	561
	45.2	Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	562
46	pyramid.exceptions		567
47	pyramid.httpexceptions		569
	47.1	HTTP Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	569
48	pyramid.i18n		583
49	pyramid.interfaces		587
	49.1	Event-Related Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	587
	49.2	Other Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	589
50	pyramid.location		607

51	pyramid.paster		609
52	pyramid.registry		611
53	pyramid.renderers		613
54	pyramid.request		617
55	pyramid.response		643
	55.1	Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	648
56	pyramid.scripting		649
57	pyramid.security		651
	57.1	Authentication API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	651
	57.2	Authorization API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	652
	57.3	Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	653
	57.4	Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	654
58	pyramid.settings		655
59	pyramid.testing		657
60	pyramid.threadlocal		661
61	pyramid.traversal		663
62	pyramid.url		671
63	pyramid.view		673
64	pyramid.wsgi		679

IV Glossary and Index	681
Glossary	683

Front Matter