Файл: pyramid.pdf

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