Pylons 0.9.6 Cheat Sheet

Author: Copyright (C) 2007 Dipl.-Inform. Christoph Haas <email@christoph-haas.de>
IRC:Meet me at #pylons on irc.freenode.net as Signum
License:

This document is published under the terms of the MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

Note

The source of the document is available from a Mercurial repository at http://workaround.org/cgi-bin/hg-pylons-cheatsheet - please send in patches to email@christoph-haas.de although you may be reading the document on wiki.pylonshq.com. Thanks.

Contents

Pylons

Installation

  • Debian/Ubuntu
    • Install: aptitude install python-pylons (available in lenny/testing or sid/unstable but not Etch!)
    • Update: aptitude update && aptitude install python-pylons
  • Easy-Install:
    • Install: easy_install Pylons
    • Update: easy_install -U Pylons
  • virtualenv

Project (Paste)

  • Create new project
    • paster create -t pylons myapplicationsname
    • Remove the public/index.html welcome page
    • Customize the routing in config/routing.py (e.g. set '' to a start controller)
  • Update project to new Pylons version: paster create -t pylons myapplicationsname (from above the directory where your development.ini is located)
  • Serve application via HTTP: paster serve --reload development.ini (application runs at http://localhost:5000)
  • Interactive shell: paster shell (install ipython for additional convenience)
  • Gory details of Pylons execution

development.ini

  • [server:main] (Paste)
    • use: points to egg of Paste's web server
    • host: the IP address the web server listens on
    • port: the TCP port the web server listens on
  • [app:main] (Pylons)
    • use: points to your application
    • full_stack: enables (by default) the error and exeption handling
    • cache_dir: directory where cached HTML templates and cookie-sessions are saved

(%(here)s refers the project's root directory (where the development.ini lives))

  • Accessing settings from the [app:main] section:

    from pylons import config
    my_setting = config['foo.bar']
    

Directory structure

data/sessions Cookie-based sessions are saved into files in this directory.
data/templates Cached HTML files that are rendered from your template files are stored here.
development.ini The startup configuration for Paste.
myapplication/config/ Global configuration files of your project. Used to define routes for URL dispatching, middleware (like for adding authentication) or the template system you prefer.
myapplication/controllers/ The location of the classes that contain your application logic. This code controls your application, renders templates, and queries the database.
myapplication/docs/ Put any documentation on the application here. Preferably in rest (restructured text) format.
myapplication/i18n/ Files that deal with localized message strings of your project. (i18n = internationalization)
myapplication/lib/ Contains files that set up a number of global variables and objects that you can use in your controllers. For example everything in lib/base.py is made available in every controller.
myapplication/model/ Here go your database models. They define the database schema and sets up ORM mappers.
myapplication/public/ Static files like images, CSS style sheets or Javascript files may go here.
myapplication/templates/ Your templates that render the actual HTML output are saved here.
myapplication/tests/ Every controller you create gets a counterpart to implement automated tests here.
README.txt Some basic instructions that you can give to the admininstrator who is supposed to install your application.
ez_setup, myapplication.egg-info, setup.cfg, setup.py Administrative files that are used to create an egg from your project that can be deployed on a web server then.
test.ini Similar to the development.ini. This file is used when you want to run automated tests on your project.

Controllers

Global objects

Configuration data is available through the config object

Routes

Mako (Templates)

Sample base template (to be inherited)

# -*- coding: utf-8 -*-
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
    <title>...........</title>
    ${ h.stylesheet_link_tag( '/style1.css', '/style2.css') }
    ${ h.javascript_include_tag( 'jquery.js', 'jquery.debug.js') }
    <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />
</head>
<body>
    <h1>My application</h1>
    ${ next.body() }
</body>
</html>

Inheriting from base template

# -*- coding: utf-8 -*-
<%inherit file="master.mako"/>
<p>Hello World</p>

Database access

Cookie-based Sessions

Formencode

Javascript libraries

Webhelpers

Internationalisation (i18n)

Unit Tests (Nose)

Community

Related add-ons

  • FormAlchemy: Automatically creates HTML forms for SQLAlchemy schemas (mapped classes)
  • Paginator: Helps split up large numbers of results into pages and lets the user navigate through the pages
  • DBSprockets: Automatically creates Toscawidget forms and Formencode Validators for SQLAlchemy schemas (mapped classes)

...