book

The Definitive Guide to Pylons

Name: The Definitive Guide to Pylons
Author: James Gardner
ISBN: 9781590599341

by James Gardner

December 2008

Intermediate to advanced

564 pages

15h 59m

English

Apress

Read now

Unlock full access

Copyright
About the Author
About the Technical Reviewer
Acknowledgments
Source Code and Updates
1. Getting Started
1. Introducing Pylons
1.1. The Old Way: CGI Scripts1.2. The Pylons Way1.2.1. Model View Controller Architecture1.2.2. Convention Over Configuration1.2.3. Loose Coupling and Clean Separation1.2.4. Other Features1.3. The Python Language1.3.1. Python 3.01.4. The Pylons Community1.5. Pylons Components1.6. What's Coming Up1.7. Summary
2. Installing Pylons
2.1. Quick Start to Installation for the Impatient2.2. Installation in Detail2.2.1. Using the Python Package Index2.2.2. Setting Up a Virtual Python Environment2.2.3. Working with Easy Install2.2.4. Installing Pylons2.2.5. Understanding Eggs2.3. Advanced Topics2.3.1. Activating and Deactivating a Virtual Python Environment2.3.2. Setting Virtualenv Options2.3.3. Choosing Package Versions with Easy Install2.3.4. Installing with a Proxy Server2.3.5. Troubleshooting Easy Install2.3.6. Working on the Bleeding Edge2.4. Platform-Specific Notes2.4.1. Linux and BSD2.4.2. Mac OS X2.4.3. Windows2.5. Summary
3. Exploring Pylons
3.1. Exploring Pylons' Dependencies3.2. Creating a Pylons Project3.3. Serving a Pylons Application3.3.1. Configuration Files3.3.2. The Paste HTTP Server3.3.3. Static Files3.3.4. A Word About IP Addresses, Hosts, and Security3.4. Exploring a Pylons Project's Directory Structure3.5. Creating a Controller and Modifying the Routes3.6. Understanding How HTTP Works3.7. Exploring the Environment3.8. Understanding the Pylons Request and Response3.8.1. Request3.8.2. Response3.9. Understanding Pylons Globals3.9.1. Helpers3.9.2. Context Object3.9.3. App Globals Object3.10. Configuring Pylons3.11. Controller Imports3.12. Summary
4. Tracking Down and Handling Problems
4.1. Using the Pylons Interactive Debugger4.1.1. Production Use4.1.2. E-mail Options4.2. Summary

