Introduction

Please criticize me! This will be an ongoing thing, I will be coming back to posts and fixing things. I want to know what you think.

So after poking around in the reddit source code like a blind man for a while, I thought that the only way to motivate myself to understand it is to explain it to others, so here it goes.

I will try to explain things at a source code level. I will not be explaining how to deploy the server, or anything like that, there are already tutorials about that. Mainly, I'll be referencing the source tree and specific files a lot. I'll try to submit diagrams every now and then to illustrate certain points better.

Pylons

Reddit is a web-app. It uses a Python API called Pylons to deploy the webserver and handle all calls. Pylons basically does everything. When you submit a link, view comments, or just go to reddit.com, what happens is that the relevant information is sent to Pylons which then processes it according to the reddit API.

As eurleif once said about his popular Pylons based website, Pylons has very little documentation and tutorials available. So I'm going to break it down as simple as possible and then break it down some more.

Pylons facilitates using a MVC (Model-View-Controller) architecture to deploy a web application. This means that there are three components of the web-app and they work separate from one another. I'm not going to go into the particulars of MVC, you can google that yourself. I'm going to work with them in order of simplest to most complicated.

Controller

The controller is the portion of the code that facilitates calls from the client (you) and the server (reddit). For example, if I would go to "http://www.reddit.com/r/gaming?sort=new" the controller takes the "r/" portion of the URL and processes it and whatever follows it, doing whatever the code tells it to do. In this case, it strips out every part of the URL after '/r' and passes that on to the middleware, which we will discuss later.

In Pylons, this basically means that when a call is made, the code looks at a map of calls to controllers located at /config/routing.py and instantiates the appropriate controller class located in the files in /controllers and calls the mapped function. The function then returns a complete HTML page, which is sent to the client.

Pylons generally gets HTML parameters to the controller by having them passed as parameters to the controller function (or "action" in Pylons speak), the reddit code base instead makes use of decorators to set method parameters. HTML parameters are passed along using the @validate decorator that you see above the GET functions in the controller. This sets the names of the HTML parameters to the function parameters usually using several decorator functions such as "nop()" and "Validate()" which I haven't figured out yet.

For instance, if I want to search, the following is called, http://www.reddit.com/search?q=hello&count=50&after=t3_fcf41 (search for "hello", list 50 results, and list them after the result titled "t3_fcf41"). This tells Pylons to look at the routing map for something called search. Pylons finds the appropriate mapping:

 mc = map.connect
 mc('/reddits/search', controller='front', action='search_reddits')

and passes that along to the controller. Here, the controller being used is "front" and the function is "search_reddits". This tells Pylons to get the class "FrontController", instantiate a new object from it and call the function "GET_search_reddits". @validate then sets the parameters "query=q=hello", "count=50", "after=t3_fcf41", "reverse=", "num=". Several functions are then called to perform the search and render the page based on the search results. Pylons then takes the fully rendered page and sends it to the client. If you notice, several mappings have a colon before the name. This is a wildcard, which means that it is not mapped to a particular string and the controller can see that string and decide what to do with it. These are passed along to the controller as function parameters. For instance, a mapping that looks like this mc('/foo/:bar', controller='foo', action='baz') will call a function defined like so:

def GET_baz(self, bar):
      return dostuff

The parameter "bar" is mapped to the next thing in the URL after 'foo/'.

All in all pretty simple. To review: The mapping of calls is stored in 'config/routing.py' in the form of "call_name, controller, function". The call name is everything past "reddit.com" in the URL, the controller is a class with the name "FooController" where "foo" is the name of the controller in the map, and "function" is the aliased name of the method to call in the controller class that has the form of "GET_function(self, **params)" where params are a series of variables including the generic request variables and the GET and POST parameters. The page is then created and sent to the client.

Questions?

Part 2