Skip to main content

The Emerging GraphQL Python stack

GraphQL is an interesting technology originating at Facebook. It is a query language that lets you get JSON results from a server. It's not a database system but can work with any kind of backend structure. It tries to solve the same issues traditionally solved by HTTP "REST-ish" APIs.

Some problems with REST

When you do a REST-ish HTTP API, you expose information about the server on a bunch of URLs. These URLs each return some data, typically JSON. You can also update the server using HTTP methods, such as POST, PUT and DELETE. The client-side code needs to know what URLs exist on the system and construct URLs based on what it wants to know. If your REST-ish HTTP API is also a proper REST API (aka a hypermedia API), you make sure that all information can actually be accessed without constructing URLs but by following links (or doing search requests) instead -- this is more loosely coupled but also more difficult to implement.

But REST-ish HTTP APIs have some problems:


Imagine you have person resources and address resources. If you have a UI on the client that shows a person's address, you will have to access both resources on separate URLs. This can easily add up to a lot of requests from the client to the server. This not only causes network traffic but can also make it harder to program the client, especially if you can only do a new request based on information you got in another response.

You can reduce this problem by embedding information -- a person resource has address information directly embedded in it. But there's no standard way to control what gets embedded and this makes the next issue worse.

too much information
In a HTTP API, you want to send out as much information about a resource as possible, even if a particular UI doesn't need it. This means that there is more network traffic, and possibly more work done on the server to generate the data even though it's not needed.
too little information
There is typically rather little machine-readable metadata that describes what the information on the server really exists. Having such information can really help with tooling, and this in turn can help avoid bugs. There are emerging specifications that tackle this, but they're not commonly used.

REST will be here to stay for the foreseeable future. There is also nothing inherent in REST that stops you from solving this -- I wrote about this in a previous blog entry. But meanwhile GraphQL has already solved much of this stuff, so at the very least is interesting to explore.


