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