Pylons Reference Documentation Release 1.0.2
Total Page:16
File Type:pdf, Size:1020Kb
Pylons Reference Documentation Release 1.0.2 Ben Bangert, Graham Higgins, James Gardner, Philip Jenvey July 22, 2015 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........................................4 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 Controllers 13 3.1 Standard Controllers.......................................... 15 3.2 Using the WSGI Controller to provide a WSGI service...................... 17 3.3 Using the REST Controller with a RESTful API........................... 18 3.4 Using the XML-RPC Controller for XML-RPC requests...................... 21 4 Views 25 4.1 Templates................................................ 27 4.2 Passing Variables to Templates.................................... 27 4.3 Default Template Variables...................................... 28 4.4 Configuring Template Engines.................................... 29 4.5 Custom render() functions..................................... 30 4.6 Templating with Mako......................................... 31 5 Models 33 5.1 About the model............................................ 34 5.2 Model Basics.............................................. 35 5.3 Organizing............................................... 37 5.4 Creating a Model............................................ 37 5.5 Adding a Relation........................................... 38 5.6 Creating the Database......................................... 39 5.7 A brief guide to using model objects in the Controller....................... 39 5.8 Logging................................................. 44 i 5.9 About SQLAlchemy.......................................... 44 6 Advanced Models 47 6.1 Advanced SQLAlchemy........................................ 47 6.2 Non-SQLAlchemy libraries...................................... 51 6.3 Object Databases............................................ 51 6.4 Popular No-SQL Databases...................................... 52 7 Configuration 53 7.1 Runtime Configuration........................................ 53 7.2 Environment.............................................. 55 7.3 URL Configuration........................................... 55 7.4 Middleware............................................... 57 7.5 Application Setup........................................... 59 8 Logging 61 8.1 Logging messages........................................... 61 8.2 Basic Logging configuration..................................... 62 8.3 Filtering log messages......................................... 63 8.4 Advanced Configuration....................................... 63 8.5 Request logging with Paste’s TransLogger............................. 64 8.6 Logging to wsgi.errors......................................... 65 9 Helpers 69 9.1 Pagination................................................ 69 9.2 Secure Form Tag Helpers....................................... 74 10 Forms 75 10.1 The basics................................................ 75 10.2 Getting Started............................................. 75 10.3 Using the Helpers........................................... 76 10.4 File Uploads............................................... 77 10.5 Validating user input with FormEncode............................... 78 10.6 Other Form Tools............................................ 81 11 Internationalization and Localization 83 11.1 Introduction............................................... 83 11.2 Getting Started............................................. 84 11.3 Using Babel............................................... 85 11.4 Back To Work.............................................. 87 11.5 Testing the Application........................................ 87 11.6 Fallback Languages.......................................... 88 11.7 Translations Within Templates.................................... 89 11.8 Lazy Translations............................................ 90 11.9 Producing a Python Egg........................................ 91 11.10 Plural Forms.............................................. 91 11.11 Summary................................................ 92 11.12 Further Reading............................................ 92 11.13 babel.core – Babel core classes.................................. 92 11.14 babel.localedata — Babel locale data............................. 102 11.15 babel.dates – Babel date classes................................. 102 11.16 babel.numbers – Babel number classes.............................. 103 12 Sessions 107 12.1 Sessions................................................. 107 ii 12.2 The Session Object........................................... 107 12.3 Configuring the Session........................................ 108 12.4 Storing SQLAlchemy mapped objects in Beaker sessions..................... 109 12.5 Custom and caching middleware.................................. 109 12.6 Using Session in Internationalization................................. 109 12.7 Using Session in Secure Forms.................................... 110 12.8 Hacking the session for no cookies.................................. 110 12.9 Using middleware (Beaker) with a composite app......................... 110 13 Caching 113 13.1 Types of Caching............................................ 113 13.2 Namespaces and Keys......................................... 114 13.3 Configuring............................................... 114 13.4 Browser-Side.............................................. 115 13.5 Controller Actions........................................... 116 13.6 Templates................................................ 117 13.7 Arbitrary Functions.......................................... 117 13.8 Fragments................................................ 118 14 Unit and functional testing 119 14.1 Unit Testing with webtest ...................................... 119 14.2 Example: Testing a Controller.................................... 120 14.3 Testing Pylons Objects......................................... 121 14.4 Testing Your Own Objects....................................... 122 14.5 Unit Testing............................................... 123 14.6 Functional Testing........................................... 123 15 Errors, Troubleshooting, and Debugging 125 15.1 Error Middleware........................................... 125 15.2 Interactive Debugging......................................... 126 15.3 E-mailing Errors............................................ 128 15.4 Programmatically Handling Errors................................. 128 16 Upgrading 131 16.1 1.0 -> 1.0.1................................................ 131 16.2 0.9.7 -> 1.0................................................ 131 17 Packaging and Deployment Overview 135 17.1 Egg Files................................................. 135 17.2 Installing as a Non-root User..................................... 135 17.3 Understanding the Setup Process.................................. 136 17.4 Deploying the Application...................................... 138 17.5 Advanced Usage............................................ 138 18 Running Pylons Apps with Other Web Servers 139 18.1 Using Fast-CGI............................................. 139 18.2 Apache Configuration......................................... 140 18.3 PrefixMiddleware........................................... 140 18.4 Using Java Web Servers with Jython................................. 141 19 Documenting Your Application 143 19.1 Introduction............................................... 143 19.2 Tutorial................................................. 143 19.3 Learning ReStructuredText...................................... 144 19.4 Using Docstrings............................................ 144 iii 19.5 Using doctest.............................................. 145 19.6 Summary................................................ 145 20 Distributing Your Application 147 20.1 Running Your Application...................................... 148 21 Python 2.3 Installation Instructions 149 21.1 Advice of end of support for Python 2.3 .............................. 149 21.2 Preparation............................................... 149 21.3 System-wide Install.......................................... 149 22 Windows Notes 151 22.1 For Win2K or WinXP.......................................... 151 22.2 For Windows 95, 98 and ME..................................... 152 22.3 Finally.................................................. 152 23 Pylons on Jython 153 23.1 Installation............................................... 153 23.2 Deploying to Java Web servers.................................... 153 24 Security policy for bugs 155 24.1 Receiving Security Updates...................................... 155 24.2 Reporting Security Issues....................................... 155 24.3 Minimising Risk............................................ 156 25 WSGI support 157 25.1 Paste