The Pyramid Web Application Development Framework Version 1.4.9
Total Page:16
File Type:pdf, Size:1020Kb
The Pyramid Web Application Development Framework Version 1.4.9 Chris McDonough Contents Front Matteri Copyright, Trademarks, and Attributions iii Typographical Conventionsv Author Introduction vii I Narrative Documentation1 1 Pyramid Introduction3 2 Installing Pyramid 23 3 Application Configuration 31 4 Creating Your First Pyramid Application 35 5 Creating a Pyramid Project 41 6 Startup 65 7 Request Processing 69 8 URL Dispatch 75 9 Views 99 10 Renderers 111 11 Templates 127 12 View Configuration 141 13 Static Assets 159 14 Request and Response Objects 169 15 Sessions 177 16 Using Events 185 17 Environment Variables and .ini File Settings 189 18 Logging 201 19 PasteDeploy Configuration Files 209 20 Command-Line Pyramid 213 21 Internationalization and Localization 231 22 Virtual Hosting 249 23 Unit, Integration, and Functional Testing 253 24 Resources 261 25 Much Ado About Traversal 273 26 Traversal 281 27 Security 293 28 Combining Traversal and URL Dispatch 305 29 Invoking a Subrequest 315 30 Using Hooks 321 31 Pyramid Configuration Introspection 347 32 Extending An Existing Pyramid Application 361 33 Advanced Configuration 367 34 Extending Pyramid Configuration 375 35 Thread Locals 383 36 Using the Zope Component Architecture in Pyramid 387 II Tutorials 393 37 ZODB + Traversal Wiki Tutorial 395 38 SQLAlchemy + URL Dispatch Wiki Tutorial 445 39 Converting a repoze.bfg Application to Pyramid 505 40 Running a Pyramid Application under mod_wsgi 509 III API Reference 513 41 pyramid.authorization 515 42 pyramid.authentication 517 43 pyramid.config 529 44 pyramid.events 573 45 pyramid.exceptions 579 46 pyramid.httpexceptions 581 47 pyramid.i18n 595 48 pyramid.interfaces 599 49 pyramid.location 617 50 pyramid.paster 619 51 pyramid.registry 621 52 pyramid.renderers 623 53 pyramid.request 629 54 pyramid.response 653 55 pyramid.scripting 661 56 pyramid.security 663 57 pyramid.settings 667 58 pyramid.testing 669 59 pyramid.threadlocal 673 60 pyramid.traversal 675 61 pyramid.url 681 62 pyramid.view 683 63 pyramid.wsgi 687 IV Glossary and Index 689 Glossary 691 Front Matter Copyright, Trademarks, and Attributions The Pyramid Web Application Development Framework, Version 1.1 by Chris McDonough Copyright © 2008-2011, Agendaless Consulting. ISBN-10: 0615445675 ISBN-13: 978-0615445670 First print publishing: February, 2011 All rights reserved. This material may be copied or distributed only subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License. You must give the original author credit. You may not use this work for commercial purposes. If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one. While the Pyramid documentation is offered under the Creative Commons Attribution- Nonconmmercial-Share Alike 3.0 United States License, the Pyramid software is offered under a less restrictive (BSD-like) license. All terms mentioned in this book that are known to be trademarks or service marks have been appropri- ately capitalized. However, use of a term in this book should not be regarded as affecting the validity of any trademark or service mark. Every effort has been made to make this book as complete and as accurate as possible, but no warranty or fitness is implied. The information provided is on as “as-is” basis. The author and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book. No patent liability is assumed with respect to the use of the information contained herein. iii Attributions Editor: Casey Duncan Contributors: Ben Bangert, Blaise Laflamme, Rob Miller, Mike Orr, Carlos de la Guardia, Paul Everitt, Tres Seaver, John Shipman, Marius Gedminas, Chris Rossi, Joachim Krebs, Xavier Spriet, Reed O’Brien, William Chambers, Charlie Choiniere, Jamaludin Ahmad, Graham Higgins, Patricio Paez, Michael Merickel, Eric Ongerth, Niall O’Higgins, Christoph Zwerschke, John Anderson, Atsushi Odagiri, Kirk Strauser, JD Navarro, Joe Dallago, Savoir-Faire Linux, Łukasz Fidosz, Christopher Lambacher, Claus Conrad, Chris Beelby, Phil Jenvey and a number of people with only pseudonyms on GitHub. Cover Designer: Hugues Laflamme of Kemeneur. Used with permission: The Request and Response Objects chapter is adapted, with permission, from documentation originally written by Ian Bicking. The Much Ado About Traversal chapter is adapted, with permission, from an article written by Rob Miller. The Logging is adapted, with permission, from the Pylons documentation logging chapter, originally written by Phil Jenvey. Print Production The print version of this book was produced using the Sphinx documentation generation system and the LaTeX typesetting system. Contacting The Publisher Please send documentation licensing inquiries, translation inquiries, and other business communications to Agendaless Consulting. Please send software and other technical queries to the Pylons-devel maillist. HTML Version and Source Code An HTML version of this book is freely available via http://docs.pylonsproject.org The source code for the examples used in this book are available within the Pyramid software distribution, always available via https://github.com/Pylons/pyramid iv Typographical Conventions Literals, filenames and function arguments are presented using the following style: argument1 Warnings, which represent limitations and need-to-know information related to a topic or concept are presented in the following style: This is a warning. Notes, which represent additional information related to a topic or concept are presented in the following style: This is a note. We present Python method names using the following style: pyramid.config.Configurator.add_view() We present Python class names, module names, attributes and global variables using the following style: pyramid.config.Configurator.registry References to glossary terms are presented using the following style: Pylons URLs are presented using the following style: Pylons References to sections and chapters are presented using the following style: Traversal Code and configuration file blocks are presented in the following style: v 1 def foo(abc): 2 pass Example blocks representing UNIX shell commands are prefixed with a $ character, e.g.: $ ../bin/nosetests Example blocks representing Windows cmd.exe commands are prefixed with a drive letter and/or a directory name, e.g.: c:\examples> ..\Scripts\nosetests Sometimes, when it’s unknown which directory is current, Windows cmd.exe example block commands are prefixed only with a > character, e.g.: > ..\Scripts\nosetests When a command that should be typed on one line is too long to fit on a page, the backslash \ is used to indicate that the following printed line should actually be part of the command: c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \ --cover-erase --with-coverage A sidebar, which presents a concept tangentially related to content discussed on a page, is rendered like so: This is a sidebar Sidebar information. vi Author Introduction Welcome to “The Pyramid Web Application Framework”. In this introduction, I’ll describe the audience for this book, I’ll describe the book content, I’ll provide some context regarding the genesis of Pyramid, and I’ll thank some important people. I hope you enjoy both this book and the software it documents. I’ve had a blast writing both. Audience This book is aimed primarily at a reader that has the following attributes: • At least a moderate amount of Python experience. • A familiarity with web protocols such as HTTP and CGI. If you fit into both of these categories, you’re in the direct target audience for this book. But don’t worry, even if you have no experience with Python or the web, both are easy to pick up “on the fly”. Python is an excellent language in which to write applications; becoming productive in Python is almost mind-blowingly easy. If you already have experience in another language such as Java, Visual Basic, Perl, Ruby, or even C/C++, learning Python will be a snap; it should take you no longer than a couple of days to become modestly productive. If you don’t have previous programming experience, it will be slightly harder, and it will take a little longer, but you’d be hard-pressed to find a better “first language.” Web technology familiarity is assumed in various places within the book. For example, the book doesn’t try to define common web-related concepts like “URL” or “query string.” Likewise, the book describes various interactions in terms of the HTTP protocol, but it does not describe how the HTTP protocol works in detail. Like any good web framework, though, Pyramid shields you from needing to know most of the gory details of web protocols and low-level data structures. As a result, you can usually avoid becoming “blocked” while you read this book even if you don’t yet deeply understand web technologies. vii Book Content This book is divided into three major parts: Narrative Documentation This is documentation which describes Pyramid concepts in narrative form, written in a largely conversational tone. Each narrative documentation chapter describes an isolated Pyra- mid concept. You should be able to get useful information out of the narrative chapters if you read them out-of-order, or when you need only a reminder about a particular topic while you’re developing an application. Tutorials Each tutorial builds a sample application or implements a set of concepts with a sample; it then describes the application or concepts in terms of the sample. You should read the tutorials if you want a guided tour of Pyramid. API Reference Comprehensive reference material for every public API exposed by Pyramid. The API doc- umentation is organized alphabetically by module name. The Genesis of repoze.bfg Before the end of 2010, Pyramid was known as repoze.bfg. I wrote repoze.bfg after many years of writing applications using Zope.