The Pyramid Web Application Development Framework Version 1.1
Total Page:16
File Type:pdf, Size:1020Kb
The Pyramid Web Application Development Framework Version 1.1 Chris McDonough CONTENTS Front Matteri Copyright, Trademarks, and Attributions iii Attributions............................................ iv Print Production.......................................... iv Contacting The Publisher..................................... iv HTML Version and Source Code................................. iv Typographical Conventionsv Author Introduction vii Audience............................................. vii Book Content........................................... viii The Genesis of repoze.bfg .................................. viii The Genesis of Pyramid...................................... ix Thanks............................................... ix I Narrative Documentation1 1 Pyramid Introduction3 1.1 What Is The Pylons Project?................................4 1.2 Pyramid and Other Web Frameworks............................4 2 Installing Pyramid7 2.1 Before You Install......................................7 2.1.1 If You Don’t Yet Have A Python Interpreter (UNIX)...............7 2.1.2 If You Don’t Yet Have A Python Interpreter (Windows)..............9 2.2 Installing Pyramid on a UNIX System...........................9 2.2.1 Installing the virtualenv Package....................... 10 2.2.2 Creating the Virtual Python Environment..................... 10 2.2.3 Installing Pyramid Into the Virtual Python Environment............. 11 2.3 Installing Pyramid on a Windows System......................... 11 2.4 Installing Pyramid on Google App Engine......................... 12 2.5 Installing Pyramid on Jython................................ 12 2.6 What Gets Installed..................................... 12 3 Application Configuration 13 3.1 Imperative Configuration.................................. 13 3.2 Declarative Configuration.................................. 14 3.3 Summary.......................................... 15 4 Creating Your First Pyramid Application 17 4.1 Hello World, Goodbye World................................ 17 4.1.1 Imports....................................... 18 4.1.2 View Callable Declarations............................. 18 4.1.3 Application Configuration............................. 19 4.1.4 Configurator Construction............................. 20 4.1.5 Adding Configuration............................... 20 4.1.6 WSGI Application Creation............................ 21 4.1.7 WSGI Application Serving............................. 22 4.1.8 Conclusion..................................... 22 4.2 References.......................................... 22 5 Creating a Pyramid Project 23 5.1 Scaffolds Included with Pyramid.............................. 23 5.2 Creating the Project..................................... 24 5.3 Installing your Newly Created Project for Development.................. 26 5.4 Running The Tests For Your Application.......................... 26 5.5 Running The Project Application.............................. 27 5.6 Viewing the Application.................................. 28 5.7 The Project Structure.................................... 30 5.8 The MyProject Project .................................. 31 5.8.1 development.ini ............................... 31 5.8.2 production.ini ................................ 35 5.8.3 MANIFEST.in .................................. 35 5.8.4 setup.py ..................................... 35 5.8.5 setup.cfg .................................... 37 5.9 The myproject Package ................................. 38 5.9.1 __init__.py .................................. 39 5.9.2 views.py ..................................... 40 5.9.3 resources.py .................................. 41 5.9.4 static ...................................... 41 5.9.5 templates/mytemplate.pt ......................... 41 5.9.6 tests.py ..................................... 41 5.10 Modifying Package Structure................................ 42 5.11 Using the Interactive Shell................................. 43 6 URL Dispatch 45 6.1 High-Level Operational Overview............................. 45 6.2 Route Configuration..................................... 45 6.2.1 Configuring a Route to Match a View....................... 46 6.2.2 Route Pattern Syntax................................ 47 6.2.3 Route Declaration Ordering............................ 50 6.2.4 Route Factories................................... 50 6.2.5 Route Configuration Arguments.......................... 51 6.2.6 Custom Route Predicates.............................. 52 6.3 Route Matching....................................... 54 6.3.1 The Matchdict................................... 55 6.3.2 The Matched Route................................. 55 6.4 Routing Examples...................................... 55 6.4.1 Example 1..................................... 55 6.4.2 Example 2..................................... 56 6.4.3 Example 3..................................... 57 6.5 Matching the Root URL.................................. 58 6.6 Generating Route URLs.................................. 58 6.7 Static Routes........................................ 58 6.8 Redirecting to Slash-Appended Routes........................... 59 6.8.1 Custom Not Found View With Slash Appended Routes.............. 60 6.9 Cleaning Up After a Request................................ 61 6.10 Using Pyramid Security With URL Dispatch........................ 61 6.11 Debugging Route Matching................................. 62 6.12 Route View Callable Registration and Lookup Details................... 63 6.13 References.......................................... 63 7 Views 65 7.1 View Callables....................................... 65 7.2 Defining a View Callable as a Function........................... 66 7.3 Defining a View Callable as a Class............................ 66 7.4 View Callable Responses.................................. 67 7.5 Using Special Exceptions In View Callables........................ 67 7.5.1 HTTP Exceptions.................................. 68 7.5.2 How Pyramid Uses HTTP Exceptions....................... 69 7.6 Custom Exception Views.................................. 69 7.7 Using a View Callable to Do an HTTP Redirect...................... 70 7.8 Handling Form Submissions in View Callables (Unicode and Character Set Issues)... 71 7.9 Alternate View Callable Argument/Calling Conventions.................. 73 7.10 Pylons-1.0-Style “Controller” Dispatch.......................... 74 8 Renderers 75 8.1 Writing View Callables Which Use a Renderer...................... 76 8.2 Built-In Renderers..................................... 77 8.2.1 string: String Renderer............................. 77 8.2.2 json: JSON Renderer............................... 78 8.3 JSONP Renderer...................................... 78 8.3.1 *.pt or *.txt: Chameleon Template Renderers................ 80 8.3.2 *.mak or *.mako: Mako Template Renderer.................. 81 8.4 Varying Attributes of Rendered Responses......................... 82 8.5 Deprecated Mechanism to Vary Attributes of Rendered Responses............ 83 8.6 Adding and Changing Renderers.............................. 84 8.6.1 Adding a New Renderer.............................. 84 8.6.2 Changing an Existing Renderer.......................... 86 8.7 Overriding A Renderer At Runtime............................ 87 9 Templates 89 9.1 Using Templates Directly.................................. 89 9.2 System Values Used During Rendering........................... 93 9.3 Templates Used as Renderers via Configuration...................... 94 9.4 Chameleon ZPT Templates................................. 95 9.4.1 A Sample ZPT Template.............................. 96 9.4.2 Using ZPT Macros in Pyramid........................... 97 9.5 Templating with Chameleon Text Templates........................ 98 9.6 Side Effects of Rendering a Chameleon Template..................... 98 9.7 Nicer Exceptions in Chameleon Templates......................... 99 9.8 Chameleon Template Internationalization......................... 100 9.9 Templating With Mako Templates............................. 100 9.9.1 A Sample Mako Template............................. 101 9.10 Automatically Reloading Templates............................ 102 9.11 Available Add-On Template System Bindings....................... 102 10 View Configuration 103 10.1 Mapping a Resource or URL Pattern to a View Callable.................. 103 10.1.1 View Configuration Parameters.......................... 104 10.1.2 Adding View Configuration Using the @view_config Decorator....... 110 10.1.3 Adding View Configuration Using add_view() ................ 113 10.1.4 Configuring View Security............................. 114 10.1.5 NotFound Errors................................. 114 10.2 Influencing HTTP Caching................................. 114 10.3 Debugging View Configuration............................... 115 11 Static Assets 117 11.1 Understanding Asset Specifications............................ 117 11.2 Serving Static Assets.................................... 118 11.2.1 Generating Static Asset URLs........................... 120 11.3 Advanced: Serving Static Assets Using a View Callable.................. 121 11.3.1 Root-Relative Custom Static View (URL Dispatch Only)............. 122 11.3.2 Registering A View Callable to Serve a “Static” Asset.............. 123 11.4 Overriding Assets...................................... 123 11.4.1 The override_asset API........................... 124 12 Request and Response Objects 127 12.1 Request........................................... 128 12.1.1