5. Using View Templates
5.1.5.1.1. Using the Template Context c Global5.1.2. Basic Template Syntax5.1.3. Default Pylons Template Variables5.1.4. Mako Runtime Built-Ins5.1.5. Separation of Logic and View5.2. Security Considerations and WebHelpers5.2.1. Writing Your Own Helpers5.2.2. Applying Filters in Templates5.3. Structuring Template Code5.3.1. Using <%def> Blocks5.3.2. The Mako Cache5.3.3. Capturing Output5.3.4. Namespaces5.3.5. The body() Def5.4. Template Inheritance Chains5.4.1. Simple Inheritance5.4.2. Next Namespace5.4.3. Parent Namespace5.5. Behind the Scenes5.5.1. Caching5.5.2. Alternative Template Languages5.5.3. Multiple Template Languages5.5.4. Working with Your Own Templating Language5.6. Summary
6. Working with Forms and Validators
6.1. The Basics6.1.1. POST vs. GET6.1.2. The Resubmitted Data Problem6.2. Building Forms with Helpers6.3. Uploading Files6.4. Handling Forms Manually6.5. Introducing FormEncode6.5.1. Configuring Validators6.6. Using HTML Fill6.6.1. Error Message Formatting6.6.2. Render Arguments6.7. Doing Validation the Quick Way6.8. Using Custom Validators6.9. Solving the Repeating Fields Problem6.9.1. Creating the Form6.10. Summary
7. Introducing the Model and SQLAlchemy
7.1. Storing Data in the Filesystem7.2. Storing Data in Amazon S37.3. Exploring Database Approaches7.3.1. Object Databases7.3.2. XML Databases7.3.3. Relational Database Management Systems7.3.4. Object-Relational Mappers7.4. Setting Up SQLAlchemy7.4.1. Installing the DB-API Driver7.4.2. Installing SQLAlchemy7.4.3. Creating a Database7.5. Exploring SQLAlchemy's Architecture7.5.1. Engine API7.5.2. Metadata and Type APIs7.5.3. SQL Expression API7.5.3.1. SQL Injection Attacks7.5.3.2. Selecting Results7.6. Exploring the Object-Relational API7.6.1. Object-Relational Principles7.6.2. More Metadata7.6.3. Classes and Mappers7.6.4. Understanding the Session7.6.5. Exploring the Session7.6.6. Queries7.6.7. Working with Objects7.6.8. Declarative API7.7. Maintaining Performance7.8. Summary
8. Starting the SimpleSite Tutorial
8.1. Getting Started with SimpleSite8.2. Exploring the Template Structure8.3. Using SQLAlchemy in Pylons8.3.1. Configuring the Engine8.3.2. Creating the Model8.3.3. Creating the Database Tables8.3.4. Querying Data8.3.5. Understanding the Role of the Base Controller8.3.6. Using a SQLAlchemy Session in Pylons8.4. Updating the Controller to Support Editing Pages8.4.1. view()8.4.2. new()8.4.3. create()8.4.4. edit() and save()8.4.5. list()8.4.6. delete()8.5. Updating the Footer8.6. Using Pagination8.7. Formatting Dates and Times8.8. Using Sessions and a Flash Message8.9. Summary
2. Advanced Pylons
9. URLs, Routing, and Dispatch
9.1. Pylons Routing in Detail9.1.1. Pylons Dispatch9.2. Routes in Detail9.2.1. Route Parts9.2.2. Default Variables9.3. Generating URLs9.3.1. Named Routes9.3.2. Static Named Routes9.3.3. Internal Static Routes9.4. Choosing Good URLs9.5. Unnecessary Routes Features9.5.1. Route Minimization9.5.2. Route Memory9.5.3. Implicit Defaults9.5.4. Best Practice9.6. Advanced URL Routing9.6.1. Requirements9.6.2. Conditions9.6.3. Filter Functions9.7. Summary
10. Unicode
10.1. A Brief History10.2. Introducing Unicode10.3. Unicode in Python 210.3.1. Unicode Literals10.3.2. Handling Errors10.3.3. Decoding Unicode10.3.4. Encoding Unicode10.3.5. Python Source Code Encoding10.3.6. Unicode and Files10.4. Unicode Considerations in Pylons Programming10.4.1. Request Parameters10.4.2. Templating10.4.3. Output Encoding10.4.4. Databases10.4.5. A Complete Request Cycle10.5. Summary
11. Internationalization and Localization
11.1. Understanding the Process11.1.1. Marking Strings for Internationalization11.1.2. Extracting Messages and Handling Translations11.2. Seeing It in Action11.2.1. Using Babel11.2.2. Supporting Multiple Languages11.2.3. Updating the Catalog11.2.4. Translations Within Templates11.2.5. Babel Extractors11.2.6. Setting the Language in the Config File11.2.7. Using a Session to Store the User's Language11.3. Advanced Internationalization Techniques11.3.1. Fallback Languages11.3.2. Lazy Translations11.3.3. Plural Forms11.3.4. Search Engine Considerations11.4. Summary
12. Testing
12.1. Types of Testing and the Development Process12.2. Unit Testing with nose12.2.1. Introducing nose12.2.2. Search Locations12.3. Functional Testing12.3.1. How Does the Test Setup Work?12.3.2. Testing the save() Action12.3.3. Testing Your Own Objects12.4. Interactive Shell12.5. Summary
13. Documentation
13.1. Python's Documentation Tools13.1.1. Comments13.1.2. Docstrings13.1.3. The Built-In help() Function13.2. Doctests13.3. Introducing reStructuredText13.4. Introducing Sphinx13.4.1. Using Sphinx13.4.2. Documenting Python Source Code13.4.3. Automatically Generating Documentation13.4.4. Syntax Highlighting13.5. Summary
14. SimpleSite Tutorial Part 2
14.1. Comments System: One-to-Many Mappings14.1.1. Planning the Controller14.1.2. Modifying the Routes14.1.3. Creating the Controller14.1.4. Updating the Controller to Handle Comments14.1.5. Setting the Page ID Automatically14.2. Updating the Page View14.2.1. Handling Deleted Pages14.3. Tags: Many-to-Many Mappings14.3.1. Creating the tag Controller14.3.2. Constraining Tag Names14.4. Adding Tags to Pages14.4.1. Deleting Tags and Pages14.5. Creating a Navigation Hierarchy14.5.1. Using Inheritance in SQLAlchemy14.5.2. Setting Up Initial Data14.5.3. Creating the Controllers14.5.4. The Page Controller14.6. Changing the Routing14.7. Adding the Navigation Elements14.8. Adding Some Style14.9. Summary
15. CSS, JavaScript, and Ajax
15.1. Adding YUI to Your Project15.2. Resetting the Browser CSS15.3. Fonts15.4. Grids15.4.1. Template Preset Grids15.4.2. Nested Grids15.4.3. Special Nested Grids15.5. Updating SimpleSite to Use CSS Grids15.6. Introducing Firebug15.7. Introducing JavaScript15.8. JavaScript Essentials15.8.1. Operators of Interest15.8.2. Types15.8.3. Functions15.8.4. Function Scope and Closures15.8.5. Objects15.8.6. this15.8.7. Namespaces15.8.8. Inheritance15.8.9. Prototypes15.8.10. JavaScript in HTML15.9. The Document Object Model15.9.1. Navigating the DOM15.9.2. Manipulating the DOM15.10. The Event Model15.10.1. Same Origin Policy15.10.2. Browser Detection vs. Feature Detection15.11. Adding Animation to the SimpleSite Flash Message15.12. Ajax15.12.1. Debugging Ajax Requests15.12.2. JSON15.13. Reducing Page Load Time15.14. Summary
3. Expert Pylons
16. The Web Server Gateway Interface (WSGI)
16.1. Introducing WSGI16.1.1. WSGI Applications16.1.1.1. Using Instances of Classes16.1.2. WSGI in Pylons Controllers16.1.3. WSGI Servers16.1.4. WSGI Middleware16.2. Writing WSGI Middleware16.2.1. Modifying the Environment16.2.2. Changing the Status and Headers16.2.3. Handling Errors16.2.4. Altering the Response16.2.5. Testing the Gzip Middleware16.3. Summary
17. Pylons' Internal Architecture
17.1. A Bit of History17.2. Egg Entry Points17.2.1. Entry Points and websetup.py17.3. The Pylons Config File17.3.1. Default Config Options17.3.2. Constructing a Server17.3.3. Constructing an Application17.3.4. Composite Applications17.3.5. Pipelines and Filters17.3.6. Understanding Factories17.3.7. Alternative Ways of Specifying Factories17.3.8. Configuration Inheritance17.4. Accessing the Pylons WSGI Application and Other Objects Programmatically17.4.1. Accessing the Server, Application, and Filters17.4.2. Accessing Configuration Options17.4.3. Creating a Pylons Application with Paste Deploy17.5. The Pylons Middleware Stack17.5.1. Application State vs. Request State17.6. Creating an Application17.6.1. Loading the Pylons Environment17.6.2. The PylonsApp Instance17.6.3. The Middleware Chain17.7. Handling a Request17.7.1. The Cascade17.7.2. The Registry Manager, StackedObjectProxy, and Pylons Globals17.7.3. Returning to the Middleware Chain17.7.4. The Role of PylonsApp17.7.5. The Role of WSGIController17.8. Handling the Response17.8.1. abort(), redirect_to(), and HTTPException17.8.2. Exception Handling17.8.3. Error Documents17.8.4. Streaming Content17.8.5. Returning Unicode from an Action17.9. Summary
18. Authentication and Authorization
18.1. Private Data18.2. A Homegrown Solution18.3. AuthKit18.4. Authentication Middleware18.5. Authorization and Permissions18.5.1. The Authorization Decorator18.5.2. The Authorization Middleware18.5.3. The Authorization Function18.5.4. Protecting a Controller18.6. Groups, Roles, and Permissions18.7. User Management API18.8. Cookie Options18.9. Alternative Methods18.10. Functional Testing18.11. General Security Considerations18.11.1. Secure Sockets Layer18.11.2. Encrypted Passwords18.12. Summary
19. SimpleSite Tutorial Part 3
19.1. Authentication and Authorization19.1.1. Setting Up the Middleware19.1.2. Adjusting websetup.py19.1.3. Protecting Controller Actions19.1.4. Changing Templates Based on Permissions19.1.5. Signing In and Signing Out19.1.6. Styling the Sign-in Screen19.1.7. Protecting the Rest of the Actions19.1.8. Using the AuthKit User Management API19.2. Error Documents19.2.1. Customizing the Error Documents for SimpleSite19.3. Adding a WYSIWYG Interface19.4. Configuring the setup.py File19.4.1. Choosing a Version Number19.4.2. Configuring Dependencies19.4.3. Extra Dependencies19.4.4. Extra Dependency Links19.4.5. Specifying Metadata19.4.6. Customizing the Long Description19.4.7. Customizing the Production Config File Template19.5. Packaging a Pylons Project for Distribution19.5.1. Building an Egg File19.5.2. Publishing an Egg on the Python Package Index19.6. Making SimpleSite into a Paste Project Template19.6.1. Introducing Project Template Variables19.6.2. Using Project Template Variables19.6.3. Completing the Cycle19.7. Summary
20. Logging
20.1. Getting Started with Pylons Logging20.2. Understanding the logging Module20.2.1. Understanding Log Levels20.2.2. Logging Variables20.2.3. Logging in Templates20.3. Introducing Logging Configuration20.3.1. Logger Sections20.3.2. Handler Sections20.3.3. Formatter Sections20.4. Redirecting Log Output Using Handlers20.4.1. Logging to a File20.4.2. Logging to wsgi.errors20.4.3. Configuring Which Messages Are Logged20.5. Controlling Propagation with Loggers20.5.1. Using Propagation to Filter Messages20.5.2. Summarizing Propagation Options20.6. Capturing Log Output from Other Software20.6.1. Capturing SQLAlchemy Log Messages Using Propagation20.6.2. Capturing AuthKit Messages Using a Handler20.7. Production Configuration20.8. Summary
21. Deployment
21.1. Choosing or Setting Up a Python Environment21.1.1. Using the System Python Environment21.1.2. Platform Packages or Easy Install?21.1.3. Using Buildout21.1.4. Setting Up a Virtual Python Environment21.1.5. Dealing with Activate21.2. Installing the Required Software into the Environment21.3. Creating a Config File for the Application21.4. Setting Up the Application Instance21.5. Serving the Application from the Installed Environment21.6. Deployment Options21.6.1. Embedding21.6.2. Proxying21.7. Using Apache to Proxy Requests to Pylons21.7.1. Setting Up Log Files21.7.2. Creating init Scripts21.7.3. Restarting Stopped Applications21.8. Embedding Pylons in Apache with mod_wsgi21.8.1. Setting Up a Virtual Host21.8.2. Troubleshooting21.9. Deployment on Windows21.10. Summary
A. Licenses
A.1. GNU Free Documentation LicenseA.1.1. 0. PREAMBLEA.1.2. 1. APPLICABILITY AND DEFINITIONSA.1.3. 2. VERBATIM COPYINGA.1.4. 3. COPYING IN QUANTITYA.1.5. 4. MODIFICATIONSA.1.6. 5. COMBINING DOCUMENTSA.1.7. 6. COLLECTIONS OF DOCUMENTSA.1.8. 7. AGGREGATION WITH INDEPENDENT WORKSA.1.9. 8. TRANSLATIONA.1.10. 9. TERMINATIONA.1.11. 10. FUTURE REVISIONS OF THIS LICENSEA.1.12. ADDENDUM: How to use this License for your documentsA.2. Pylons LicenseA.2.1. ALL TEMPLATES GENERATED ARE COVERED UNDER THE FOLLOWING LICENSE:A.3. YUI License

Content preview from The Definitive Guide to Pylons

Chapter 13. Documentation

In this chapter, you'll learn about the tools you can use to document your Pylons applications. Documentation can take a number of forms:

Source code documentation (comments and docstrings)
API documentation
User guides
Developer guides

The combination of approaches you choose to use for your project will depend on who will be using it and in what manner. For example, if you are developing an application on your own for your home page, you might decide that source code documentation is sufficient. If you are writing a library to support a Pylons application and you hope other developers will use it, then API documentation will be important. If you are creating an application like the SimpleSite tutorial application that might ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Publisher Resources

ISBN: 9781590599341Purchase book

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

The Definitive Guide to Pylons

by James Gardner

Chapter 13. Documentation

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.