GraphQL introduces a query language that lets the client express what it really wants from the server. A single request with this query goes to the server, and the server comes back with a complete structure with everything that's needed for a particular state of the UI. To get person information with its address information embedded, you can write something like:

  person(id: 101) {
    address {

You get back JSON like:

    "fullname": "Bob Lasereyes',
    "address: {
      "street": "Laserstreet",
      "number": "77",
      "postalCode": "XYZQ",
      "city": "Super City",
      "country": "Mutantia"

Check the GraphQL readme for much more.

This solves the issues with RESTish HTTP APIs:

less spamminess
To represent a single UI state you can typically get away with doing just a single request to the server specifying everything you need. The server then gives you a single response.
the right amount of information
You only get the information you ask for, nothing more, nothing less.
enough meta information
The server has a schema (which tools can introspect) that describes exactly what kind of data you can access.


If you use GraphQL with the React UI library there's another project from Facebook you can use with it: Relay. Relay lets you declare what data you want (using GraphQL), co-locate GraphQL snippets with the bits of UI that need it, so your UIs are more composable and can be rearranged more easily, and has a sophisticated system to help with mutations, so that you display the updated information in the UI as quickly as possible without re-fetching too much data.

It's cool, it's just new, I want to explore it to see whether it can tackle some of my use cases and make life easier for developers.

On the server side

So Relay and GraphQL are interesting and cool. So what do we need to start using it? To use React with Relay on the client side to build UIs, we need a Relay-compliant GraphQL server.

Facebook released a reference implementation of GraphQL, in JavaScript: graphql-js. It also released a library to help make a GraphQL server Relay compliant, again in JavaScript: graphql-relay-js. It also released a server that exposes GraphQL over HTTP, again in JavaScript: express-graphql.

That's all very cool if your server is in JavaScript. But what if your server is in Python? Luckily the Facebook people anticipated this and GraphQL is not bound to JavaScript. See the GraphQL draft specification and the GraphQL Relay specification.

The Python GraphQL stack

Last week I started exploring the state of the GraphQL stack in Python on the server. I was very pleased to find that it was in good shape already:

  • graphqllib: this is an implementation of GraphQL by Taeho Kim with contributions by an emerging open source community around it. Lots of contributions are by Jake Heinz, who was also very helpful in discussions on the Slack chat (#python at
  • graphql-relay-py: an implementation of graphql-relay-js for Python by Syrus Akbary, so we can make our GraphQL Relay server more compliant.

The piece that was missing was actually using this stack as a backend for a React + Relay frontend. Was it mature enough to do this? I figured I'd give it a try. So I set out to port the one missing piece to Python, the HTTP web server. So I took express-graphql and ported over its code and tests to Python + WSGI using WebOb. The result is wsgi_graphql, a WSGI component that offers the same HTTP API as express-graphql.

It was a fun little exercise. I found a few issues in graphqllib while doing so, and they're fixed already. I even found a minor bug in express-graphql while doing so, which is fixed as well.

So does it work? Can you use React and Relay on the frontend with Python on the backend? I created a demo project, relaypy, that experimentally pulls all these pieces together. It exposes a GraphQL server with a Relay-compliant schema. I hooked up some simple React + Relay code on the frontend. It worked! In addition, I threw in a cool introspection/query UI that was created for GraphQL called GraphiQL. This works too!

Should you be using this stuff in the real world? No, not yet. There are big warning letters on the graphqllib project that it's highly experimental. But while it's all very early days for these components, but the Python support has come very far in just a few short months -- GraphQL was only released as a public project in July, and Relay is even younger. I expect that in a short time this stuff will be ready for production and we'll have a capable GraphQL stack in Python that we can use with React and Relay.

Bonus: Graphene

Emerging just last week as well was graphene, which a very new library by Syrus Akbary to make implementing GraphQL servers more Pythonic. The API offered by graphqllib is rather low-level, which is nice as it's very flexible, but for many Python projects you'd like to use something more Pythonic. Graphene promises to be that API.

Thoughts about React Europe

Last week I visited the React Europe conference in Paris; it was the first such event in Europe and the second React conference in the world. Paris like much of the rest of western Europe during this early July was insanely hot. The airconditioning at the conference location had trouble keeping up, and bars and restaurants were more like saunas. Nonetheless, much was learned and much fun was had. I'm glad I went!

React, in case you're not aware, is a frontend JavaScript framework. There are a lot of those. I wrote one myself years ago (before it was cool; I'm a frontend framework hipster) called Obviel. React appeals to me because it's component driven and because it makes so many complexities go away with its approach to state.

Another reason I really like React is because its community is so creative. I missed being involved with such a creative community after my exit from Zope, which was due in large part as it had become less creative. A lot of the web is being rethought by the React community. Whether all of those ideas are good remains to be seen, but it's certainly exciting and good will come from it.

Here is a summary of my experiences at the conference, with some suggestions for the conference organizers sprinkled in. They did a great job, but this way I hope to help them make it even better.


When I heard there would be a hackathon the day before the conference, I immediately signed up. This would be a great way to meet other developers in the React community, work on some open source infrastructure software together, and learn from them. Then a few days before travel I learned there was a contest and prizes. Contest? Prizes? I was somewhat taken aback!

I come from the tradition of sprints in the Python world. Sprints in the Python community originated with the Zope project, and go back to 2001. Sprints can be 1-3 day affairs held either before or after a Python conference. The dedicated sprint is also not uncommon: interested developers gather together somewhere for a few days, sometimes quite a few days, to work on stuff together. This can be a small group of 4 people in someone's offices, or 10 people in a converted barn in the woods, or 30 people in a castle, or even more people in a hotel on a snowy alpine mountain in the winter. I've experienced all of that and more.

What do people do at such sprints? People hack on open source infrastructure together. Beginners are onboarded into projects by more experienced developers. New projects get started. People discuss new approaches. They get to know each other, and learn from each other. They party. Some sprints have more central coordination than others. A sprint is a great way to get to know other developers and do open source together in a room instead of over the internet.

I previously thought the word hackathon to be another word for sprint. But a contest makes people compete with each other, and a sprint is all about collaboration instead.

Luckily I chatted a bit online before the conference and quickly enough found another developer who wanted to work with me on open source stuff, turning it into a proper sprint after all. We put together this little library as a result. I also met Dan Abramov. I'll get back to him later.

When I arrived at the beautiful Mozilla offices in Paris where the sprint was held, it felt like a library -- everybody was quietly nestled behind their own laptop. I was afraid to speak, though characteristically that didn't last long. I may have made a comment that I thought hackathons aren't supposed to be ibraries. We got a bit more noise after that.

I thoroughly enjoyed this sprint (as that is what it became after all), and learned a lot. Meanwhile the hackathon went well too for the three Dutch friends I traveled with -- they won the contest!

React Europe organizers, I'd like to request a bit more room for sprint-like collaboration at the next conference. In open source we want to emphasize collaboration more than competition, don't we?


The quality of the talks of the conference was excellent; they got me thinking, which I enjoy. I'll discuss some of the trends and list a few talks that stood out to me personally; my selection has more to do with my personal interests than the quality of the talks I won't mention, though.

Inline styles and animations

Michael Chan gave a talk about Inline Styles. React is about encapsulating bits of UI into coherent components. But styling was originally left up to external CSS, apart from the components. It doesn't have to be. The React community has been exploring ways to put style information into components as well, in part replacing CSS altogether. This is definitely a rethinking of best practices that will cause some resistance, but definitely very interesting. I will have to explore some of the libraries for doing this that have emerged in the React community; perhaps they will fit my developer brain better than CSS has so far.

There were two talks about how you might define animations as well with React. I especially liked Cheng Lou's talk where he explored declarative ways to express animations. Who knows, maybe even unstylish programmers like myself will end up doing animation!

GraphQL and Relay

Lee Byron (creator of immutable-js) gave a talk about GraphQL. GraphQL is rethinking client/server communication originating at Facebook. Instead of leaving it up to the web server to determine the shape of the data the client code sees, GraphQL lets that be expressed by the client code. The idea is that the developer of the client UI code knows better that data they need than the server developer does (even if these are the same person). This has some performance benefits as well as it can be used to minimize network traffic. Most important to be me is that it promises a better way of client UI development: the data arrives in the shape the client developer needs already.

Lee announced the immediate release of a GraphQL introduction, GraphQL draft specification and a reference implementation in JavaScript, resolving a criticism I had in a previous blog post. I started reading the spec that night (I had missed out on the intro; it's a better place to start!).

Joseph Savona gave a talk about the Relay project, which is a way to integrate GraphQL with React. The idea is to specify what data a component needs not only on the client, but right next to the UI components that need it. Before the UI is rendered, the required data is composed into a larger GraphQL query and the data is retrieved. Relay aims to solve a lot of the hard parts of client/server communication in a central framework, making various complexities go away for UI developers. Joseph announced an open source release of Relay for around August. I'm looking forward to learn more about Relay then.

Dan Schafer and Nick Schrock gave a talk about what implementing a GraphQL server actually looks like. GraphQL is a query language, not a database system. It is designed to integrate with whatever backend services you already have, not replace them. This is good as it requires much less buy-in and you can evolve your systems towards GraphQL incrementally -- this was Facebook's own use case as well. To expose your service's data as GraphQL you need to give a server GraphQL framework a description of what your server data looks like and some code on how to obtain this data from the underlying services.

Both Dan and Nick spent the break after their talk answering a lot of questions by many interested developers, including myself. I spoke to Dan myself and I'm really grateful for all his informative answers.

The GraphQL and Relay developers at Facebook are explicitly hoping to build a real open source community around this technology, and they made a flying start this conference.


All this GraphQL and Relay stuff is exciting, but the way most people integrate React with backends at present is through variations on the Flux pattern. There were several talks that touched upon Flux during the conference. The talk that stood out was by Dan Abramov, who I mentioned earlier. This talk has already been released as an online video, and I recommend you watch it. In it Dan develops and debugs a client-side application live, and due to the ingenious architecture behind it, he can modify code and see the changes in the application's behavior immediately, without an explicit reload and without having to reenter data. It was really eye-opening.

What makes this style of development possible is a more purely functional approach towards the Flux pattern. Dan started the Redux framework, which focuses on making this kind of thing possible. Instead of definining methods that describe how to store data in some global store object, in Redux you define pure functions instead (reducers) that describe how to transform the store state into a new state.

Dan Abramov is interesting by himself. He has quickly made a big name for himself in the React community by working on all sorts of exciting new software and approaches, while being very approachable at the same time. He's doing open source right. He's also in his early 20s. I'm old enough to have run into very smart younger developers before, so his success is not too intimidating for me. I'll try to learn from what he does right and apply it in my own open source work.

The purely functional reducer pattern was all over the conference; I saw references to it in several other talks, especially Kevin Robinson's talk on simplifying the data layer, which explored the power of keeping a log of actions. It has its applications on both clients and servers.

The React web framework already set the tone: it makes some powerful functional programming techniques surrounding UI state management available in a JavaScript framework. The React community is now mining more functional programming techniques, making them accessible to JavaScript developers. It's interesting times.

Using React's component nature

There were several talks that touch on how you can use React's component nature. Ryan Florence gave an entertaining talk about you can incrementally rewrite an existing client-side application to use React components, step by step. Aria Buckles gave a talk on writing good reusable components with React; I recognized several mistakes I've made in my code and better ways to do it.

Finally in a topic close to my heart Evan Morikawa and Ben Gotow gave a talk about how to use React and Flux to turn applications into extensible platforms. Extensible platforms are all over software development. CMSes are a very common example in web development. One could even argue having an extensible core that supports multiple customers with customizations is the mystical quality that turns an application into "enterprise software".

DX: Developer Experience

The new abbreviation DX was used in a lot of talks. DX stands for "Developer Experience" in analogy with UX standing for "user experience".

I've always thought about this concept as usability for developers: a good library or framework offers a good user interface for developers who want to build stuff with it. A library or framework isn't there just to let developers get some done, but to let them get this stuff done well: smoothly, avoiding common mistakes, and not letting them down when they need to do something special.

I really appreciated the React community's emphasis on DX. Let's make the easy things easy, and the hard things possible, together.

Gender Diversity

This section is not intended as devastating criticism but as a suggestion. I'm not an expert on this topic at all, but I did want to make this observation.

I've attended a lot of Python conferences over the years. The gender balance at these conferences was in the early years much more like the React Europe conference: mostly men with a few women here and there. But in recent years there has been a big push in the Python community, especially in North America, to change the gender balance at these conferences and the community as a whole. With success: these days PyCons in North America attract over 30% women attendees. While EuroPython still has a way to go, last year I already noticed a definite trend towards more women speaking and attending. It was a change I appreciated.

Change like this doesn't happen by itself. React Europe made a good start by adopting a code of conduct. We can learn more about what other conference organizers do. Closer to the React community I've also appreciated the actions of the JSConf Europe organizers in this direction. Some simple ideas include to actively reach out to women to submit their talk and to reach out to user groups.

Of course, for all I know this was in fact done, in which case do please do keep it up! If not, that's my suggestion.


I really enjoyed this conference. There were a lot of interesting talks; too many to go into here. I met a lot of interesting people. Mining functional programming techniques to benefit mere mortal developers such as myself, and developer experience in general, are clearly major trends in the React community.

Now that I'm home I'm looking forward to exploring these ideas and technologies some more. Thank you organizers, speakers and fellow attendees! And then to think the conference will likely get even better next year! I hope I can make it again.

Build a better batching UI with Morepath and Jinja2


This post is the first in what I hope will be a series on neat things you can do with Morepath. Morepath is a Python web micro framework with some very interesting capabilities. What we'll look at today is what you can do with Morepath's link generation in a server-driven web application. While Morepath is an excellent fit to create REST APIs, it also works well server aplications. So let's look at how Morepath can help you to create a batching UI.

On the special occasion of this post we also released a new version of Morepath, Morepath 0.11.1!

A batching UI is a UI where you have a larger amount of data available than you want to show to the user at once. You instead partition the data in smaller batches, and you let the user navigate through these batches by clicking a previous and next link. If you have 56 items in total and the batch size is 10, you first see items 0-9. You can then click next to see items 10-19, then items 20-29, and so on until you see the last few items 50-55. Clicking previous will take you backwards again.

In this example, a URL to see a single batch looks like this:

To see items 20-29. You can also approach the application like this:

to start at the first batch.

I'm going to highlight the relevant parts of the application here. The complete example project can be found on Github. I have included instructions on how to install the app in the README.rst there.


First we need to define a few model classes to define the application. We are going to go for a fake database of fake persons that we want to batch through.

Here's the Person class:

class Person(object):
    def __init__(self, id, name, address, email): = id = name
        self.address = address = email

We use the neat fake-factory package to create some fake data for our fake database; the fake database is just a Python list:

fake = Faker()

def generate_random_person(id):
    return Person(id,, fake.address(),

def generate_random_persons(amount):
    return [generate_random_person(id) for id in range(amount)]

person_db = generate_random_persons(56)

So far nothing special. But next we create a special PersonCollection model that represents a batch of persons:

class PersonCollection(object):
    def __init__(self, persons, start):
        self.persons = persons
        if start < 0 or start >= len(persons):
            start = 0
        self.start = start

    def query(self):
        return self.persons[self.start:self.start + BATCH_SIZE]

    def previous(self):
        if self.start == 0:
            return None
        start = self.start - BATCH_SIZE
        if start < 0:
            start = 0
        return PersonCollection(self.persons, start)

    def next(self):
        start = self.start + BATCH_SIZE
        if start >= len(self.persons):
            return None
        return PersonCollection(self.persons, self.start + BATCH_SIZE)

To create an instance of PersonCollection you need two arguments: persons, which is going to be our person_db we created before, and start, which is the start index of the batch.

We define a query method that queries the persons we need from the larger batch, based on start and a global constant, BATCH_SIZE. Here we do this by simply taking a slice. In a real application you'd execute some kind of database query.

We also define previous and next methods. These give back the previous PersonCollection and next PersonCollection. They use the same persons database, but adjust the start of the batch. If there is no previous or next batch as we're at the beginning or the end, these methods return None.

There is nothing directly web related in this code, though of course PersonCollection is there to serve our web application in particular. But as you notice there is absolutely no interaction with request or any other parts of the Morepath API. This makes it easier to reason about this code: you can for instance write unit tests that just test the behavior of these instances without dealing with requests, HTML, etc.


Now we expose these models to the web. We tell Morepath what models are behind what URLs, and how to create URLs to models:

@App.path(model=PersonCollection, path='/')
def get_person_collection(start=0):
    return PersonCollection(person_db, start)

@App.path(model=Person, path='{id}',
          converters={'id': int})
def get_person(id):
        return person_db[id]
    except IndexError:
        return None

Let's look at this in more detail:

@App.path(model=PersonCollection, path='/')
def get_person_collection(start=0):
    return PersonCollection(person_db, start)

This is not a lot of code, but it actually tells Morepath a lot:

  • When you go to the root path / you get the instance returned by the get_person_collection function.
  • This URL takes a request parameter start, for instance ?start=10.
  • This request parameter is optional. If it's not given it defaults to 0.
  • Since the default is a Python int object, Morepath rejects any requests with request parameters that cannot be converted to an integer as a 400 Bad Request. So ?start=11 is legal, but ?start=foo is not.
  • When asked for the link to a PersonCollection instance in Python code, as we'll see soon, Morepath uses this information to reconstruct it.

Now let's look at get_person:

@App.path(model=Person, path='{id}',
          converters={'id': int})
def get_person(id):
        return person_db[id]
    except IndexError:
        return None

This uses a path with a parameter in it, id, which is passed to the get_person function. It explicitly sets the system to expect an int and reject anything else, but we could've used id=0 as a default parameter instead here too. Finally, get_person can return None if the id is not known in our Python list "database". Morepath automatically turns this into a 404 Not Found for you.

View & template for Person

While PersonCollection and Person instances now have a URL, we didn't tell Morepath yet what to do when someone goes there. So for now, these URLs will respond with a 404.

Let's fix this by defining some Morepath views. We'll do a simple view for Person first:

@App.html(model=Person, template='person.jinja2')
def person_default(self, request):
    return {
        'address': self.address,

We use the html decorator to indicate that this view delivers data of Content-Type text/html, and that it uses a person.jinja2 template to do so.

The person_default function itself gets a self and a request argument. The self argument is an instance of the model class indicated in the decorator, so a Person instance. The request argument is a WebOb request instance. We give the template the data returned in the dictionary.

The template person.jinja2 looks like this:

<!DOCTYPE html>
    <title>Morepath batching demo</title>
      Name: {{ name }}<br/>
      Address: {{ address }}<br/>
      Email: {{ email }}<br />

Here we use the Jinja2 template language to render the data to HTML. Morepath out of the box does not support Jinja2; it's template language agnostic. But in our example we use the Morepath extension more.jinja2 which integrates Jinja2. Chameleon support is also available in more.chameleon in case you prefer that.

View & template for PersonCollection

Here is the view that exposes PersonCollection:

@App.html(model=PersonCollection, template='person_collection.jinja2')
def person_collection_default(self, request):
    return {
        'persons': self.query(),

It gives the template the list of persons that is in the current PersonCollection instance so it can show them in a template as we'll see in a moment. It also creates two URLs: previous_link and next_link. These are links to the previous and next batch available, or None if no previous or next batch exists (this is the first or the last batch).

Let's look at the template:

<!DOCTYPE html>
   <title>Morepath batching demo</title>
      {% for person in persons %}
        <td><a href="{{ }}">{{ }}</a></td>
        <td>{{ }}</td>
        <td>{{ person.address }}</td>
      {% endfor %}
    {% if previous_link %}
    <a href="{{ previous_link }}">Previous</a>
    {% endif %}
    {% if next_link %}
    <a href="{{ next_link }}">Next</a>
    {% endif %}

A bit more is going on here. First it loops through the persons list to show all the persons in a batch in a HTML table. The name in the table is a link to the person instance; we use in the template to create this URL.

The template also shows a previous and next link, but only if they're not None, so when there is actually a previous or next batch available.

That's it

And that's it, besides a few details of application setup, which you can find in the complete example project on Github.

There's not much to this code, and that's how it should be. I invite you to compare this approach to a batching UI to what an implementation for another web framework looks like. Do you put the link generation code in the template itself? Or as ad hoc code inside the view functions? How clear and concise and testable is that code compared to what we just did here? Do you give back the right HTTP status codes when things go wrong? Consider also how easy it would be to expand the code to include searching in addition to batching.

Do you want to try out Morepath now? Read the very extensive documentation. I hope to hear from you!

GraphQL and REST


There is a new trend in open source that I'm not sure I like very much: big companies announce that they are going to open source something, but the release is nowhere in sight yet. Announcing something invites feedback, especially if it's announced as open source. When the software in question is available already as closed source for people to play with I don't really mind as feedback is possible, though it makes me wonder what the point is of holding back on a release.

It's a bit more difficult to give feedback on something when the thing announced is still heavily in development with no release in sight. How can one give feedback? But since you announced you'd open source it, I guess we should not be shy and give you feedback anyway.

Facebook has been doing this kind of announcement a lot recently: they announced React Native before they released it. They also announced Relay and GraphQL, but both have not yet been released. They've given us some information in a few talks and blog posts, and the rest is speculation. If you want to learn more about Relay and GraphQL I highly recommend you read these slides by Laney Kuenzel.

From the information we do have, Relay looks very interesting indeed. I think I'd like to have the option use Relay in the future. That means I need to implement GraphQL somehow, or at least something close enough to it, as it's the infrastructure that makes Relay possible.

React is a rethink of how to construct a client-side web application UI. React challenges MVC and bi-directional data binding. GraphQL is a rethink of the way client-side web applications talk to their backend. GraphQL challenges REST.


So what was REST again? Rich frontend applications these days typically talk to a HTTP backend. These backends follow some basic REST patterns: resources are on URLs and you can interact with them using HTTP verbs. Some resources represent single items:


If you issue a GET request to it you get its representation, typically in JSON. You can also issue a PUT request to it to overwrite its representation, and DELETE to delete it.

In a HTTP API we typically also have a way to access collections:


You can issue GET to this too, possibly with some HTTP query parameters to do a filter, to get a representation of the users known to the application. You can also issue POST to this to add a new user.

Real proper REST APIs, also known as Hypermedia APIs, go beyond this: they have hyperlinks between resources. I wrote a web framework named Morepath which aims to make it easier to create complex hypermedia APIs, so you can say I'm pretty heavily invested in REST.

Challenging REST

GraphQL challenges REST. The core idea is that the code that best knows what data is needed for a UI is not on the server but on the client. The UI component knows best what data it wants.

REST delivers all the data a UI might need about a resource and it's up to the client to go look for the bits it actually wants to show. If that data is not in a resource it already has, the client needs to go off to the server and request some more data from another URL. With GraphQL the UI gets exactly the data it needs instead, in a shape handy for the UI.

As we can see here, a GraphQL query looks like this:

   user(id: 400) {
     profilePicture(size: 50)  {

You get back this:

  "user" : {
    "id": 4000,
    "name": "Some name",
    "isViewerFriend": true,
    "profilePicture": {
      "uri": "",
      "width": 50,
      "height": 50

This says you want an object of type user with id 4000. You are interested in its id, name and isViewerFriend fields.

You also want another object it is connected to: the profilePicture. You want the uri, width and height fields of this. While there is no public GraphQL specification out there yet, I think that size: 50 means to restrict the subquery for a profile picture to only those of size 50. I'm not sure what happens if no profilePicture of this size is available, though.

To talk to the backend, there is only a single HTTP end-point that receives all these queries, or alternatively you use a non-HTTP mechanism like web sockets. Very unRESTful indeed!

REST and shaping data

Since I'm invested in REST, I've been wondering about whether we can bring some of these ideas to REST APIs. Perhaps we can even map GraphQL to a REST API in a reasonably efficient way. But even if we don't implement all of GraphQL, we might gain enough to make our REST APIs more useful to front-end developers.

As an exercise, let's try to express the query above as a REST query for a hypothetical REST API. First we take this bit:

user(id: 4000) {

We can express this using a path:


The client could construct this path by using a URI template (/users/{id}) provided by the server, or by following a link provided by the server, or by doing the least RESTful thing of them all: hardcode the URL construction in client code.

How do we express with HTTP what fields a user wants? REST of course does have a mechanism that can be used to shape data: HTTP query parameters. So this bit:


could become these query parameters:


And the query would then look like this:


That is pretty straightforward. It needs server buy-in, but it wouldn't be very difficult to implement in the basic case. The sub-query is more tricky. We need to think of some way to represent it in query parameters. We could do something like this (multi-line for clarity):


The whole query now looks like this:


The result of this query would look the same as in the GraphQL example. It's important to notice that this REST API is not fully normalized -- the profilePicure data is not behind a separate URL that the client then needs to go to. Instead, the object is embedded in the result for the sake of convenience and performance.

I'd be tempted to make the server send back some JSON-LD to help here: each object (the user object and the profileData subobject) can have an @id for its canonical URL and a @type as a type designator. A client-side cache could exploit this @id information to store information about the objects it already knows about. Client-side code could also use this information to deal with normalized APIs transparently: it can automatically fetch the sub-object for you if it's not embedded, at the cost of performance.

Does this REST API have the same features as the GraphQL example? I have no idea. It probably depends especially on how queries of related objects work. GraphQL does supply caching benefits, which you wouldn't have without more work. On the other hand you might be able to exploit HTTP-level caching mechanisms with this REST-based approach. Then again, this has more HTTP overhead, which GraphQL can avoid.

Let's briefly get back to the idea to automatically map GraphQL to a REST API. What is needed is a way to look up a URI template for a GraphQL type. So, for the user type we could connect it to a URI template /users/{id}. The server could supply this map of GraphQL type to URI template to the server, so the server can make the translation of the GraphQL to the REST API.

Further speculation

What about queries for multiple objects? We could use some kind of collection URL with a filter:


It is normal in REST to shape collection data this way already, after all. Unfortunately I have no clear idea what a query for a collection of objects looks like in GraphQL.

I've only vaguely started thinking about mutations. If you can access the objects's URL in a standard way such as with an @id field, you can then get a handle on the object and send it POST, PUT and DELETE requests.


All this is wild speculation, as we don't really know enough about GraphQL yet to fully understand its capabilities. It's quite possible that I'm throwing away some important property of GraphQL away by mapping it to a REST API. Scalability, for instance. Then again, usually my scalability use cases aren't the same as Facebook's, so I might not care as long as I get Relay's benefits to client-side code development.

It's also possible that it's actually easier to implement a single GraphQL-based endpoint than to write or adapt a REST API to support these patterns. Who knows.

Another question I don't have the answer to is what properties a system should have to make Relay work at all. Does it need to be exactly GraphQL, or would a subset of its features work? Which properties of GraphQL are essential?

Thank you, GraphQL and Relay people, for challenging the status quo! Though it makes me slightly uncomfortable, I greatly appreciate it. Hopefully my feedback wasn't too dumb; luckily you can't blame me too much for that as I can legitimately claim ignorance! I'm looking forward to learning more.

Server Templating in Morepath 0.10


I just released Morepath 0.10 (CHANGES)! Morepath is a modern Python web framework that combines power with simplicity of use. Morepath 0.10's biggest new feature is server-side templating support.

Most Python web frameworks were born at a time when server-side templating was the only way to get HTML content into a web browser. Templates in the browser did not yet exist. Server templating was a necessity for a server web framework, built-in from day 1.

The web has changed and much more can be done in the browser now: if you want a web page, you can accomplish it with client-side JavaScript code, helped by templates, or embedded HTML-like snippets in JavaScript, like what the React framework does. Morepath is a web framework that was born in this new era.

Morepath could take a more leisurely approach to server templating. We recommend that users rely on client-side technology to construct a UI -- something that Morepath is very good at supporting. For many web applications, this approach is fine and leads to more responsive user interfaces. It also has the benefit that it supports a strong separation between user interface and underlying data. And you could still use server template engines with Morepath, but with no help from the framework.

But there is still room for server templates. Server-generated HTML has its advantages. It's the easiest way to create a bookmarkable traditional web site -- no client-side routing needed. For more dynamic web applications it can also sometimes make sense to send a server-rendered HTML page to the client as a starting point, and only switch to a client-side dynamic code later. This is useful in those cases where you want the end-user to see a web page as quickly as possible: in that case sending HTML directly from the server can still be faster, as there is no need for the browser to load and process JavaScript in order to display some content.

So now Morepath has now, at last, gained server template support, in version 0.10. We took our time. We prototyped a bit first. We worked out the details of the rest of the framework. As we will see, it's nice we had the chance to spend time on other aspects of Morepath first, as that infrastructure now also makes template language integration very clean.

The basics

Say you want to use Jinja2, the template language used by Flask, in Morepath. Morepath does not ship with Jinja2 or any other template language by default. Instead you can install it as a plugin in your own project. The first thing you do is modify your project's and add more.jinja2 to install_requires:


Now when you install your project's dependencies, it pulls in more.jinja2, which also pulls in the Jinja2 template engine itself.

Morepath's extension system works through subclassing. If you want Jinja2 support in your Morepath application, you need to subclass your Morepath app from the Jinja2App:

from more.jinja2 import Jinja2App

class App(Jinja2App):

The App class is now aware of Jinja2 templates.

Next you need to tell your app what directory to look in for templates:

def get_template_directory():
    return 'templates'

This tells your app to look in the templates directory next to the Python module you wrote this code in, so the templates subdirectory of the Python package that contains your code.

Now you can use templates in your code. Here's a HTML view with a template:

@App.html(model=Customer, template='customer.jinja2')
def customer_default(self, request):
    return {
      'street': self.street,
      'zip': self.zip_code

The view returns a dictionary. This dictionary contains the variables that should go into the customer.jinja2 template, which should be in the templates directory. Note that you have to use the jinja2 extension, as Morepath recognizes how to interpret a template by its extension.

You can now write the customer.jinja2 template that uses this information:

  <p>Customer {{name}} lives on {{street}} in {{city}}.</p>
  <p>The zip code is {{zip}}.</p>

You can use the usual Jinja2 constructs here.

When you access the view above, the template gets rendered.


What if you want to use Chameleon (ZPT) templates instead of Jinja2 templates? We've provided more.chameleon that has this integration. Include it in install_requires in, and then do this to integrate it into your app:

from more.chameleon import ChameleonApp

class App(ChameleonApp):

You can now set up a template directory and put in .pt files, which you can then refer to from the template argument to views.

You could even subclass both ChameleonApp and Jinja2App apps and have an application that uses both Chameleon and Jinja2 templates. While that doesn't seem like a great idea, Morepath does allow multiple applications to be composed into a larger application, so it is nice that it is possible to combine an application that uses Jinja2 with another one that uses Chameleon.


Imagine there is an application developed by a third party that has a whole bunch of templates in them. Now without changing that application directory you want to override a template in it. Perhaps you want to override a master template that sets up a common look and feel, for instance.

In Morepath, template overrides can be done by subclassing the application (just like you can override anything else):

class SubApp(App):

def get_template_directory_override():
    return 'override_templates'

That template_directory directive tells SubApp to look for templates in override_templates first before it checks the templates directory that was set up by App.

If we want to override master.jinja2, all we have to do is copy it from templates into override_templates and change it to suit our purposes. Since a template with that name is found in override_templates first, it is found instead of the one in templates. The original App remains unaffected.


In the introduction we mentioned that the template language integration code into Morepath is clean. You should be able to integrate other template engines easily too. Here is the code that integrates Jinja2 into Morepath:

import os
import morepath
import jinja2

class Jinja2App(morepath.App):

def get_setting_section():
    return {
        'auto_reload': False,

def get_jinja2_loader(template_directories, settings):
    config = settings.jinja2.__dict__.copy()

    # we always want to use autoescape as this is about
    # HTML templating
        'autoescape': True,
        'extensions': ['jinja2.ext.autoescape']

    return jinja2.Environment(

def get_jinja2_render(loader, name, original_render):
    template = loader.get_template(name)

    def render(content, request):
        variables = {'request': request}
        return original_render(template.render(**variables), request)
    return render

The template_loader directive sets up an object that knows how to load templates from a given list of template directories. In the case of Jinja2 that is the Jinja2 environment object.

The template_render directive then tells Morepath how to render individual templates: get them from the loader first, and then construct a function that given content returned by the view function and request, uses the template to render it.


For more documentation, see the Morepath documentation on templates.

Let us know what you think!

10 reasons to check out the Morepath web framework in 2015

Happy new year everybody! Last year we've made a lot of progress on the Morepath web framework for Python. It will go quite a lot further in 2015 as well. Here are 10 reasons why you should check out Morepath this year:

  1. Knows about HTTP status codes. When you write a "Hello World" application it does not matter that there are other status codes besides 200 OK, but in real world applications you want your application to know about 404 Not Found, and 405 Method Not Allowed, and so on.

    Morepath does not make you write write verbose and failure-prone special cased code to handle status codes. Instead, Morepath does HTTP status codes correctly right away.

  2. Morepath makes hyperlinks to objects. In a typical routing web framework, to make a URL, you need to remember the name of a route, the parameters that go into the route, and how to get that information from the object to which you are making the route. This leads to duplicated code and hardcodes route names everywhere. Since it does so little, it encourages you to skip it entirely and write even more hardcoded URL generation code everywhere.

    Morepath makes it easier to do the right thing. Morepath lets you link to Python objects. Morepath also understands URL parameters can be part of URLs too, and can create a link with them in there for you too.

  3. Built-in permission system. Morepath does not leave something as important as security entirely up to extensions. The core framework knows that views can be guarded with permissions. Who has what permission for what object is then up to you, and Morepath lets you define permissions powerfully and succinctly.

  4. Compose applications. If you have a project application and a wiki application, you can mount the wiki application into the project applications. You can develop and test applications independently, and then combine them later. These are true coarse-grained components. This way, Morepath lets build large applications out of smaller ones.

  5. All views are reusable. Morepath does not have a separate sub-framework to let you write more reusable and generic views than the normal ones. Instead any view you create in Morepath is already reusable. And remember - you don't have to hardcode route names, which makes views more generic by default.

    Views in Morepath are true fine-grained reusable components, without extra work. Morepath gives you the tools to build a generic UI. You can reuse views with ease with Morepath.

  6. Subclass applications. Morepath does not have a separate sub-framework to let you write reusable blueprints for applications. Instead, any application you create in Morepath is already reusable in that way. In the real world, applications evolve into frameworks all the time, and Morepath does not stand in your way with special cases.

    You can subclass any Morepath app to add new routes and views, or override existing ones.

  7. Made for the modern web. Many modern web applications feature a REST backend with a rich, client-side frontend written in JavaScript. Morepath is written to support REST from the ground up - it's not a layer over something else, but it's not a constraining HTTP API generation tool either.

  8. Extensible framework. Morepath lets you extend the web framework in the same way it lets you extend applications written in it. You can write new Morepath directives and framework applications. As examples, more.static adds advanced browser static resource handling to Morepath, more.transaction integrates Morepath with transaction based databases such as SQLAlchemy and the ZODB, and more.forwarded adds HTTP Forwarded header support.

  9. Micro framework with macro ambitions. Morepath is a micro framework; it's not a lot of code. It's easy to get an overview of what's going on, and it's easy to embed in a larger application. Morepath packs a lot more punch in a small amount of code than your typical Python micro web framework.

    All this does not come at the cost of performance. When the primary selling point of a Python web framework seems to be performance, perhaps it's not doing enough for you. But Morepath has more than adequate performance - on "Hello world" at least Morepath outpaces some very popular web Python frameworks comfortably.

  10. Documentation. Some Python micro frameworks also have micro documentation. Instead, Morepath has lots of docs.

Enjoy 2015!

A Review of the Web and how Morepath fits in

I've spent a bit of time writing the somewhat grandiosely titled A Review of the Web, and I think it's a neat addition to the documentation of the Morepath web framework.

It attempts to do two things:

  • Help those developers who aren't as familiar yet with the details of web technology to get a handle on various concepts surrounding web frameworks and web services.
  • Show to developers who are more familiar with these concepts how Morepath fits in as a web framework.

Does this document fulfill either purpose? Let me know!

Morepath 0.9 released!

Yesterday I released Morepath 0.9 (CHANGES)!

What is Morepath? Morepath is a Python web framework. It tries to be especially good at implementing modern, RESTful backends. It is very good at creating hyperlinks. It is easy to use, but still lets you write flexible, maintainable and reusable code. Morepath is very extensively documented.

This release doesn't involve earth-shaking changes like the 0.7 and 0.8 releases did, but it still has an interesting change I'd like to discuss.

Proxy support

Morepath by default doesn't obey the HTTP Forwarded header in link generation, which is a good thing, as it would allow various link hijacking attacks if it did. But if you're behind a trusted proxy that generates the Forwarded header you do want Morepath to take it into account. To do so, you install the more.forwarded extension and subclass your (root) application from it:

from more.forwarded import ForwardedApp

class MyApp(ForwardedApp):

We don't have support yet for the old-style X_FORWARDED_HOST and X_FORWARDED_PROTO that the Forwarded header replaces; we're open to contributions to more.forwarded!

Linking to external applications

Now we come to a very interesting capability of Morepath: the ability to model and link to external applications.

Let's consider a hypothetical external application. It's hosted on the ubiquitous It has documents listed on URLs like this:

We could of course simply create links to it by concatenating and the document id, foo. For such a simple external application that is probably the best way to go. So what I'm going to describe next is total overkill for such a simple example, but I have to use a simple example to make it comprehensible at all.

Here's how we'd go about modeling the external site:

class ExternalDocumentApp(morepath.App):

class ExternalDocument(object):
    def _init__(self, id): = id

@ExternalDocumentApp.path(model=ExternalDocument, path='/documents/{id}')
def get_external_document(id):
    return ExternalDocument(id)

We don't declare any views for ExternalDocument as our code is not going to create representations for the external document, just create links to it. We need to mount it into our actual applicatino code so that we can use it:

@App.mount(path='external_documents', app=ExternalDocumentApp)
def mount_external_document_app():
    return ExternalDocumentApp()

Now we set up the link_prefix for ExternalDocumentApp to point to

def external_link_prefix(request):
    return ''

As you can see, we've hardcoded in it. Now if you're in some view code for your App, you can create a link to an ExternalDocument like this:

def some_model_default(self, request):
   return {

This will generate the correct link to the external document foo:


You can make this simpler by using a defer_links directive for your App (introduced in Morepath 0.7):

def defer_document(app, obj):
    return app.child('external_documents')

We've now told Morepath that any ExternalDocument objects need to have their link generated by the mounted external_documents app. This allows you to write link generation code that's a lot simpler:

def some_model_default(self, request):
   return {

In review

As I said previously, this is total overkill for an external application as simple as the hypothetical one I described. But this technique of modeling an external application can be very useful in specific circumstances:

  • This is declarative code. If you are dealing with a lot of different kind of links to an external application, it can be worthwhile to properly model it in your application, instead of spreading more failure-prone link construction code all over the place.

  • If you have to deal with an external application that for some reason is expected to change its structure (or hostname) in the future. By explicitly modeling what you link to, you can easily adjust all the outgoing links in your application when that change happens.

  • Consider a Morepath application that has a sub-application, mounted into it in the same process. You now decide to run this sub-application in a separate process, with a separate hostname. To do this you break out the code out into its own project so you can run it separately.

    In this case you already have declarative link generation to it. In the original project, you create a hollowed-out version of the sub-application that just has the path directives that describe the link structure. You then hardcode the new hostname using link_prefix.

    The code that links to it in the original application will now automatically update to point to the sub-application on the new host.

    This way you can break a larger application into multiple separate pieces pretty easily!


If you've read all the way to the end, I hope you've enjoyed that and aren't completely overwhelmed by these options! Just remember: these are advanced use cases. Morepath grows with your application. It is simple for simple things, but is there for you when you do have more complex requirements.

Better REST with Morepath 0.8

Today I released Morepath 0.8 (CHANGES). In this release Morepath has become faster, simpler and more powerful at the same time. I like it when I can do all three in a release!

I'll get faster and simpler out of the way fast, so I can go into the "more powerful", which is what Morepath is all about.


I run this simple benchmark once every while to make sure Morepath's performance is going in the right direction. The benchmark does almost nothing: it just sends the text "Hello world" back to the browser from a view on a path.

It's still useful to try such a small benchmark, as it can help show how much your web framework is doing to send something that basic back to the browser. In July when I presented Morepath at EuroPython, I measured it. I was about as fast as Django then at this task, and was already significantly faster than Flask.

I'm pleased to report that Morepath 0.8 is 50% faster than in July. At raw performance on this benchmark, we have now comfortably surpassed Django and are leaving Flask somewhere in the distance.

Morepath is not about performance -- it's fast enough anyway, other work will dominate in most real-world applications, but it's nice to know.

Performance is relative of course: Pyramid for instance is still racing far ahead on this benchmark, and so is wheezy.web, the web framework from which I took this benchmark and hacked up.


Morepath 0.8 is running on a new engine: a completely refactored Reg library. Reg was originally inspired by zope.interface (which Pyramid uses), but it has since evolved almost beyond recognition into a powerful generic dispatch system.

In Reg 0.9, the dispatch system has been simplified and generalized to also let you dispatch on the value of arguments as well as their classes. Reg 0.9 also lifts the restriction that you have to dispatch on all non-key keyword arguments. Reg could also cache lookups to make things go faster, but this now also works for the new non-class-based dispatch.

Much of Morepath's flexibility and power is due to Reg. Morepath 0.9's view lookup system has been rewritten to make use of the new powers of Reg, making it both faster and more powerful.

Enough abstract talk: let's look at what implementing a REST web service looks like in Morepath 0.8.

The Power of Morepath: REST in Morepath


Here's the scenario we are going to implement.

Say you're implementing a REST API (also known as a hypermedia API).

You want to support the URL (hostname info omitted):


When you access it with a GET request, you get JSON describing the customer with the given id, or if it doesn't exist, 404 Not Found.

There's also the URL:


This represents a collection of customers. You want to be able to GET it and get some JSON information about the customers back.

Moreover, you want to POST JSON to it that represents a new customer, to add it a customer to the collection.

The customer JSON at /customers/{id} looks like this:

  "@id": "/customers/0",
  "@type": "Customer",
  "name": "Joe Shopper"

What's this @id and @type business? They're just conventions (though I took them took from the JSON-LD standard). @id is a link to the customer itself, which also uniquely identifies this customer. @type describes the type of this object.

The customer collection JSON at /customers looks like this:

  "@id": "/customers",
  "@type": "CustomerCollection"
  "customers": ['/customers/0', '/customers/1'],
  "add": "/customers",

When you POST a new customer @id is not needed, but it gets added after POST. The response to a POST should be JSON representing the new customer we just POSTed, but now with the @id added.

Implementing this scenario with Morepath

First we define a class Customer that defines the customer. In a real-world application this is backed by some database, perhaps using an ORM like SQLAlchemy, but we'll keep it simple here:

class Customer(object):
    def __init__(self, name): = None  # we will set it after creation = name

Customer doesn't know anything about the web at all; it shouldn't have to.

Then there's a CustomerCollection that represents a collection of Customer objects. Again in the real world it would be backed by some database, and implemented in terms of database operations to query and add customers, but here we show a simple in-memory implementation:

class CustomerCollection(object):
     def __init__(self):
         self.customers = {}
         self.id_counter = 0

     def get(self, id):
         return self.customers.get(id)

     def add(self, customer):
         self.customers[self.id_counter] = customer
         # here we set the id = self.id_counter
         self.id_counter += 1
         return customer

customer_collection = CustomerCollection()

We register this collection at the path /customers:

@App.path(model=CustomerCollection, path='/customers')
def get_customer_collection():
    return customer_collection

We register Customer at the path /customers/{id}:

@App.path(model=Customer, path='/customers/{id}'
          converters={'id': int})
def get_customer(id):
    return customer_collection.get(id)

See the converters bit we did there? This makes sure that the {id} variable is converted from a string into an integer for you automatically, as internally we use integer ids.

We now register a dump_json that can transform the Customer object into JSON:

def dump(self, request):
   return {
      '@type': 'Customer',

Now we are ready to implement a GET (the default) view for Customer, so that /customer/{id} works:

def customer_default(self, request):
    return self

That's easy! It can just return self and let dump_json take care of making it be JSON.

Now let's work on the POST of new customers on /customers.

We register a load_json directive that can transform JSON into a Customer instance:

def load(json, request):
    if json['@type'] == 'Customer':
        return Customer(name=json['name'])
    return json

We now can register a view that handles the POST of a new Customer to the CustomerCollection:

def customer_collection_post(self, request):
    return self.add(request.body_obj)

This calls the add method we defined on CustomerCollection before. body_obj is a Customer instance, converted from the incoming JSON. It returns the resulting Customer instance which is automatically transformed to JSON.

For good measure let's also define a way to transform the CustomerCollection into JSON:

def dump_customer_collection(self, request):
    return {
        '@type': 'CustomerCollection',
        'customers': [
   for customer in self.customers.values()
    } automatically creates the correct links to Customer instances and the CustomerCollection itself.

We now need to add a GET view for CustomerCollection:

def customer_collection_default(self, request):
    return self

We done with our implementation. Check out a working example on Github. To try it out you could use a commandline tool like wget or curl, or Chrome's Postman extension, for instance.

What about HTTP status codes?

A good REST API sends back the correct HTTP status codes when something goes wrong. There's more to HTTP status codes than just 200 OK and 404 Not Found.

Now with a normal Python web framework, you'd have to go through your implementation and add checks for various error conditions, and then return or raise HTTP errors in lots of places.

Morepath is not a normal Python web framework.

Morepath does the following:

/customers and /customers/1

200 Ok (if customer 1 exists)

Well, of course!


404 Not Found

Yeah, but other web frameworks do this too.


404 Not Found (if customer 1000 doesn't exist)

Morepath automates this for you if you return None from the ``@App.path`` directive.


400 Bad Request

Oh, okay. That's nice!

PUT on /customers/1

405 Method Not Allowed

You know about this status code, but does your web framework?

POST on /customers of JSON that does not have @type Customer
422 Unprocessable Entity

Yes, 422 Unprocessable Entity is a real HTTP status code, and it's used in REST APIs -- the Github API uses it for instance. Other REST API use 400 Bad Request for this case. You can make Morepath do this as well.

Under the hood

Here's the part of the Morepath codebase that implements much of this behavior:

@App.predicate(generic.view, name='model', default=None, index=ClassIndex)
def model_predicate(obj):
    return obj.__class__

@App.predicate_fallback(generic.view, model_predicate)
def model_not_found(self, request):
    raise HTTPNotFound()

@App.predicate(generic.view, name='name', default='', index=KeyIndex,
def name_predicate(request):
    return request.view_name

@App.predicate_fallback(generic.view, name_predicate)
def name_not_found(self, request):
    raise HTTPNotFound()

@App.predicate(generic.view, name='request_method', default='GET',
               index=KeyIndex, after=name_predicate)
def request_method_predicate(request):
    return request.method

@App.predicate_fallback(generic.view, request_method_predicate)
def method_not_allowed(self, request):
    raise HTTPMethodNotAllowed()

@App.predicate(generic.view, name='body_model', default=object,
               index=ClassIndex, after=request_method_predicate)
def body_model_predicate(request):
    return request.body_obj.__class__

@App.predicate_fallback(generic.view, body_model_predicate)
def body_model_unprocessable(self, request):
    raise HTTPUnprocessableEntity()

Don't like 422 Unprocessable Entity when body_model doesn't match? Want 400 Bad Request instead? Just override the predicate_fallback for this in your own application:

class MyApp(morepath.App):

@MyApp.predicate_fallback(generic.view, body_model_predicate)
def body_model_unprocessable_overridden(self, request):
    raise HTTPBadRequest()

Want to have views respond to the HTTP Accept header? Add a new predicate that handles this to your app.

Now what are you waiting for? Try out Morepath!

Morepath 0.7: new inter-app linking

I've just released Morepath 0.7!

What is Morepath? Morepath is a Python web framework. It tries to be especially good at implementing modern, RESTful backends. It is very good at creating hyperlinks. It is easy to use, but still lets you write flexible, maintainable and reusable code. Morepath is very extensively documented.

So what's new in Morepath 0.7? The CHANGES doc as usual has the details, but I'll give an overview here.

New features for JSON handling

Morepath 0.7 introduces new ways to deal with JSON. There are two new directives, dump_json and load_json. By using these you can teach Morepath how to automatically convert incoming JSON to a Python object, and outgoing Python objects to JSON. See the JSON and objects documentation for more.

Mounting and linking

The big change in Morepath 0.7 however involves the way mounting works, and how you can link between applications. This introduces a few breaking changes if you were using these features before. The CHANGES document provides documentation that will tell you how to adjust your code.

I'm very happy with the new change. It cleans up several APIs. I believe this makes them both easier to understand while at the same time significantly cleaning up the implementation. It also introduces a powerful new feature for inter-app linking: deferred links.

In brief, Morepath lets you mount one application into another:

import morepath

class RootApp(morepath.App)

class SubApp(morepath.App):

@RootApp.mount(path='sub', app=SubApp)
def mount_subapp():
    return SubApp()

Now the SubApp application, which can be its own whole different thing (its instance is a WSGI application), is mounted under the RootApp application. When you go to /sub, SubApp takes over.

This doesn't work just for simple sub-paths like sub, but also for parameterized paths. Consider this:

class WikiApp(morepath.App):
    def __init__(self, wiki_id):
        self.wiki_id = wiki_id

@UserApp.mount(path='/users/{username}/wiki', app=WikiApp)
def mount_wiki(username):
    return WikiApp(wiki_id=wiki_id_for_username(username)

Here's we've mounted a wiki app into a user app. When you go to /users/foo/wiki, the wiki app for user foo takes over, with its own routes, views, and the like. The wiki app doesn't need to know about the user app, and the user app just needs to know how to mount the wiki app.

Morepath is very good at linking: it knows how to construct a link to an object instance. So, if you want to link to a particular WikiPage instance from within the wiki app, you'd simply write this:

What if you wanted to create a link to a wiki page from the user app? Just linking to the wiki page will fail, as the user app doesn't know how to create links to wiki pages. But you can tell it to create a link to an object in the wiki app explicitly:

wiki_app =, username='foo'), app=wiki_app)

If you are going to write a lot of such links, this can get boring. Morepath introduces a new defer_links directive to help automate this:

def defer_links_wiki_page(app, obj):
    return app.child(WikiApp(obj.wiki_id))

You have told Morepath that when it wants to create a link to a wiki page it should consult a mounted wiki app? Which wiki id to use is determined by inspecting the wiki page object -- it's assumed it knows in which wiki it belongs in this example.

Now you can just write this in the user app to link to wiki pages:

Read the nesting applications documentation for more details.