You are previewing The Definitive Guide to Pylons.
O'Reilly logo
The Definitive Guide to Pylons

Book Description

Spurred by the enormous popularity of Ruby on Rails, web frameworks have revolutionized the way developers of all programming languages tackle the often complex task of web application development. Some of the most exciting activity in this area can be seen in the Python community, one of the wildly popular frameworks to enter the fray being Pylons (http://pylonshq.com/).

Cofounder and lead developer James Gardner brings you a comprehensive introduction to Pylons, the web framework that uses the best of Ruby, Python, and Perl and the emerging WSGI standard to provide structure and flexibility. With expert guidance from the author, you'll learn how to create your own Pylons-driven web site using SQLAlchemy and FormEncode and attain the mastery of advanced Pylons features, such as internationalization and localization, packaging and deployment.

Table of Contents

  1. Copyright
  2. About the Author
  3. About the Technical Reviewer
  4. Acknowledgments
  5. Source Code and Updates
  6. 1. Getting Started
    1. 1. Introducing Pylons
      1. 1.1. The Old Way: CGI Scripts
      2. 1.2. The Pylons Way
        1. 1.2.1. Model View Controller Architecture
        2. 1.2.2. Convention Over Configuration
        3. 1.2.3. Loose Coupling and Clean Separation
        4. 1.2.4. Other Features
      3. 1.3. The Python Language
        1. 1.3.1. Python 3.0
      4. 1.4. The Pylons Community
      5. 1.5. Pylons Components
      6. 1.6. What's Coming Up
      7. 1.7. Summary
    2. 2. Installing Pylons
      1. 2.1. Quick Start to Installation for the Impatient
      2. 2.2. Installation in Detail
        1. 2.2.1. Using the Python Package Index
        2. 2.2.2. Setting Up a Virtual Python Environment
        3. 2.2.3. Working with Easy Install
        4. 2.2.4. Installing Pylons
        5. 2.2.5. Understanding Eggs
      3. 2.3. Advanced Topics
        1. 2.3.1. Activating and Deactivating a Virtual Python Environment
        2. 2.3.2. Setting Virtualenv Options
        3. 2.3.3. Choosing Package Versions with Easy Install
        4. 2.3.4. Installing with a Proxy Server
        5. 2.3.5. Troubleshooting Easy Install
        6. 2.3.6. Working on the Bleeding Edge
      4. 2.4. Platform-Specific Notes
        1. 2.4.1. Linux and BSD
        2. 2.4.2. Mac OS X
        3. 2.4.3. Windows
      5. 2.5. Summary
    3. 3. Exploring Pylons
      1. 3.1. Exploring Pylons' Dependencies
      2. 3.2. Creating a Pylons Project
      3. 3.3. Serving a Pylons Application
        1. 3.3.1. Configuration Files
        2. 3.3.2. The Paste HTTP Server
        3. 3.3.3. Static Files
        4. 3.3.4. A Word About IP Addresses, Hosts, and Security
      4. 3.4. Exploring a Pylons Project's Directory Structure
      5. 3.5. Creating a Controller and Modifying the Routes
      6. 3.6. Understanding How HTTP Works
      7. 3.7. Exploring the Environment
      8. 3.8. Understanding the Pylons Request and Response
        1. 3.8.1. Request
        2. 3.8.2. Response
      9. 3.9. Understanding Pylons Globals
        1. 3.9.1. Helpers
        2. 3.9.2. Context Object
        3. 3.9.3. App Globals Object
      10. 3.10. Configuring Pylons
      11. 3.11. Controller Imports
      12. 3.12. Summary
    4. 4. Tracking Down and Handling Problems
      1. 4.1. Using the Pylons Interactive Debugger
        1. 4.1.1. Production Use
        2. 4.1.2. E-mail Options
      2. 4.2. Summary
    5. 5. Using View Templates
      1. 5.1.
        1. 5.1.1. Using the Template Context c Global
        2. 5.1.2. Basic Template Syntax
        3. 5.1.3. Default Pylons Template Variables
        4. 5.1.4. Mako Runtime Built-Ins
        5. 5.1.5. Separation of Logic and View
      2. 5.2. Security Considerations and WebHelpers
        1. 5.2.1. Writing Your Own Helpers
        2. 5.2.2. Applying Filters in Templates
      3. 5.3. Structuring Template Code
        1. 5.3.1. Using <%def> Blocks
        2. 5.3.2. The Mako Cache
        3. 5.3.3. Capturing Output
        4. 5.3.4. Namespaces
        5. 5.3.5. The body() Def
      4. 5.4. Template Inheritance Chains
        1. 5.4.1. Simple Inheritance
        2. 5.4.2. Next Namespace
        3. 5.4.3. Parent Namespace
      5. 5.5. Behind the Scenes
        1. 5.5.1. Caching
        2. 5.5.2. Alternative Template Languages
        3. 5.5.3. Multiple Template Languages
        4. 5.5.4. Working with Your Own Templating Language
      6. 5.6. Summary
    6. 6. Working with Forms and Validators
      1. 6.1. The Basics
        1. 6.1.1. POST vs. GET
        2. 6.1.2. The Resubmitted Data Problem
      2. 6.2. Building Forms with Helpers
      3. 6.3. Uploading Files
      4. 6.4. Handling Forms Manually
      5. 6.5. Introducing FormEncode
        1. 6.5.1. Configuring Validators
      6. 6.6. Using HTML Fill
        1. 6.6.1. Error Message Formatting
        2. 6.6.2. Render Arguments
      7. 6.7. Doing Validation the Quick Way
      8. 6.8. Using Custom Validators
      9. 6.9. Solving the Repeating Fields Problem
        1. 6.9.1. Creating the Form
      10. 6.10. Summary
    7. 7. Introducing the Model and SQLAlchemy
      1. 7.1. Storing Data in the Filesystem
      2. 7.2. Storing Data in Amazon S3
      3. 7.3. Exploring Database Approaches
        1. 7.3.1. Object Databases
        2. 7.3.2. XML Databases
        3. 7.3.3. Relational Database Management Systems
        4. 7.3.4. Object-Relational Mappers
      4. 7.4. Setting Up SQLAlchemy
        1. 7.4.1. Installing the DB-API Driver
        2. 7.4.2. Installing SQLAlchemy
        3. 7.4.3. Creating a Database
      5. 7.5. Exploring SQLAlchemy's Architecture
        1. 7.5.1. Engine API
        2. 7.5.2. Metadata and Type APIs
        3. 7.5.3. SQL Expression API
          1. 7.5.3.1. SQL Injection Attacks
          2. 7.5.3.2. Selecting Results
      6. 7.6. Exploring the Object-Relational API
        1. 7.6.1. Object-Relational Principles
        2. 7.6.2. More Metadata
        3. 7.6.3. Classes and Mappers
        4. 7.6.4. Understanding the Session
        5. 7.6.5. Exploring the Session
        6. 7.6.6. Queries
        7. 7.6.7. Working with Objects
        8. 7.6.8. Declarative API
      7. 7.7. Maintaining Performance
      8. 7.8. Summary
    8. 8. Starting the SimpleSite Tutorial
      1. 8.1. Getting Started with SimpleSite
      2. 8.2. Exploring the Template Structure
      3. 8.3. Using SQLAlchemy in Pylons
        1. 8.3.1. Configuring the Engine
        2. 8.3.2. Creating the Model
        3. 8.3.3. Creating the Database Tables
        4. 8.3.4. Querying Data
        5. 8.3.5. Understanding the Role of the Base Controller
        6. 8.3.6. Using a SQLAlchemy Session in Pylons
      4. 8.4. Updating the Controller to Support Editing Pages
        1. 8.4.1. view()
        2. 8.4.2. new()
        3. 8.4.3. create()
        4. 8.4.4. edit() and save()
        5. 8.4.5. list()
        6. 8.4.6. delete()
      5. 8.5. Updating the Footer
      6. 8.6. Using Pagination
      7. 8.7. Formatting Dates and Times
      8. 8.8. Using Sessions and a Flash Message
      9. 8.9. Summary
  7. 2. Advanced Pylons
    1. 9. URLs, Routing, and Dispatch
      1. 9.1. Pylons Routing in Detail
        1. 9.1.1. Pylons Dispatch
      2. 9.2. Routes in Detail
        1. 9.2.1. Route Parts
        2. 9.2.2. Default Variables
      3. 9.3. Generating URLs
        1. 9.3.1. Named Routes
        2. 9.3.2. Static Named Routes
        3. 9.3.3. Internal Static Routes
      4. 9.4. Choosing Good URLs
      5. 9.5. Unnecessary Routes Features
        1. 9.5.1. Route Minimization
        2. 9.5.2. Route Memory
        3. 9.5.3. Implicit Defaults
        4. 9.5.4. Best Practice
      6. 9.6. Advanced URL Routing
        1. 9.6.1. Requirements
        2. 9.6.2. Conditions
        3. 9.6.3. Filter Functions
      7. 9.7. Summary
    2. 10. Unicode
      1. 10.1. A Brief History
      2. 10.2. Introducing Unicode
      3. 10.3. Unicode in Python 2
        1. 10.3.1. Unicode Literals
        2. 10.3.2. Handling Errors
        3. 10.3.3. Decoding Unicode
        4. 10.3.4. Encoding Unicode
        5. 10.3.5. Python Source Code Encoding
        6. 10.3.6. Unicode and Files
      4. 10.4. Unicode Considerations in Pylons Programming
        1. 10.4.1. Request Parameters
        2. 10.4.2. Templating
        3. 10.4.3. Output Encoding
        4. 10.4.4. Databases
        5. 10.4.5. A Complete Request Cycle
      5. 10.5. Summary
    3. 11. Internationalization and Localization
      1. 11.1. Understanding the Process
        1. 11.1.1. Marking Strings for Internationalization
        2. 11.1.2. Extracting Messages and Handling Translations
      2. 11.2. Seeing It in Action
        1. 11.2.1. Using Babel
        2. 11.2.2. Supporting Multiple Languages
        3. 11.2.3. Updating the Catalog
        4. 11.2.4. Translations Within Templates
        5. 11.2.5. Babel Extractors
        6. 11.2.6. Setting the Language in the Config File
        7. 11.2.7. Using a Session to Store the User's Language
      3. 11.3. Advanced Internationalization Techniques
        1. 11.3.1. Fallback Languages
        2. 11.3.2. Lazy Translations
        3. 11.3.3. Plural Forms
        4. 11.3.4. Search Engine Considerations
      4. 11.4. Summary
    4. 12. Testing
      1. 12.1. Types of Testing and the Development Process
      2. 12.2. Unit Testing with nose
        1. 12.2.1. Introducing nose
        2. 12.2.2. Search Locations
      3. 12.3. Functional Testing
        1. 12.3.1. How Does the Test Setup Work?
        2. 12.3.2. Testing the save() Action
        3. 12.3.3. Testing Your Own Objects
      4. 12.4. Interactive Shell
      5. 12.5. Summary
    5. 13. Documentation
      1. 13.1. Python's Documentation Tools
        1. 13.1.1. Comments
        2. 13.1.2. Docstrings
        3. 13.1.3. The Built-In help() Function
      2. 13.2. Doctests
      3. 13.3. Introducing reStructuredText
      4. 13.4. Introducing Sphinx
        1. 13.4.1. Using Sphinx
        2. 13.4.2. Documenting Python Source Code
        3. 13.4.3. Automatically Generating Documentation
        4. 13.4.4. Syntax Highlighting
      5. 13.5. Summary
    6. 14. SimpleSite Tutorial Part 2
      1. 14.1. Comments System: One-to-Many Mappings
        1. 14.1.1. Planning the Controller
        2. 14.1.2. Modifying the Routes
        3. 14.1.3. Creating the Controller
        4. 14.1.4. Updating the Controller to Handle Comments
        5. 14.1.5. Setting the Page ID Automatically
      2. 14.2. Updating the Page View
        1. 14.2.1. Handling Deleted Pages
      3. 14.3. Tags: Many-to-Many Mappings
        1. 14.3.1. Creating the tag Controller
        2. 14.3.2. Constraining Tag Names
      4. 14.4. Adding Tags to Pages
        1. 14.4.1. Deleting Tags and Pages
      5. 14.5. Creating a Navigation Hierarchy
        1. 14.5.1. Using Inheritance in SQLAlchemy
        2. 14.5.2. Setting Up Initial Data
        3. 14.5.3. Creating the Controllers
        4. 14.5.4. The Page Controller
      6. 14.6. Changing the Routing
      7. 14.7. Adding the Navigation Elements
      8. 14.8. Adding Some Style
      9. 14.9. Summary
    7. 15. CSS, JavaScript, and Ajax
      1. 15.1. Adding YUI to Your Project
      2. 15.2. Resetting the Browser CSS
      3. 15.3. Fonts
      4. 15.4. Grids
        1. 15.4.1. Template Preset Grids
        2. 15.4.2. Nested Grids
        3. 15.4.3. Special Nested Grids
      5. 15.5. Updating SimpleSite to Use CSS Grids
      6. 15.6. Introducing Firebug
      7. 15.7. Introducing JavaScript
      8. 15.8. JavaScript Essentials
        1. 15.8.1. Operators of Interest
        2. 15.8.2. Types
        3. 15.8.3. Functions
        4. 15.8.4. Function Scope and Closures
        5. 15.8.5. Objects
        6. 15.8.6. this
        7. 15.8.7. Namespaces
        8. 15.8.8. Inheritance
        9. 15.8.9. Prototypes
        10. 15.8.10. JavaScript in HTML
      9. 15.9. The Document Object Model
        1. 15.9.1. Navigating the DOM
        2. 15.9.2. Manipulating the DOM
      10. 15.10. The Event Model
        1. 15.10.1. Same Origin Policy
        2. 15.10.2. Browser Detection vs. Feature Detection
      11. 15.11. Adding Animation to the SimpleSite Flash Message
      12. 15.12. Ajax
        1. 15.12.1. Debugging Ajax Requests
        2. 15.12.2. JSON
      13. 15.13. Reducing Page Load Time
      14. 15.14. Summary
  8. 3. Expert Pylons
    1. 16. The Web Server Gateway Interface (WSGI)
      1. 16.1. Introducing WSGI
        1. 16.1.1. WSGI Applications
          1. 16.1.1.1. Using Instances of Classes
        2. 16.1.2. WSGI in Pylons Controllers
        3. 16.1.3. WSGI Servers
        4. 16.1.4. WSGI Middleware
      2. 16.2. Writing WSGI Middleware
        1. 16.2.1. Modifying the Environment
        2. 16.2.2. Changing the Status and Headers
        3. 16.2.3. Handling Errors
        4. 16.2.4. Altering the Response
        5. 16.2.5. Testing the Gzip Middleware
      3. 16.3. Summary
    2. 17. Pylons' Internal Architecture
      1. 17.1. A Bit of History
      2. 17.2. Egg Entry Points
        1. 17.2.1. Entry Points and websetup.py
      3. 17.3. The Pylons Config File
        1. 17.3.1. Default Config Options
        2. 17.3.2. Constructing a Server
        3. 17.3.3. Constructing an Application
        4. 17.3.4. Composite Applications
        5. 17.3.5. Pipelines and Filters
        6. 17.3.6. Understanding Factories
        7. 17.3.7. Alternative Ways of Specifying Factories
        8. 17.3.8. Configuration Inheritance
      4. 17.4. Accessing the Pylons WSGI Application and Other Objects Programmatically
        1. 17.4.1. Accessing the Server, Application, and Filters
        2. 17.4.2. Accessing Configuration Options
        3. 17.4.3. Creating a Pylons Application with Paste Deploy
      5. 17.5. The Pylons Middleware Stack
        1. 17.5.1. Application State vs. Request State
      6. 17.6. Creating an Application
        1. 17.6.1. Loading the Pylons Environment
        2. 17.6.2. The PylonsApp Instance
        3. 17.6.3. The Middleware Chain
      7. 17.7. Handling a Request
        1. 17.7.1. The Cascade
        2. 17.7.2. The Registry Manager, StackedObjectProxy, and Pylons Globals
        3. 17.7.3. Returning to the Middleware Chain
        4. 17.7.4. The Role of PylonsApp
        5. 17.7.5. The Role of WSGIController
      8. 17.8. Handling the Response
        1. 17.8.1. abort(), redirect_to(), and HTTPException
        2. 17.8.2. Exception Handling
        3. 17.8.3. Error Documents
        4. 17.8.4. Streaming Content
        5. 17.8.5. Returning Unicode from an Action
      9. 17.9. Summary
    3. 18. Authentication and Authorization
      1. 18.1. Private Data
      2. 18.2. A Homegrown Solution
      3. 18.3. AuthKit
      4. 18.4. Authentication Middleware
      5. 18.5. Authorization and Permissions
        1. 18.5.1. The Authorization Decorator
        2. 18.5.2. The Authorization Middleware
        3. 18.5.3. The Authorization Function
        4. 18.5.4. Protecting a Controller
      6. 18.6. Groups, Roles, and Permissions
      7. 18.7. User Management API
      8. 18.8. Cookie Options
      9. 18.9. Alternative Methods
      10. 18.10. Functional Testing
      11. 18.11. General Security Considerations
        1. 18.11.1. Secure Sockets Layer
        2. 18.11.2. Encrypted Passwords
      12. 18.12. Summary
    4. 19. SimpleSite Tutorial Part 3
      1. 19.1. Authentication and Authorization
        1. 19.1.1. Setting Up the Middleware
        2. 19.1.2. Adjusting websetup.py
        3. 19.1.3. Protecting Controller Actions
        4. 19.1.4. Changing Templates Based on Permissions
        5. 19.1.5. Signing In and Signing Out
        6. 19.1.6. Styling the Sign-in Screen
        7. 19.1.7. Protecting the Rest of the Actions
        8. 19.1.8. Using the AuthKit User Management API
      2. 19.2. Error Documents
        1. 19.2.1. Customizing the Error Documents for SimpleSite
      3. 19.3. Adding a WYSIWYG Interface
      4. 19.4. Configuring the setup.py File
        1. 19.4.1. Choosing a Version Number
        2. 19.4.2. Configuring Dependencies
        3. 19.4.3. Extra Dependencies
        4. 19.4.4. Extra Dependency Links
        5. 19.4.5. Specifying Metadata
        6. 19.4.6. Customizing the Long Description
        7. 19.4.7. Customizing the Production Config File Template
      5. 19.5. Packaging a Pylons Project for Distribution
        1. 19.5.1. Building an Egg File
        2. 19.5.2. Publishing an Egg on the Python Package Index
      6. 19.6. Making SimpleSite into a Paste Project Template
        1. 19.6.1. Introducing Project Template Variables
        2. 19.6.2. Using Project Template Variables
        3. 19.6.3. Completing the Cycle
      7. 19.7. Summary
    5. 20. Logging
      1. 20.1. Getting Started with Pylons Logging
      2. 20.2. Understanding the logging Module
        1. 20.2.1. Understanding Log Levels
        2. 20.2.2. Logging Variables
        3. 20.2.3. Logging in Templates
      3. 20.3. Introducing Logging Configuration
        1. 20.3.1. Logger Sections
        2. 20.3.2. Handler Sections
        3. 20.3.3. Formatter Sections
      4. 20.4. Redirecting Log Output Using Handlers
        1. 20.4.1. Logging to a File
        2. 20.4.2. Logging to wsgi.errors
        3. 20.4.3. Configuring Which Messages Are Logged
      5. 20.5. Controlling Propagation with Loggers
        1. 20.5.1. Using Propagation to Filter Messages
        2. 20.5.2. Summarizing Propagation Options
      6. 20.6. Capturing Log Output from Other Software
        1. 20.6.1. Capturing SQLAlchemy Log Messages Using Propagation
        2. 20.6.2. Capturing AuthKit Messages Using a Handler
      7. 20.7. Production Configuration
      8. 20.8. Summary
    6. 21. Deployment
      1. 21.1. Choosing or Setting Up a Python Environment
        1. 21.1.1. Using the System Python Environment
        2. 21.1.2. Platform Packages or Easy Install?
        3. 21.1.3. Using Buildout
        4. 21.1.4. Setting Up a Virtual Python Environment
        5. 21.1.5. Dealing with Activate
      2. 21.2. Installing the Required Software into the Environment
      3. 21.3. Creating a Config File for the Application
      4. 21.4. Setting Up the Application Instance
      5. 21.5. Serving the Application from the Installed Environment
      6. 21.6. Deployment Options
        1. 21.6.1. Embedding
        2. 21.6.2. Proxying
      7. 21.7. Using Apache to Proxy Requests to Pylons
        1. 21.7.1. Setting Up Log Files
        2. 21.7.2. Creating init Scripts
        3. 21.7.3. Restarting Stopped Applications
      8. 21.8. Embedding Pylons in Apache with mod_wsgi
        1. 21.8.1. Setting Up a Virtual Host
        2. 21.8.2. Troubleshooting
      9. 21.9. Deployment on Windows
      10. 21.10. Summary
    7. A. Licenses
      1. A.1. GNU Free Documentation License
        1. A.1.1. 0. PREAMBLE
        2. A.1.2. 1. APPLICABILITY AND DEFINITIONS
        3. A.1.3. 2. VERBATIM COPYING
        4. A.1.4. 3. COPYING IN QUANTITY
        5. A.1.5. 4. MODIFICATIONS
        6. A.1.6. 5. COMBINING DOCUMENTS
        7. A.1.7. 6. COLLECTIONS OF DOCUMENTS
        8. A.1.8. 7. AGGREGATION WITH INDEPENDENT WORKS
        9. A.1.9. 8. TRANSLATION
        10. A.1.10. 9. TERMINATION
        11. A.1.11. 10. FUTURE REVISIONS OF THIS LICENSE
        12. A.1.12. ADDENDUM: How to use this License for your documents
      2. A.2. Pylons License
        1. A.2.1. ALL TEMPLATES GENERATED ARE COVERED UNDER THE FOLLOWING LICENSE:
      3. A.3. YUI License