Note: I am currently rewriting this introductory article as a new article called "Beginning Pylons". It is supposed to become a complete introduction with an example project showing most of the features and components used by Pylons. The current writing takes place in a Mercurial repository here:
http://workaround.org/cgi-bin/hg-beginning-pylons
Concepts of Pylons
Welcome to Pylons. You probably arrived here because you want to write a web-based application and are now looking for an easy way to do that. Perhaps you have even written CGI scripts or web applications in PHP.
Well, Pylons is a web framework which works a bit differently from what you may be used to. If you have used other frameworks such as Django, Turbogears or Ruby-on-Rails you will feel right at home though. This introduction aims to show you what Pylons offers and how developing with Pylons feels.
What is a framework?
As stated above Pylons is a web framework. Generally a framework is a collection of components (such as other programs, code libraries or even scripting languages) that work together to form a basis for your own application. When you develop a web application you often need some common tools:
- something that generates HTML
- something that reads arguments that are sent via HTTP
- something that communicates with your database
- something that contains your application logic
- something that deals with user accounts
- something that stores persistent data (like cookie-based sessions)
If you have already written an web application (even it was just a simple script that prints "Hello World") you will have written most of the above parts yourself. You probably just used print statements to create the HTML and did not care about complex templating systems. That works well in simple applications ... but programs tends to grow larger and, without a good concept, they become less maintainable. You may later have a dozen programs that output HTML pages that all look similar. Sure, you can move some common parts into a module that you use from all your programs. But basically you create solutions for typical tasks that almost every web applications have.
So some smart people invested their spare time to create components that fulfil these everyday tasks. For example there is a Python package called Myghty that deals with writing HTML - called a templating system. Using Myghty you create a file (the "template") that mainly contains your HTML page. But you can add Python statements right in that file where you need them and can access variables from other parts of your application. And since these templates can even use each other you can easily change the look of your web site by just changing a master template.
This is just one example of how such components can make your life as a programmer easier. There are a lot of ready-made components. And it is a good idea to use them instead of dealing with these boring everyday tasks. Now imagine you take a number of these useful components and get them to work together. A web framework like Pylons is exactly doing that.
What does MVC mean?
You may encounter the abbreviation MVC when you read about web frameworks. MVC is an acronym for model-view-controller and depicts a design pattern used in software engineering. The MVC approach splits your application into:
Models
They contain data that your application works with. Models do not contain any information about the meaning of this data. Often the model refers to database tables.
View
This is responsible for reading data from a model and displaying it to the user. (While models and controllers are called the same in Pylons you may notice that the equivalent part to a view in Pylons is basically the template.)
Controller
Here lies the logic of your application. The controller activates views to display data to the user or gets information from the user and stores it to the model(s).
You may wonder what is so special about that design pattern. You may have already written programs that communicate with your database, send HTML to the user and contain some kind of intelligence to steer everything. The idea of MVC though is that you can work on one part without breaking other parts.
(For a more complete explanation see http://en.wikipedia.org/wiki/Model_View_Controller)
Pylons' components
As Pylons consists of several parts it can be hard for the beginner to understand how those components work together. Let me show you around. It all begins with...
Paste
Paste is mainly a web server and a tool that helps you deploy our application to other computers. As you can see at http://pythonpaste.org/script/ your development.ini consists of two sections:
[server:main]
This section is meant for Paste itself. It tells Paste which IP address to bind its web server to and which TCP port to use. The use= line refers to the egg (an automated way to install Python packages) that contains Paste.
[app:main]
This section contains configuration lines for your own web application.
The Pylons documentation tells you that you start the web server with your application using paster serve --reload development.ini. Unless you specify any app-name as an option Paste will look for an application called main. That is how it finds [app:main]. After some internal Paste logic your config/middleware.py is loaded and its function make_app is called. You can even alter that function to add special functionality that you need.
You can find the exhaustive details in the Pylons Execution Analysis.
SQLAlchemy
Most web applications use a database as a persistent storage. You can save your customer information in there, articles for your web shop or whatever you can imagine. SQLAlchemy delivers two helpful features:
- an SQL toolkit
- an object relational mapper
The 'SQL toolkit' part is easy to explain: you define your database tables and don't need to write SQL statements any more. Regard SQLAlchemy as an abstraction layer. If you use that abstraction everywhere in your application you can even switch the database from MySQL to PostgreSQL and don't need to care about subtleties of the different database servers.
An even more interesting part is the object relational mapper that SQLAlchemy delivers. Imagine that you define your database table in Python syntax and create a Python class. Now you call a special mapper function that magically glues the class to the table. A simple example:
Customer.select_by(name='Kennedy')
This will query the database and get a database record from the table that represents your customers with the name 'Kennedy'. Isn't this more readable than writing SQL queries?
The complete documentation can be found at http://www.sqlalchemy.org/docs/
Myghty
This is the templating system. Instead of using print statements to print out HTML that is sent to the user's browser you use templates. A template file contains just HTML. And if you had a static page you would tell your program to
render_response('welcome.myt')
and Myghty will load the file templates/welcome.myt and display it to the user.
So far this is pretty boring. It gets interesting when you add Python code right into the templates. A simple example:
1
2
3
4
5
6
7
8
9
10
11 | <html>
<body>
<h1>Welcome</h1>
<p>Today we serve:</p>
<ul>
% for meal in ['calzone', 'porkpie', 'pizza']:
<li><% meal %></li>
%
</ul>
</body>
</html>
|
Templates offer some amazing features. You can use variables that you defined elsewhere in your application. You can include or inherit from other templates. See http://www.myghty.org/docs/ for more.
If you are used to PHP then this way to output HTML with programming logic inside will be familiar to you.
Routes
An interesting aspect of web frameworks is that you completely control what happens with the data the user sends you. This includes the URL itself. Routes lets you choose which action should happen for a particular kind of URL. Let's take the following URL as an example:
http://pylonshq.com/blog/2007/01
You can tell Routes that you want the BlogController to handle this request and pass on the '2007' as a year and the '01' as the month. In Routes syntax this looks like:
m.connect('blog/:year/:month', controller='blog')
The URL routing configuration is found in config/routing.py of your application.
Webhelpers
Even with the components described above you will still find yourself writing utility functions for everyday tasks. The Webhelpers is a package of such functions that you can use in Pylons applications. Some examples of what they do:
- handle AJAX elements gracefully
- format text and numbers
- create URLs, links, HTML form elements
- create RSS feeds
There is also a part of Webhelpers that contains functions ported from the Ruby on Rails framework. Webhelpers are not only helping you to save time on boring tasks but also control the script.aculo.us Javascript library that can be used for AJAX functionality and cool graphical effects to impress your coworkers. To get an idea on how that looks take a journey to http://wiki.script.aculo.us/scriptaculous/show/Demos
Are there other web frameworks?
Yes. Two other commonly cited frameworks are Django and Turbogears. There is no fair comparison because basically all three frameworks try to provide (dis)similar functionality. And different programmers may have different expectations. But let's try a comparison anyway.
Django
Django is oriented to programmers who deal mainly with content. The makers of Django are from the newspaper business. They say that they were often asked to implement certain features on their web site with tight deadlines. So they wrote their own framework. Django does not re-use many components. Even their way to access databases (the so called object-relational mapper) is home-made.
If you have similar requirements as Django's makers you will find that it is an excellent framework. But it is not meant to have its components replaced easily in case you don't like them. Their templating language is not very "pythonic" - it is a language of its own although an easy one. A nice feature is their admin frontend - it will create HTML forms for you to easily manage the data in your database. And it comes with a nifty way to map URLs to certain functions in your application based on regular expressions.
AJAX is basically possible with Django but not very comfortable. They have a web server built in but they suggest you run Django applications on an Apache with mod_python. One thing that can truly be said about Django: they have good marketing. 
Django is well documented, has a large community and there is even a book currently written. All in all Django is a "don't worry - be happy" framework that is tightly integrated and which will help you get things done quickly if you don't care too much which components it uses and don't expect all parts to look perfectly pythonic. It's a bit magical.
Turbogears
Turbogears makes use of existing components. Their web server runs on CherryPy, their HTML templates come from Kid, they access databases through SQLObject and even include a good way to write interactive AJAX applications through the use of a Javascript library called Mochikit that is tightly integrated.
They make it easier than Django to replace certain components in case you don't like them. For example you can throw away SQLObject and use SQLAlchemy instead; although many parts of Turbogears still lack full support for SQLAlchemy. Turbogears's URL mapping scheme is less explicit. You can't tell what is supposed to happen for certain URLs. Instead a program of the same name as the first part of the URL is called. So the URLs the user sees may appear less nifty.
A nicer feature is their set of web-based utilities. Among them is their WidgetBrowser to browse the library of supplied form elements - or Catwalk - a database administration frontend similar to that which Django provides. Turbogears is well documented and has a large community, too. All in all Turbogears has nifty features like its widget library or a good set of utility functions that make life easier.
Its documentation is somewhat incomplete and contains recipes and examples rather than a nice reference. A move to SQLAlchemy has been publicly announced but many features currently only work well with SQLObject. Turbogears may be a nice choice for programmers who are scared by the magic of Django and like it a bit more explicit.
Pylons
Pylons isn't exactly new but appears to have a smaller community than Django or Turbogears. That does not mean it's technically worse than other frameworks. It is unique in that it is more minimal and flexible than other frameworks. Basically you need to learn the basics of the components it uses. Next you need to understand how these components are controlled from within a Pylons application. So Pylons is the glue between the components with an additional powerful package called "Webhelpers" that aids in many areas from AJAX to RSS feed creation.
Pylons' flexibility means that you can exchange the components very easily. You don't like SQLAlchemy? Use SQLObjects. You read that Myghty is superseded by Mako? Use Mako. Pylons may not always hold your hand but it will try to make it easy to use different components than what Pylons uses by default. And you will likely be happy with what Pylons offers by default. The components are carefully chosen by looking at what other web frameworks do wrong.
The documentation for Pylons is still lacking and there is no "Pylons Handbook" yet. It seems like some fans of Pylons tried it because they generally liked the idea of web frameworks but were frustrated with Django or Turbogears. Some say that Pylons is the Ruby-on-Rails written in Python.
How is using a web framework different from CGI programming?
Many developers have programmed CGIs in a scripting language like Perl. Mostly because that is what web hosting services still offer. A CGI is a program that is launched by the web server when a user requests a certain URL in the browser. The CGI reads information it gets sent from the browser (and some environment variables that are set by the web server) and prints HTML that is shown in the browser. So you basically need a web server like Apache.
With a web framework like Pylons you do not use a seperate web server. Pylons includes a web server component called "Paste". This approach has several advantages:
- you can develop your application on your workstation easily because you do not need a complex set up with a third-party web server like Apache. Just fire up the web server process and try out your application. The server will even check if any of your program parts will change and reload the server automatically. - you control many aspects of the web server within your application (like returning HTTP error codes) which are otherwise done by the web server
- you can have flexible URL schemes. In CGIs the URLs always reflect the name of the CGI to be run. With Pylons you define what action is run when a certain URL pattern matches (e.g. /articles/2007/01)
- the web server keeps the whole application in memory which boosts the speed of your application. When using CGIs the web server will load and launch your script interpreter everytime the CGI is requested which creates some overhead on busy web sites.
What is the best way to start with Pylons?
Since Pylons is a collection of other components glued together it would not make much sense to write a Pylons handbook that just copied the existing documentation of these components. The documentation that comes with Pylons mostly covers pointers to the components and shows examples and tutorials of Pylons programs. So please don't be frustrated if you just get referred to another website.
It is not necessary that you know all the components by heart. But you need to understand their basics to use them properly in a Pylons application. In addition to the Getting Started introduction to Pylons and the QuickWiki tutorial that you can find at http://pylonshq.com/docs and which cover most of the basics it is recommended you read at least the quick introductions to Pylons components:
This should give you a basic understanding in the shortest possible time. Good luck with your first Pylons project.
Authors:
- Christoph Haas <email@christoph-haas.de>
- Graham Higgins
- Mike Orr
