Pylons Reference Documentation Release 0.9.7 Ben Bangert, Graham Higgins, James Gardner January 09, 2013 CONTENTS 1 Getting Started 1 1.1 Requirements..............................................1 1.2 Installing................................................1 1.3 Creating a Pylons Project.......................................2 1.4 Running the application........................................3 1.5 Hello World...............................................4 2 Concepts of Pylons 7 2.1 The ‘Why’ of a Pylons Project.....................................7 2.2 WSGI Applications...........................................7 2.3 WSGI Middleware...........................................8 2.4 Controller Dispatch.......................................... 10 2.5 Paster.................................................. 10 2.6 Loading the Application........................................ 11 3 Pylons Tutorials 13 3.1 Quickwiki tutorial........................................... 13 3.2 Understanding Unicode........................................ 30 4 Controllers 39 4.1 Standard Controllers.......................................... 41 4.2 Using the WSGI Controller to provide a WSGI service...................... 43 4.3 Using the REST Controller with a RESTful API........................... 43 4.4 Using the XML-RPC Controller for XML-RPC requests...................... 46 5 Views 51 5.1 Templates................................................ 53 5.2 Passing Variables to Templates.................................... 53 5.3 Default Template Variables...................................... 54 5.4 Configuring Template Engines.................................... 55 5.5 Custom render() functions..................................... 56 5.6 Templating with Mako......................................... 57 6 Models 59 6.1 About the model............................................ 60 6.2 Model basics.............................................. 61 6.3 Working with SQLAlchemy...................................... 63 7 Configuration 77 7.1 Runtime Configuration........................................ 77 i 7.2 Environment.............................................. 79 7.3 URL Configuration........................................... 79 7.4 Middleware............................................... 81 7.5 Application Setup........................................... 83 8 Logging 85 8.1 Logging messages........................................... 85 8.2 Basic Logging configuration..................................... 86 8.3 Filtering log messages......................................... 87 8.4 Advanced Configuration....................................... 87 8.5 Request logging with Paste’s TransLogger............................. 88 8.6 Logging to wsgi.errors......................................... 89 9 Helpers 93 9.1 Pagination................................................ 93 9.2 Secure Form Tag Helpers....................................... 98 10 Forms 99 10.1 The basics................................................ 99 10.2 Getting Started............................................. 99 10.3 Using the Helpers........................................... 100 10.4 File Uploads............................................... 101 10.5 Validating user input with FormEncode............................... 102 10.6 Other Form Tools............................................ 105 11 Internationalization and Localization 107 11.1 Introduction............................................... 107 11.2 Getting Started............................................. 108 11.3 Using Babel............................................... 109 11.4 Back To Work.............................................. 111 11.5 Testing the Application........................................ 112 11.6 Fallback Languages.......................................... 112 11.7 Translations Within Templates.................................... 113 11.8 Lazy Translations............................................ 114 11.9 Producing a Python Egg........................................ 115 11.10 Plural Forms.............................................. 115 11.11 Summary................................................ 116 11.12 Further Reading............................................ 116 11.13 babel.core – Babel core classes.................................. 117 11.14 babel.localedata — Babel locale data............................. 117 11.15 babel.dates – Babel date classes................................. 117 11.16 babel.numbers – Babel number classes.............................. 117 12 Sessions 119 12.1 Sessions................................................. 119 12.2 Session Objects............................................. 119 12.3 Beaker.................................................. 120 12.4 Custom and caching middleware.................................. 123 12.5 Bulk deletion of expired db-held sessions.............................. 123 12.6 Using Session in Internationalization................................. 123 12.7 Using Session in Secure Forms.................................... 123 12.8 Hacking the session for no cookies.................................. 124 12.9 Using middleware (Beaker) with a composite app......................... 124 12.10 storing SA mapped objects in Beaker sessions........................... 125 ii 13 Caching 127 13.1 Using the Cache object......................................... 128 13.2 Using Cache keywords to render ................................... 128 13.3 Using the Cache Decorator...................................... 129 13.4 Caching Arbitrary Functions..................................... 130 13.5 ETag Caching.............................................. 130 13.6 Inside the Beaker Cache........................................ 131 14 Unit and functional testing 135 14.1 Unit Testing with webtest ...................................... 135 14.2 Example: Testing a Controller.................................... 136 14.3 Testing Pylons Objects......................................... 137 14.4 Testing Your Own Objects....................................... 138 14.5 Unit Testing............................................... 139 14.6 Functional Testing........................................... 139 15 Troubleshooting & Debugging 141 15.1 Interactive debugging......................................... 141 15.2 The Debugging Screen......................................... 141 15.3 Example: Exploring the Traceback.................................. 141 15.4 Email Options.............................................. 142 16 Upgrading 143 16.1 Upgrading from 0.9.6 -> 0.9.7..................................... 143 16.2 Moving from a pre-0.9.6 to 0.9.6................................... 144 17 Packaging and Deployment Overview 145 17.1 Egg Files................................................. 145 17.2 Installing as a Non-root User..................................... 145 17.3 Understanding the Setup Process.................................. 146 17.4 Deploying the Application...................................... 148 17.5 Advanced Usage............................................ 148 18 Running Pylons Apps with Other Web Servers 149 18.1 Using Fast-CGI............................................. 149 18.2 Apache Configuration......................................... 150 18.3 PrefixMiddleware........................................... 150 19 Documenting Your Application 153 19.1 Introduction............................................... 153 19.2 Tutorial................................................. 153 19.3 Learning ReStructuredText...................................... 154 19.4 Using Docstrings............................................ 154 19.5 Using doctest.............................................. 155 19.6 Summary................................................ 155 20 Distributing Your Application 157 20.1 Running Your Application...................................... 158 21 Python 2.3 Installation Instructions 159 21.1 Advice of end of support for Python 2.3 .............................. 159 21.2 Preparation............................................... 159 21.3 System-wide Install.......................................... 159 22 Windows Notes 161 iii 22.1 For Win2K or WinXP.......................................... 161 22.2 For Windows 95, 98 and ME..................................... 162 22.3 Finally.................................................. 162 23 Security policy for bugs 163 23.1 Receiving Security Updates...................................... 163 23.2 Reporting Security Issues....................................... 163 23.3 Minimising Risk............................................ 164 24 WSGI support 165 24.1 Paste and WSGI............................................ 165 24.2 Using a WSGI Application as a Pylons 0.9 Controller....................... 166 24.3 Running a WSGI Application From Within a Controller..................... 166 24.4 Configuring Middleware Within a Pylons Application...................... 167 24.5 The Cascade............................................... 168 24.6 Useful Resources............................................ 168 25 Advanced Pylons 169 25.1 WSGI, CLI scripts........................................... 169 25.2 Adding commands to Paster..................................... 171 25.3 Creating Paste templates....................................... 174 25.4 Using Entry Points to Write Plugins................................. 178 26 Pylons Modules 181 26.1 pylons.commands – Command line functions.........................