Documentation¶

Video intro¶

Here is a a 25 minute introduction to Morepath, originally given at EuroPython 2014:

Morepath Super Powers¶

• Automatic hyperlinks that don’t break.
• Creating generic UIs is as easy as subclassing.
• Simple, flexible, powerful permissions.
• Reuse views in views.
• Extensible apps. Nestable apps. Override apps, even override Morepath itself!

Curious how Morepath compares with other Python web frameworks? See Comparison with other Web Frameworks.

Morepath Knows About Your Models¶

import morepath

class App(morepath.App):
    pass

class Document(object):
    def __init__(self, id):
        self.id = id

@App.path(path='')
class Root(object):
    pass

@App.path(path='documents/{id}', model=Document)
def get_document(id):
    return Document(id)  # query for doc

@App.html(model=Root)
def hello_root(self, request):
    return '<a href="%s">Go to doc</a>' % request.link(Document('foo'))

@App.html(model=Document)
def hello_doc(self, request):
    return '<p>Hello document: %s!</p>' % self.id

if __name__ == '__main__':
    config = morepath.setup()
    config.scan()
    config.commit()
    morepath.run(App())

Want to know what’s going on? Check out the Quickstart!

More documentation, please!¶

• Read the documentation

If you have questions, please join the #morepath IRC channel on freenode. Hope to see you there!

Hello world¶

Let’s look at a minimal “Hello world!” application in Morepath:

import morepath

class App(morepath.App):
    pass

@App.path(path='')
class Root(object):
    pass

@App.view(model=Root)
def hello_world(self, request):
    return "Hello world!"

if __name__ == '__main__':
    config = morepath.setup()
    config.scan()
    config.commit()
    morepath.run(App())

You can save this as hello.py and then run it with Python:

$ python hello.py
Running <morepath.App 'Hello'> with wsgiref.simple_server on http://127.0.0.1:5000

If you now go with a web browser to the URL given, you should see “Hello world!” as expected. When you want to stop the server, just press control-C.

This application is a bit bigger than you might be used to in other web micro-frameworks. That’s for a reason: Morepath is not geared to create the most succinct “Hello world!” application but to be effective for building slightly larger applications, all the way up to huge ones.

Let’s go through the hello world app step by step to gain a better understanding.

Code Walkthrough¶

1. We import morepath.

2. We create a subclass of morepath.App named App. This class contains our application’s configuration: what models and views are available. It can also be instantiated into a WSGI application object.

3. We then set up a Root class. Morepath is model-driven and in order to create any views, we first need at least one model, in this case the empty Root class.

   We set up the model as the root of the website (the empty string '' indicates the root, but '/' works too) using the morepath.App.path() decorator.

4. Now we can create the “Hello world” view. It’s just a function that takes self and request as arguments (we don’t need to use either in this case), and returns the string "Hello world!". The self argument is the instance of the model class that is being viewed.

   We then need to hook up this view with the morepath.App.view() decorator. We say it’s associated with the Root model. Since we supply no explicit name to the decorator, the function is the default view for the Root model on /.

5. The if __name__ == '__main__' section is a way in Python to make the code only run if the hello.py module is started directly with Python as discussed above. In a real-world application you instead use a setuptools entry point so that a startup script for your application is created automatically.

6. morepath.setup() sets up Morepath’s default behavior, and returns a Morepath config object. If your app is in a Python package and you’ve set up the right install_requires in setup.py, consider using morepath.autosetup() to be done in one step.

7. We then scan() this module (or package) for configuration decorators (such as morepath.App.path() and morepath.App.view()) and cause the registration to be registered using morepath.Config.commit().

   This step ensures your configuration (model routes, views, etc) is loaded exactly once in a way that’s reusable and extensible.

   Note that if you want to use a Morepath extension like more.static, you need to either scan this as well:

   import more.static
   
   ...
   config.scan(more.static)
   ...
   

   or use morepath.autosetup() to automate this. See Organizing your Project for more information.

8. We then instantiate the App class to create a WSGI app using the default web server. Since you create a WSGI app you can also plug it into any other WSGI server.

This example presents a compact way to organize your code in a single module, but for a real project we recommend you read Organizing your Project. This supports organizing your project with multiple modules.

Routing¶

Morepath uses a special routing technique that is different from many other routing frameworks you may be familiar with. Morepath does not route to views, but routes to models instead.

class User(object):
     def __init__(self, username, fullname, email):
         self.username = username
         self.fullname = fullname
         self.email = email

users = {}
def add_user(user):
     users[user.username] = user

faassen = User('faassen', 'Martijn Faassen', 'faassen@startifact.com')
bob = User('bob', 'Bob Bobsled', 'bob@example.com')
add_user(faassen)
add_user(bob)

@App.path(model=User, path='/users/{username}',
          variables=lambda model: dict(username=model.username))
def get_user(username):
    return users.get(username)

/users/faassen

/users/bob

@App.path(model=User, path='/users/{username}')
def get_user(username):
    return users.get(username)

@App.path(model=Post, path='posts/{post_id}', converters=dict(post_id=int))
def get_post(post_id):
    return query_post(post_id)

@App.path(model=Post, path='posts/{post_id}')
def get_post(post_id=0):
    return query_post(post_id)

@App.view(model=User)
def user_info(self, request):
    return "User's full name is: %s" % self.fullname

@App.view(model=User, name='edit')
def edit_user(self, request):
    return "An editing UI goes here"

request.link(bob)

request.link(bob, 'edit')

@App.json(model=User, name='info')
def user_json_info(self, request):
    return {'username': self.username,
            'fullname': self.fullname,
            'email': self.email}

@App.html(model=User)
def user_info(self, request):
    return "<p>User's full name is: %s</p>" % self.fullname

Request object¶

The first argument for a view function is the request object. We’ll give a quick overview of what’s possible here, but consult the WebOb API documentation for more information.

• request.GET contains any URL parameters (?key=value). See webob.request.BaseRequest.GET.
• request.POST contains any HTTP form data that was submitted. See webob.request.BaseRequest.POST.
• request.method gets the HTTP method (GET, POST, etc). See webob.request.BaseRequest.method.
• request.cookies contains the cookies. See webob.request.BaseRequest.cookies. response.set_cookie can be used to set cookies. See webob.response.Response.set_cookie().

Redirects¶

To redirect to another URL, use morepath.redirect(). For example:

@App.view(model=User, name='extra')
def redirecting(self, request):
    return morepath.redirect(request.link(self, 'other'))

HTTP Errors¶

To trigger an HTTP error response you can raise various WebOb HTTP exceptions (webob.exc). For instance:

from webob.exc import HTTPNotAcceptable

@App.view(model=User, name='extra')
def erroring(self, request):
    raise HTTPNotAcceptable()

But note that Morepath already raises a lot of these errors for you automatically just by having your structure your code the Morepath way.

Mailing list/forum¶

There’s a mailing list/web forum for discussing Morepath. Discussion about use and development of Morepath are both welcome:

https://groups.google.com/forum/#!forum/morepath

Feel free to speak up. Questions are very welcome!

#morepath on Freenode IRC¶

Want to chat with us? Join us on the #morepath channel on Freenode IRC.

If you don’t have an IRC client, an easy way to use Freenode is through its webchat feature.

Github¶

Morepath is maintained as a Github project:

https://github.com/morepath/morepath

Feel free to fork it and make pull requests!

We use the Github issue tracker for discussion about bugs and new features:

https://github.com/morepath/morepath/issues

So please report issues there. Feel free to add new issues!

Quick and Dirty Installation¶

To get started with Morepath right away, first create a Python 2.7 virtualenv:

$ virtualenv morepath_env
$ source morepath_env/bin/activate

Now install Morepath into it:

$ pip install morepath

You can now use the virtual env’s Python to run any code that uses Morepath:

$ python quickstart.py

See Quickstart for information on how to get started with Morepath itself, including an example of quickstart.py.

Creating a Morepath Project¶

When you develop a web application it’s a good idae to use standard Python project organization practices. Organizing your Project describes some recommendations on how to do this with Morepath. Relevant in particular is the contents of setup.py, which depends on Morepath and also sets up an entry point to start the web server.

Once you have a project you can use tools like pip or buildout. We’ll briefly describe how to use both.

$ pip install --editable .

$ myproject-start

[buildout]
develop = .
parts = scripts devpython
versions = versions

[versions]
venusian = 1.0a8
morepath = 0.1
reg = 0.6

[scripts]
recipe = zc.recipe.egg:scripts
eggs = myproject
       pytest

[devpython]
recipe = zc.recipe.egg
interpreter = devpython
eggs = myproject
       flake8

$ /path/to/morepath_env/bin/python bootstrap.py

$ bin/buildout

$ bin/myproject-start

bin/myproject-start

bin/py.test myproject

extras_require = dict(
  test=['pytest >= 2.5',
        'pytest-cov'],
),

[scripts]
recipe = zc.recipe.egg:scripts
eggs = myproject [test]
       pytest

$ bin/devpython

$ bin/flake8 myproject

Depending on Morepath development versions¶

If you like being on the cutting edge and want to depend on the latest Morepath and Reg development versions always, we recommend you use buildout with the mr.developer extension for your project. You can see how in this buildout.cfg.

You can also install these using pip (in a virtualenv). Here’s how:

$ pip install git+git://github.com/morepath/reg.git@master

$ pip install git+git://github.com/morepath/morepath.git@master

Link with Ease¶

Since Morepath knows about your models, it can generate links to them. If you have a model instance (for example through a database query), you can get a link to it by calling morepath.Request.link():

request.link(my_model)

Want a link to its edit view (or whatever named view you want)? Just do:

request.link(my_model, 'edit')

If you create links this way everywhere (and why shouldn’t you?), you know your application’s links will never break.

For much more, see Paths and Linking.

Generic UI¶

Morepath knows about model inheritance. It lets you define views for a base class that automatically become available for all subclasses. This is a powerful mechanism to let you write generic UIs.

For example, if we have this generic base class:

class ContainerBase(object):
    def entries(self):
       """All entries in the container returned as a list."""

We can easily define a generic default view that works for all subclasses:

@App.view(model=ContainerBase)
def overview(self, request):
    return ', '.join([entry.title for entry in self.entries()])

But what if you want to do something different for a particular subclass? What if MySpecialContainer needs it own custom default view? Easy:

@App.view(model=MySpecialContainer)
def special_overview(self, request):
    return "A special overview!"

Morepath leverages the power of the flexible Reg generic function library to accomplish this.

For much more, see Views.

Model-driven Permissions¶

Morepath features a very flexible but easy to use permission system. Let’s say we have an Edit permission; it’s just a class:

class Edit(object):
    pass

And we have a view for some Document class that we only want to be accessible if the user has an edit permission:

@App.view(model=Document, permission=Edit)
def edit_document(self, request):
    return "Editable"

How does Morepath know whether someone has Edit permission? We need to tell it using the morepath.App.permission_rule() directive. We can implement any rule we want, for instance this one:

@App.permission_rule(model=Document, permission=Edit)
def have_edit_permission(identity, model, permission):
    return model.has_permission(identity.userid)

Instead of a specific rule that only works for Document, we can also give our app a broad rule (use model=object).

Composable Views¶

Let’s say you have a JSON view for a Document class:

@App.json(model=Document)
def document_json(self, request):
    return {'title': self.title}

And now we have a view for a container that contains documents. We want to automatically render the JSON views of the documents in a list. We can write this:

@App.json(model=DocumentContainer)
def document_container_json(self, request):
    return [document_json(request, doc) for doc in self.entries()]

Here we’ve used document_json ourselves. But what now if the container does not only contain Document instances? What if one of them is a SpecialDocument? Our document_container_json function breaks. How to fix it? Easy, we can use morepath.Request.view():

@App.json(model=DocumentContainer)
def document_container_json(self, request):
    return [request.view(doc) for doc in self.entries()]

Now document_container_json works for anything in the container model that has a default view!

Extensible Applications¶

Somebody else has written an application with Morepath. It contains lots of stuff that does exactly what you want, and one view that doesn’t do what you want:

@App.view(model=Document)
def recalcitrant_view(self, request):
    return "The wrong thing!"

Ugh! We can’t just change the application as it needs to continue to work in its original form. Besides, it’s being maintained by someone else. What do we do now? Monkey-patch? Not at all: Morepath got you covered. You simply create a new application subclass that extends the original:

class MyApp(App):
    pass

We now have an application that does exactly what app does. Now to override that one view to do what we want:

@MyApp.view(model=Document)
def whatwewant(self, request):
    return "The right thing!"

And we’re done!

It’s not just the view directive that works this way: all Morepath directives work this way.

Morepath also lets you mount one application within another, allowing composition-based reuse. See App Reuse for more information. Using these techniques you can build large applications, see Building Large Applications.

HTTP protocol¶

HTTP is a protocol by which clients (such as web browsers) and servers can communicate. The client sends a HTTP request, and the server sends back a HTTP response. HTTP is extensible, and can be extended with content types, new headers, and so on.

Version 1.1 of HTTP is most common on the web today. It is defined by a bunch of specifications:

• RFC7230 - HTTP/1.1: Message Syntax and Routing
• RFC7231 - HTTP/1.1: Semantics and Content
• RFC7232 - HTTP/1.1: Conditional Requests
• RFC7233 - HTTP/1.1: Range Requests
• RFC7234 - HTTP/1.1: Caching
• RFC7235 - HTTP/1.1: Authentication

Luckily it’s not necessary to understand the full details of these specifications to develop a web application. We’ll go into a basic overview of relevant concepts in this document.

Morepath handles the HTTP protocol on the server side: creating a response to incoming HTTP requests.

Web browser¶

A web browser such as Firefox, Chrome and Internet Explorer uses the HTTP protocol to talk to web servers.

A web browser is a type of HTTP client.

Web server¶

A web server implements the HTTP protocol to respond to requests from HTTP clients such as web browsers.

There are general web servers such as Apache and Nginx. These are programmable in various ways.

There are also more specific web servers that are geared at particular tasks. Examples of these are Waitress and Gunicorn which are geared towards serving web applications written in Python.

A web server is programmable in various ways. Morepath can plug into web servers that implement the Python WSGI protocol.

Web application¶

A web application is software that presents a user interface by means of a web browser. The web browser is usually a visible piece of software, but may also be embedded in other software, such as in FirefoxOS.

A web application is loaded from a web server. After it is loaded it can still interact with the web server (or other web servers). The web server can implement part of the application logic and maintains the application data.

The dynamic behavior of a web application used to be implemented almost entirely by the server, but it is now also possible to implement a large part of their behavior within the web browser instead, using the JavaScript language.

Morepath code runs entirely on the server, but supports web applications that want to implement a large part of their dynamic behavior within the web browser.

Web service¶

A web service does not present a user interface to the user. A web service instead presents an application programming interface (API) to custom HTTP client software. The API is to this software what the UI is to the user.

You can layer a full web application on top of a web service. Such layering can result in looser coupling in the implementation, which tends to increase the quality of the implementation.

Morepath helps developers to implement web services.

Custom HTTP client¶

A web browser is one form of HTTP client, but other HTTP software can be written in a variety of languages to talk to a web server programmatically. This uses it as a web service.

JavaScript code in a web browser can also use the browser’s facilities to talk to the web server programmatically (a technique called AJAX), and can thus serve as a custom HTTP client as well.

Framework¶

A library is reusable code that your code calls, whereas a framework is reusable code that calls your code. “Don’t call us, we’ll call you”.

A framework aims to help you do particular tasks quickly; you only need to fill in the details, and the framework handles the rest.

There is a gray area between library and framework. Morepath is mostly a framework.

Server web framework¶

A framework that helps you program the behavior of a web server. Morepath is a server web framework written in the Python programming language.

JavaScript¶

JavaScript is a programming language that is run in the browser. It can use the web browser APIs (such as the DOM) to manipulate the web page, get user input, or access the server programmatically (AJAX).

JavaScript can also be run on the server with Node.JS, but Morepath is a Python web framework and does not make use of server-side JavaScript.

Bower is a tool to help manage client-side JavaScript code.

Bower¶

A popular way to install client-side JavaScript (and CSS) code is to use the Bower package management tool. By using a package manager installing and updating a collection of JavaScript libraries becomes more easy than doing it by hand.

Morepath offers Bower integration, see: Static resources with Morepath.

AJAX¶

AJAX is a technique to access resources programmatically from a browser application in JavaScript. These resources typically have a JSON representation.

Client web framework¶

There are also client-side web frameworks that let you program the behavior of a web browser, typically called “JavaScript MVC framework”. Examples of such are React, Ember and Angular.

Morepath supports client-side code that uses a client web framework, but does not implement a client web framework itself. You can pick whichever you want.

WSGI¶

WSGI is a Python protocol by which Python code can be integrated with a web server. WSGI can also be used to implement framework components which are layered between application code and server.

A morepath.App instance implements the WSGI protocol and can therefore be integrated with a WSGI-compliant web server and WSGI framework component.

HTTP request¶

A HTTP request is a message a HTTP client sends to the server. The server then returns a HTTP response.

The HTTP request contains a URL path, a request method, possibly a request body, and various headers such as the content type.

A HTTP request in Morepath is made accessible programmatically as a Python request object using the WebOb library. It is a class:`morepath.Request, which is a subclass of webob.request.BaseRequest.

HTTP response¶

A HTTP response returns a representation of the resource indicated by the path of the request as the response body. The response has a content type which determines what representation is being sent. The response also has a status code that indicates whether the request could be handled, or the reason why a detailed response could not be generated.

A lot of different representations exist. HTML is a very common one, but for programmatic clients JSON is typically used.

Morepath lets you create a morepath.Response object directly, which is a subclass of webob.response.Response, and return it from a view function.

More conveniently you use a specialized view type (morepath.App.json() or morepath.App.html()) and return the content that should go into the response body, such as a HTML string or a JSON-serializable object. Morepath then automatically creates the response with the right content type for you. Should you wish to set additional information on the response object, you can use morepath.Request.after().

Resource¶

A resource is anything that can be addressed on the web by a URL (or URI or IRI). Can be a web page presenting a full UI (using HTML + CSS), or can be a piece of information (typically in JSON), or can also be an abstract entity that has no representation at all.

Morepath lets you implement resources of all kinds. Normally Morepath resources have representations, but it is also possible to implement abstract entities that have just a URL and have no representation. Morepath can also help you create links to resources on other web servers.

URL¶

Here is an example of a URL:

http://example.com/documents/3

A HTTP client such as a web browser uses URLs to determine:

• What protocol to use to talk to the server (in this case http).
• What host to talk to (in this case example.com). This identifies the web server, though a complex host may be implemented using a combination of web servers.
• What path to request from the server (in this case /documents/3).

The server determines how it responds to requests for particular paths.

Path¶

A path is a way for a client to address a particular resource on a server. It is part of the request. The path is also part of URLs, and thus can be used for linking resources.

Morepath connects paths with Python objects using the path directive (morepath.App.path()): it can resolve a path to a Python object, and construct a path for a given Python object. This is described in Paths and Linking.

Example:

@App.path(path='/documents/{id}', model=Document)
def get_document(id):
   return query_document(id)

Link generation¶

Morepath makes it easy to generate a hyperlink to a Python object. Morepath uses information on the object itself and its class to determine what link to generate.

Given the path directive above, we can generate a link to an instance of Document using morepath.Request.link():

some_document = get_some_document_from_somewhere()
request.link(some_document)

This makes it easy to create links within Morepath view functions.

Headers¶

A HTTP request and a HTTP response have headers. Headers contain information about the message that are not the body: they are about the request or the response, or about the body. For example, the content-type is header named Content-Type and has a value that is a MIME type such as text/html.

Headers are used for a wide variety of purposes, such as to declare information about how a client may cache a response, or what kind of responses a client accepts from a server, or to pass cookies along. Here is an overview of common headers.

In Morepath, the headers are accessible on a request and response object as the attribute webob.request.BaseRequest.headers and webob.response.Response.headers. which behaves like a Python dictionary. You could therefore access the request content-type using request.headers['Content-Type']. But see below for a more convenient way to access the content type.

To set the headers (or other information) on a response, you can create a morepath.Response instance in a view function. You can then pass in the headers, or set them afterward.

Often better is to use the morepath.Request.after() decorator to declare a function that sets headers the response object once it has been created for you by the framework.

WebOb has APIs that help you deal with many headers at a higher level of abstraction. For example, webob.request.BaseRequest.content_type is a more convenient way to access the content type information of a request than to access the header directly, as additional charset information is not there. Before you start to manipulate headers directly it pays off to consult the WebOb documentation for webob.request.BaseRequest and webob.response.Response: there may well be a better way.

Morepath also has special support for dealing with certain headers. For instance, the Forwarded header can be set by a HTTP proxy. To make Morepath use this header for URL generation, you can use the more.forwarded extension.

Cookies¶

One special set of headers deals with HTTP cookies. A server can set a cookie on the client by passing back a special header in its response. A cookie is much like a key/value pair in a Python dictionary.

Once the cookie has been set, the client sends back the cookie to the server during each subsequent request, again using a header, until the cookie expires or cookie is explicitly deleted by the server using a response header.

Normally in HTTP requests are independent from each other: assuming the server database is the same, the same request should give the same response, no matter what other requests have gone before it. This makes it easier to reason about HTTP, and it makes it easier to scale it up, for instance by caching responses.

Cookies change this: they can be used to make requests order-dependent. This can be useful, but it can also make it harder to reason about what is going on and scale, so be careful with them. In particular, a REST web service should be able to function without requiring the client to maintain cookies.

Cookies are commonly used to store login session information on the client.

WebOb makes management of cookies more convenient: the webob.request.BaseRequest.cookies attribute on the request object contains the list of cookies sent by the client, and the response object has an API incuding webob.response.Response.set_cookie() and webob.response.Response.delete_cookie() to allow you to manage cookies.

Content types¶

A resource may present itself in variety of representations. This is indicated by the content type set in the HTTP response, using the Content-Type header. There are a lot of content types, including HTML and JSON. The value is a MIME type such as text/html for HTML and application/json for JSON. The value can also contain additional parameters such as character encoding information.

WebOb makes content-type header information conveniently available with the webob.request.BaseRequest.content_type, webob.response.Response.content_type and webob.response.Response.content_type_params attributes.

A request may also have a content type: the request content type determines what kind of content is sent to the server by the client in the request body.

While you can create any kind of content type with Morepath, it has special support for generating HTML and JSON responses (using morepath.App.html() and morepath.App.json()), and for processing a JSON request body (see load_json in JSON and objects).

View¶

In Morepath, a view is a Python function that takes a Python object to represent (self) and a morepath.Request object (request) as arguments and returns something that can be turned into a HTTP response, or a HTTP response object directly.

Here is an example of a Morepath view, using the most basic morepath.App.view() directive:

@App.view(model=MyObject)
def my_object_default(self, request):
    return "some text content"

There are also specific morepath.App.json() and morepath.App.html() directives to support those content types.

See Views for much more on how to construct Morepath views.

HTTP request method¶

A HTTP request has a method, also known as HTTP verb. The GET method is used to retrieve information from the server. The POST method is used to add new information to the server (for instance a form submit), and the PUT method is used to update existing information. The DELETE method is used to delete information from the server.

It is up to the server implementation how to exactly handle the request method. With Morepath, by default a view responds to the GET method, but you can also write views to handle the other HTTP methods, by indicating it with a view predicate. Here is a view that handles the POST method (and returns a representation of what has just been POSTed):

@App.view(model=MyCollection, request_method='POST')
def add_to_collection(self, request):
    item = MyItem(request.json)
    self.add(item)
    return request.view(item)

You can access the method on the request using webob.request.BaseRequest.method, but typically Morepath does this for you when you use the request_method predicate.

View predicate¶

A view predicate in Morepath is used to match a view function with details of self and request.

This view directive:

@App.view(model=MyCollection, request_method='POST')
def add_to_collection(self, request):
   ...

only matches when self is an instance of MyCollection (model predicate) and when request.method is POST (request_method predicate). Only in this case will add_to_collection be called.

You can extend Morepath with additional view predicates. You can also define a predicate fallback, which can be used to specify what HTTP status code to set when the view cannot be matched.

See view predicates

HTTP status codes¶

HTTP status codes such as 200 Ok and 404 Not Found are part of the HTTP response. Here is a list of HTTP status codes. The server can use them to indicate to the client whether it was successfully able to create a response, or if not, what the problem was.

Morepath can automatically generate the correct HTTP status codes for you in many cases:

200 Ok:

When the path in the request is matched with a path directive, and there is a view for the particular model and request method.

404 Not Found:

When the path does not match, or when the path matches but the path function returns None.

Also when no view is available for the request in combination with the object returned by the path function. More specifically, the model view predicate or the name view predicate do not match.

400 Bad Request:

When information in the path or request parameters could not be converted to the required types.

405 Method Not Allowed:

When no view exists for the given HTTP request method. More specifically, the request_method view predicate does not match.

422 Unprocessable Entity:

When the request body supplied with a POST or PUT request can be parsed (as JSON, for instance), but is not the correct type.

More specifically, the body_model view predicate does not match.

500 Internal Server Error:

There is a bug in the server that causes an exception to be raised. Morepath does not generate these itself, but a WSGI server automatically catches any exceptions not handled by Morepath and turns them into 500 errors.

Instead of having to write code that sends back the right status codes manually, you declare paths and views with Morepath and Morepath can usually do the right thing for you automatically. This saves you from writing a lot of custom code when you want to implement HTTP properly.

Sometimes it is still useful to set the status code directly. WebOb lets you raise special exceptions for HTTP errors. You can also set the webob.response.Response.status attribute on the response.

JSON¶

A representation of a resource. JSON is a language that represents data, not user interface (like HTML combined with CSS) or logic (like Python or JavaScript). JSON looks like this:

{
  "id": "foo_barson",
  "name": "Foo Barson",
  "occupation": "Carpenter",
  "level": 34
  "friends": ["http://example.com/people/qux_quxson",
              "http://example.com/people/one_twonson"]
}

JSON is the most common data representation language used in REST web services. The main alternative is XML. While XML does offer more extensive tooling support, it is a lot more verbose and more difficult to process than JSON. JSON is already very close to the data structures of many programming languages, including JavaScript and Python.

In Python, JSON can be constructed by combining Python dictionaries and lists with strings, numbers, booleans and None.

With Morepath you can use the morepath.App.json() directive to generate JSON programmatically:

@App.json(model=MyObject)
def my_object_default(self, request):
     return {
        "id": self.id,
        "name": self.name,
        "occuptation": self.get_occupation(),
        "level": self.level,
        "friends": [request.link(friend) for friend in self.friends]
     }

This works like the view directive, but in addition converts the return value of the function into a JSON response that is sent to the client.

JSON-LD¶

JSON-LD is an extension of JSON that helps support linked data in JSON. Any JSON-LD structure is valid JSON, but not every JSON structure is valid JSON-LD.

Using a @context, it lets a JSON object describe which parts of it contain hyperlinks, and also allows JSON property names themselves to be interpreted as unique hyperlinks. You can also express that particular property values have a particular data type; this can range from basic data types like datetime to custom data types like “person”. All of this can help when you want to process JSON coming from different data sources.

Perhaps more important in practice for REST web services is that it also offers a standard way for a JSON object to have a unique id and a type. Both are identified by a hyperlink, as the special @id and @type properties. @type in particular makes it easier to use JSON data as hypermedia: client behavior can be driven by the type of data that is retrieved, instead of what URL it happened to be retrieved from.

Morepath does not mandate the use of JSON-LD, or has any special support for it, but its link generation facilities make it easier to use it.

HTTP API¶

A HTTP API is a web service that is built on HTTP; it is based on the notion of HTTP resources on URLs and has an understanding of HTTP request methods.

This is to distinguish it from a web service implementation where HTTP is merely a transport mechanism, such as SOAP.

Because the client needs to understand what URLs exist on the server and how to interpret their response, the coupling between client and server code is relatively tight.

This type of web service is commonly called a REST web service, but the original definition of REST goes beyond this and adds hypermedia. Many HTTP APIs only reach level 2 on the Richardson Maturity Model, which isn’t full REST yet.

A HTTP API is sometimes simply called API, which is also confusing, as the word API has a lot of other uses in development outside of HTTP.

Morepath is designed to help you build HTTP APIs, but also to go you a step further to full REST.

REST web service¶

Morepath helps you to create REST web service, also known as a hypermedia API.

This is level 3 on the Richardson Maturity Model.

This means that to interact with the content of the web service you can follow hyperlinks. A client starts at one root URL and to get to other information it follow links in the content.

Different JSON resources can be distinguished from each other by their type; this can based on the content-type of the response, or be based on information within the content itself, such as a type property in JSON (@type in JSON-LD).

In other words, the web service represents itself to software much like a web site presents itself to a human: as content with links.

A REST web service allows for a looser coupling between server and client than a plain HTTP API allows, as the client does not need to know more than a single entry point URL into the server, and only needs an understanding of the response types and how to navigate links.

HTML and CSS¶

HTML is a markup language used to represent a resource. Augmented by CSS, a style language, it determines what you see on a web page.

HTML can be loaded from a files on the server; this typically done with a general web server such as Apache and Nginx. For dynamic applications HTML can also be generated on the server, often using a server-side templating language.

HTML may also be manipulated programmatically in the browser using JavaScript through the DOM API.

In Morepath you can use the morepath.App.html() view directive to generate HTML programmatically:

@App.view(model=MyObject)
def my_object_default(self, request):
     return '<html><head></head><body></body></html>'

Morepath at this point does not have support for server-side templating.

See Static resources with Morepath for information on how you can load static resources such as CSS and JavaScript automatically to augment a HTML page.

Web page¶

The browser displays a user interface to the user in the form of a web page. A web page is usually constructed using HTML and CSS. Other content such as images, video, audio, SVG, canvas, WebGL may also be embedded into it.

JavaScript code is executed in the browser to make the user interface more dynamic, and this dynamism can go very far.

A web page is loaded by putting a URL in the address bar of the browser. The browser then fetches it (and related resources) from the server. You can do this manually, or by clicking a link, or the URL of the browser may be changed programmatically with JavaScript code.

In the past, all web applications were implemented as a multiple web pages that were generated on the server in response to user actions.

It is also possible to change the URL in the address bar without fetching a complete new web page from the server. This technique is used to implement single-page web applications.

Single-page web application¶

A single-page web application (SPA) is web application that consists of a single web page that is updated within the browser without the need to load a complete need web page. So the web page is loaded from the server only once, when the user first goes there.

When a user interacts with it, JavaScript code is executed that updates the user interface and may also interact with a web server using AJAX.

A single page web application may update the URL in the address bar of the browser, and respond to URL changes, but it is the same web page that implements the behavior for all these URLs. It may need a bit of server-side support to do so.

Morepath supports the creation of single-page web applications. It also lets you create multi-page applications, but at this point in time has no special support for server-side templating.

Introduction¶

Morepath lets you publish model classes on paths using Python functions. It also lets you create links to model instances. To be able do so Morepath needs to be told what variables there are in the path in order to find the model, and how to find these variables again in the model in order to construct a link to it.

Paths¶

@App.path(model=Item, path='items/{id}')
def get_item(id):
   ...

@App.path(model=ItemDetail, path='items/{id}/details/{detail_id}')
def get_item_detail(id, detail_id):
   ...

@App.path(model=Item, path='items/{id}')
def get_item(id):
   ...

@App.path(model=ItemDetail, path='items/{item_id}/details/{detail_id}')
def get_item_detail(item_id, detail_id):
   ...

Let’s assume we have a model class Overview:

class Overview(object):
    pass

Here’s how we could expose it to the web under the path overview:

@App.path(model=Overview, path='overview')
def get_overview():
    return Overview()

And let’s give it a default view so we can see it when we go to its URL:

@App.view(model=Overview)
def overview_default(self, request):
    return "Overview"

No variables are involved yet: they aren’t in the path and the get_overview function takes no arguments.

Let’s try a single variable now. We have a class Document:

class Document(object):
    def __init__(self, name):
        self.name = name

Let’s expose it to the web under documents/{name}:

@App.path(model=Document, path='documents/{name}')
def get_document(name):
    return query_document_by_name(name)

@App.view(model=Document)
def document_default(self, request):
    return "Document: " + self.name

Here we declare a variable in the path ({name}), and it gets passed into the get_document function. The function does some kind of query to look for a Document instance by name. We then have a view that knows how to display a Document instance.

We can also have multiple variables in a path. We have a VersionedDocument:

class VersionedDocument(object):
    def __init__(self, name, version):
        self.name = name
        self.version = version

We could expose this to the web like this:

@App.path(model=VersionedDocument,
          path='versioned_documents/{name}-{version}')
def get_versioned_document(name, version):
    return query_versioned_document(name, version)

@App.view(model=VersionedDocument)
def versioned_document_default(self, request):
    return "Versioned document: %s %s" % (self.name, self.version)

The rule is that all variables declared in the path can be used as arguments in the model function.

URL query parameters¶

What if we want to use URL parameters to expose models? That is possible too. Let’s look at the Document case first:

@App.path(model=Document, path='documents')
def get_document(name):
    return query_document_by_name(name)

get_document has an argument name, but it doesn’t appear in the path. This argument is now taken to be a URL parameter. So, this exposes URLs of the type documents?name=foo. That’s not as nice as documents/foo, so we recommend against parameters in this case: you should use paths to identify something.

URL parameters are more useful for queries. Let’s imagine we have a collection of documents and we have an API on it that allows us to search in it for some text:

class DocumentCollection(object):
    def __init__(self, text):
        self.text = text

    def search(self):
        if self.text is None:
            return []
        return fulltext_search(self.text)

We now publish this collection, making it searchable:

@App.path(model=DocumentCollection, path='search')
def document_search(text):
    return DocumentCollection(text)

To be able to see something, we add a view that returns a comma separated string with the names of all matching documents:

@App.view(model=DocumentCollection)
def document_collection_default(self, request):
    return ', '.join([document.name for document in self.search()])

As you can see it uses the DocumentCollection.search method.

Unlike path variables, URL parameters can be omitted, i.e. we can have a plain search path without a text parameter. In that case text has the value None. The search method has code to handle this special case: it returns the empty list.

Often it’s useful to have a default instead. Let’s imagine we have a default search query, all that should be used if no text parameter is supplied (instead of None). We make a default available by supplying a default value in the document_search function:

@App.path(model=DocumentCollection, path='search')
def document_search(text='all'):
    return DocumentCollection(text)

Note that defaults have no meaning for path variables, because whenever a path is resolved, all variables in it have been found. They can be used as type hints however; we’ll talk more about those soon.

Like with path variables, you can have as many URL parameters as you want.

Extra URL query parameters¶

URL parameters are matched with function arguments, but it could be you’re interested in an arbitrary amount of extra URL parameters. You can specify that you’re interested in this by adding an extra_parameters argument:

@App.path(model=DocumentCollection, path='search')
def document_search(text='all', extra_parameters):
    return DocumentCollection(text, extra_parameters)

Now any additional URL parameters are put into the extra_parameters dictionary. So, search?text=blah&a=A&b=B would match text with the text parameter, and there would be an extra_parameters containing {'a': 'A', 'b': 'B'}.

extra_parameters can also be useful for the case where the name of the parameter is not a valid Python name (such as @foo) – you can still receive such parameters using extra_parameters.

Linking¶

To create a link to a model, we can call morepath.Request.link() in our view code. At that point the model is examined to retrieve the variables so that the path can be constructed.

Here is a simple case involving Document again:

class Document(object):
    def __init__(self, name):
        self.name = name

@App.path(model=Document, path='documents/{name}')
def get_document(name):
    return query_document_by_name(name)

We add a named view called link that links to the document itself:

@App.view(model=Document, name='link')
def document_self_link(self, request):
    return request.link(self)

The view at /documents/foo/link produces the link /documents/foo. That’s the right one!

So, it constructs a link to the document itself. This view is not very useful, but the principle is the same everywhere in any view: as long as we have a Document instance we can create a link to it using request.link().

You can also give link a name to link to a named view. Here’s a link2 view creates a link to the link view:

@App.view(model=Document, name='link2')
def document_self_link(self, request):
    return request.link(self, name='link')

So the view at /documents/foo/link2 produces the link /documents/foo/link.

Linking with path variables¶

How does the request.link code know what the value of the {name} variable should be so that the link can be constructed? In this case this happened automatically: the value of the name attribute of Document is assumed to be the one that goes into the link.

This automatic rule won’t work everywhere, however. Perhaps an attribute with a different name is used, or a more complicated method is used to construct the name. For those cases we can take over and supply a custom variables function that knows how to construct the variables needed to construct the link from the model.

The variables function gets the model as a single argument and needs to return a dictionary. The keys should be the variable names used in the path or URL parameters, and the values should be the values as extracted from the model.

As an example, here is the variables function for the Document case made explicit:

@App.path(model=Document, path='documents/{name}',
          variables=lambda model: dict(name=model.name))
def get_document(name):
    return query_document_by_name(name)

Or to spell it out without the use of lambda:

def document_variables(model):
    return dict(name=model.name)

@App.path(model=Document, path='documents/{name}',
          variables=document_variables)
def get_document(name):
    return query_document_by_name(name)

Let’s change Document so that the name is stored in the id attribute:

class DifferentDocument(object):
    def __init__(self, name):
        self.id = name

Our automatic variables won’t cut it anymore, so we have to be explicit:: attribute, we can do this:

@App.path(model=DifferentDocument, path='documents/{name}',
          variables=lambda model: dict(name=model.id))
def get_document(name):
    return query_document_by_name(name)

All we’ve done is adjust the variables function to take model.id.

Getting variables works for multiple variables too of course. Here’s the explicit variables for the VersionedDocument case that takes multiple variables:

@App.path(model=VersionedDocument,
          path='versioned_documents/{name}-{version}',
          variables=lambda model: dict(name=model.name,
                                       version=model.version))
def get_versioned_document(name, version):
    return query_versioned_document(name, version)

If you have extra_parameters, the default variables expects that extra_parameters to exist as an attribute on the object, but you can write a custom variables that retrieves this dictionary from the object in some other way:

@App.path(model=SearchResults,
          path='search',
          variables=lambda model: dict(text=model.search_text,
                                       extra_parameters=model.get_extra()))
def get_search_results(text, extra_parameters):
    ...

Linking with URL query parameters¶

Linking works the same way for URL parameters as it works for path variables.

Here’s a get_model that takes the document name as a URL parameter, using an implicit variables:

@App.path(model=Document, path='documents')
def get_document(name):
    return query_document_by_name(name)

Now we add back the same self_link view as we had before:

@App.view(model=Document, name='link')
def document_self_link(self, request):
    return request.link(self)

Here’s get_document with an explicit variables:

@App.path(model=Document, path='documents',
          variables=lambda model: dict(name=model.name))
def get_document(name):
    return query_document_by_name(name)

i.e. exactly the same as for the path variable case.

Let’s look at a document exposed on this URL:

/documents?name=foo

Then the view documents/link?name=foo constructs the link:

/documents?name=foo

The documents/link?name=foo is interesting: the name=foo parameters are added to the end, but they are used by the get_document function, not by its views. Here’s link2 again to further demonstrate this behavior:

@App.view(model=Document, name='link2')
def document_self_link(self, request):
    return request.link(self, name='link')

When we now go to documents/link2?name=foo we get the link /documents/link?name=foo.

Prefixing links with a base URL¶

By default, morepath.Request.link() generates links as fully qualified URLs using the HOST header and the given protocol (http, https), for instance:

http://localhost/document

You can use the morepath.App.link_prefix() decorator to override this behavior. For example, if you do not want to add the full hostname (in fact the behavior of Morepath before version 0.9), you can write:

@App.link_prefix()
def simple_link_prefix(request):
    return ''

The link_prefix function is only called once per request per app, during the first call to morepath.Request.link() for an app. After this it is cached for the rest of the duration of that request.

Linking to external applications¶

As a more advanced use case for link_prefix, you can use it to represent an application that is completely external, just for the purposes of making it easier to create a link to it.

Let’s say we want to be able to link to documents on the external site http://example.com, and that these documents live on URLs like http://example.com/documents/{id}.

We can create a model for such an external document first:

class ExternalDocument(object):
    def __init__(self, id):
        self.id = id

And declare the path space of the external site:

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

We don’t need to declare any views for ExternalDocument; ExternalApp only exists to let you generate a link to the example.com external site more easily.

Now we want request.link(ExternalDocument('foo')) to result in the link http://example.com/documents/foo. All we need to do is to declare a special link_prefix for the external app where we hardcode http://example.com:

@ExternalApp.link_prefix()
def simple_link_prefix(request):
    return 'http://example.com'

Type hints¶

So far we’ve only dealt with variables that have string values. But what if we want to use other types for our variables, such as int or datetime? What if we have a record that you obtain by an int id, for instance? Given some Record class that has an int id like this:

class Record(object):
    def __init__(self, id):
        self.id = id

We could do this to expose it:

@App.path(model=Record, path='records/{id}')
def get_record(id):
    try:
        id = int(id)
    except ValueError:
        return None
    return record_by_id(id)

But Morepath offers a better way. We can tell Morepath we expect an int and only an int, and if something else is supplied, the path should not match. Here’s how:

@App.path(model=Record, path='records/{id}')
def get_record(id=0):
    return record_by_id(id)

We’ve added a default parameter (id=0) here that Morepath uses as an indication that only an int is expected. Morepath will now automatically convert id to an int before it enters the function. It also gives a 404 Not Found response for URLs that don’t have an int. So it accepts /records/100 but gives a 404 for /records/foo.

Let’s examine the same case for an id URL parameter:

@App.path(model=Record, path='records')
def get_record(id=0):
    return record_by_id(id)

This responds to an URL like /records?id=100, but rejects /records/id=foo as foo cannot be converted to an int. It rejects a request with the latter path with a 400 Bad Request error.

By supplying a default for a URL parameter we’ve accomplished two in one here, as it’s a good idea to supply defaults for URL parameters anyway, as that makes them properly optional.

Conversion¶

Sometimes simple type hints are not enough. What if multiple possible string representations for something exist in the same application? Let’s examine the case of datetime.date.

We could represent it as a string in ISO 8601 format as returned by the datetime.date.isoformat() method, i.e. 2014-01-15 for the 15th of january 2014. We could also use ISO 8601 compact format, namely 20140115 (and this what Morepath defaults to). But we could also use another representation, say 15/01/2014.

Let’s first see how a string with an ISO compact date can be decoded (deserialized, loaded) into a date object:

from datetime import date
from time import mktime, strptime

def date_decode(s):
    return date.fromtimestamp(mktime(strptime(s, '%Y%m%d')))

We can try it out:

>>> date_decode('20140115')
datetime.date(2014, 1, 15)

Note that this function raises a ValueError if we give it a string that cannot be converted into a date:

>>> date_decode('blah')
Traceback (most recent call last):
   ...
ValueError: time data 'blah' does not match format '%Y-%m-%d'

This is a general principle of decode: a decode function can fail and if it does it should raise a ValueError.

We also specify how to encode (serialize, dump) a date object back into a string:

def date_encode(d):
    return d.strftime('%Y%m%d')

We can try it out too:

>>> date_encode(date(2014, 1, 15))
'20140115'

A encode function should never fail, if at least presented with input of the right type, in this case a date instance.

encode(decode(s)) == s

decode(encode(o)) == o

Now that we have our date_decode and date_encode functions, we can wrap them in an morepath.Converter object:

date_converter = morepath.Converter(decode=date_decode, encode=date_encode)

Let’s now see how we can use date_converter.

We have some kind of Records collection that can be parameterized with start and end to select records in a date range:

class Records(object):
   def __init__(self, start, end):
      self.start = start
      self.end = end

   def query(self):
      return query_records_in_date_range(self.start, self.end)

We expose it to the web:

@App.path(model=Records, path='records',
          converters=dict(start=date_converter, end=date_converter))
def get_records(start, end):
    return Records(start, end)

We also add a simple view that gives us comma-separated list of matching record ids:

@App.view(model=Records):
def records_view(self, request):
    return ', '.join([str(record.id) for record in self.query()])

We can now go to URLs like this:

/records?start=20110110&end=20110215

The start and end URL parameters now are decoded into date objects, which get passed into get_records. And when you generate a link to a Records object, the start and end dates are encoded into strings.

What happens when a decode raises a ValueError, i.e. improper dates were passed in? In that case, the URL parameters cannot be decoded properly, and Morepath returns a 400 Bad Request response.

You can also use encode and decode for arguments used in a path:

@App.path(model=Day, path='days/{d}', converters=dict(d=date_converter))
def get_day(d):
    return Day(d)

This publishes the model on a URL like this:

/days/20110101

When you pass in a broken date, like /days/foo, a ValueError is raised by the date decoder, and a 404 not Found response is given by the server: the URL does not resolve to a model.

Default converters¶

Morepath has a number of default converters registered; we already saw examples for int and strings. Morepath also has a default converter for date (compact ISO 8601, i.e. 20131231) and datetime (i.e. 20131231T23:59:59).

You can add new default converters for your own classes, or override existing default behavior, by using the morepath.App.converter() decorator. Let’s change the default behavior for date in this example to use ISO 8601 extended format, so that dashes are there to separate the year, month and day, i.e. 2013-12-31:

def extended_date_decode(s):
    return date.fromtimestamp(mktime(strptime(s, '%Y-%m-%d')))

def extended_date_encode(d):
    return d.strftime('%Y-%m-%d')

@App.converter(type=date)
def date_converter():
    return Converter(extended_date_decode, extended_date_encode)

Now Morepath understand type hints for date differently:

@App.path(model=Day, path='days/{d}')
def get_day(d=date(2011, 1, 1)):
    return Day(d)

has models published on a URL like:

/days/2013-12-31

Type hints and converters¶

You may have a situation where you don’t want to add a default argument to indicate the type hint, but you know you want to use a default converter for a particular type. For those cases you can pass the type into the converters dictionary as a shortcut:

@App.path(model=Day, path='days/{d}', converters=dict(d=date))
def get_day(d):
    return Day(d)

The variable d is now interpreted as a date. Morepath uses whatever converter that was registered for that type.

List converters¶

What if you want to allow a list of parameters instead of just a single one? You can do this by wrapping the converter or type in the converters dictionary in a list:

@App.path(model=Days, path='days', converters=dict(d=[date]))
def get_days(d):
    return Days(d)

Now the d parameter will be interpreted as a list. This means URLs like this are accepted:

/days?d=2014-01-01

/days?d=2014-01-01&d=2014-01-02

/days

For the first case, d is a list with one date item, in the second case, d has 2 items, and in the third case the list d is empty.

get_converters¶

Sometimes you only know what converters are available at run-time; this particularly relevant if you want to supply converters for the values in extra_parameters. You can supply the converters using the special get_converters parameter to @app.path:

def my_get_converters():
    return { 'something': int }

@App.path(path='search', model=SearchResults,
          get_converters=my_get_converters)
...

Now if there is a parameter (or extra parameter) called something, it is converted to an int.

You can combine converters and get_converters. If you use both, get_converters will override any converters also defined in the static converters. This can also be useful for dealing with URL parameters that are not valid Python names, such as @foo or foo[]; these can still be converted using get_converters.

Required¶

Sometimes you may want a URL parameter to be required: when the URL parameter is missing, it’s an error and a 400 Bad Request should be returned. You can do this by passing in a required argument to the model decorator:

@App.path(model=Record, path='records', required=['id'])
def get_record(id):
    return query_record(id)

Normally when the id URL parameter is missing, the None value is passed into get_record (if there is no default). But since we made id required, 400 Bad Request will be issued if id is missing now. required only has meaning for URL parameters; path variables are always present if the path matches at all.

Absorbing¶

In some special cases you may want a path to match all sub-paths, absorbing them. This can be useful if you are writing a server backend to a client side application that does routing on the client using the HTML 5 history API – the server needs to handle catch all subpaths in that case and send them back to the client, where they can be handled by the client-side router.

You can do this using the special absorb argument to the path decorator, like this:

class Model(object):
    def __init__(self, absorb):
        self.absorb = absorb

@App.path(model=Model, path='start', absorb=True)
def get_foo(absorb):
    return Model(absorb)

As you can see, if you use absorb then a special absorb argument is passed into the model factory function.

Now the start path matches all of its sub-paths. So for this path:

/start/foo/bar/baz

model.absorb is foo/bar/baz.

It also matches if there is no sub-path:

/start

model.absorb is the empty string ''.

Note that you cannot use view names with a path that absorbs; only a default view with the empty name. View names are absorbed along with the rest of the path.

Note also that you cannot define an explicit path under an absorbed path – this is ignored. This means that the following additional code has no effect:

@App.path(model=Foo, path='start/extra')

You can still generate a link to a model that is under an absorbed path – it uses the value of the absorb variable.

Proxy support¶

If you have a Morepath application that sits behind a trusted proxy that sets the Forwarded header, then you want links generated by Morepath take this header into account. To do this, you can make your project depend on the more.forwarded extension. After you have it installed, you can subclass your app from more.forwarded.ForwardedApp to make your app proxy-aware. Note that you only need to do this for the root app, not for any apps mounted into it.

You should only use this extension if you know you are behind a trusted proxy that indeed sets the Forwarded header. This because otherwise you could expose your application to attacks that affect link generation through the Forwarded header.

Introduction¶

Morepath views are looked up through the URL path, but not through the routing procedure. Routing stops at models. Then the last segment of the path is taken to identify the view by name.

Named views¶

Let’s examine a path:

/documents/1/edit

If there’s a model like this:

@App.path(model=Document, path='/documents/{id}')
def get_document(id):
    return query_for_document(id)

then /edit identifies a view named edit on the Document model (or on one of its base classes). Here’s how we define it:

@App.view(model=Document, name='edit')
def document_edit(self, request):
    return "edit view on model: %s" % self.id

Default views¶

Let’s examine this path:

/documents/1

If the model is published on the path /documents/{id}, then this is a path to the default view of the model. Here’s how that view is defined:

@App.view(model=Document)
def document_default(self, request):
    return "default view on model: %s" % self.id

The default view is the view that gets triggered if there is no special path segment in the URL that indicates a specific view. The default view has as its name the empty string "", so this registration is the equivalent of the one above:

@App.view(model=Document, name="")
def document_default(self, request):
    return "default view on model: %s" % self.id

Generic views¶

Generic views in Morepath are nothing special: the thing that makes them generic is that their model is a base class, and inheritance does the rest. Let’s see how that works.

What if we want to have a view that works for any model that implements a certain API? Let’s imagine we have a Collection model:

class Collection(object):
   def __init__(self, offset, limit):
       self.offset = offset
       self.limit = limit

   def query(self):
       raise NotImplementedError

A Collection represents a collection of objects, which can be ordered somehow. We restrict the objects we actually get by offset and limit. With offset 100 and limit 10, we get objects 100 through 109.

Collection is a base class, so we don’t actually implement how to do a query. That’s up to the subclasses. We do specify that query is supposed to return objects that have an id attribute.

We can create a view to this abstract collection that displays the ids of the things in it in a comma separated list:

@App.view(model=Collection)
def collection_default(self, request):
    return ", ".join([str(item.id) for item in self.query()])

This view is generic: it works for any kind of collection.

We can now create a concrete collection that fulfills the requirements:

class Item(object):
   def __init__(self, id):
       self.id = id

class MyCollection(Collection):
   def query(self):
       return [Item(str(i)) for i in
               range(self.offset, self.offset + self.limit)

When we now publish the concrete MyCollection on some URL:

@App.path(model=MyCollection, path='my_collection')
def get_my_collection():
    return MyCollection()

it automatically gains a default view for it that represents the ids in it as a comma separated list. So the view collection_default is generic.

Details¶

The decorator morepath.App.view() (@App.view) takes two arguments here, model, which is the class of the model the view is representing, and name, which is the name of the view in the URL path.

The @App.view decorator decorates a function that takes two arguments: a self and a request.

The self object is the model that’s being viewed, i.e. the one found by the get_document function. It is going to be an instance of the class given by the model parameter.

The request object is an instance of morepath.Request, which in turn is a special kind of webob.request.BaseRequest. You can get request information from it like arguments or form data, and it also exposes a few special methods, such as morepath.Request.link().

The @App.path and @App.view decorators are associated by indirectly their model parameters: the view works for a given model path if the model parameter is the same, or if the view is associated with a base class of the model exposed by the @App.path decorator.

Ambiguity between path and view¶

Let’s examine these simple paths in an application:

/folder
/folder/{name}

/folder shows an overview of the items in it. /folder/{name} is a way to get to an individual item.

This means:

/folder/some_item

is a path if there is an item in the folder with the name some_item.

Now what if we also want to have a path that allows you to edit the folder? It’d be natural to spell it like this:

/folder/edit

i.e. there is a path /folder with a view edit.

But now we have a problem: how does Morepath know that edit is a view and not a named item in the folder? The answer is that it doesn’t. You cannot reach the view this way.

Instead we have to make it explicit in the path that we want a view with a + character:

/folder/+edit

Now Morepath won’t try to interpret +edit as a named item in the folder, but instead looks up the view.

Any view can be addressed not just by name but also by its name with a + prefix. To generate a link to a name with a + prefix you can use the prefix as well, so you can write:

request.link(my_folder, '+edit')

render¶

By default @App.view returns either a morepath.Response object or a string that gets turned into a response. The content-type of the response is not set. For a HTML response you want a view that sets the content-type to text/html. You can do this by passing a render parameter to the @App.view decorator:

@App.view(class=Document, render=morepath.render_html)
def document_default(self, request):
    return "<p>Some html</p>"

morepath.render_html() is a very simple function:

def render_html(content, request):
    response = morepath.Response(content)
    response.content_type = 'text/html'
    return response

You can define your own render functions; they just need to take some content (any object, in this case its a string), and return a Response object.

Another render function is morepath.render_json(). Here it is:

import json

def render_json(content, request):
    response = morepath.Response(json.dumps(content))
    response.content_type = 'application/json'
    return response

We’d use it like this:

@App.view(class=Document, render=morepath.render_json)
def document_default(self, request):
    return {'my': 'json'}

HTML views and JSON views are so common we have special shortcut decorators:

• @App.html (morepath.App.html())
• @App.json (morepath.App.json())

Here’s how you use them:

@App.html(class=Document)
def document_default(self, request):
    return "<p>Some html</p>"

@App.json(class=Document)
def document_default(self, request):
    return {'my': 'json'}

Templates¶

You can use a server template with a view by using the template argument:

@App.html(model=Document, template='document.pt')
def document_default(self, request):
    return { 'title': self.title, 'content': self.content }

See Templates for more information.

Permissions¶

We can protect a view using a permission. A permission is any Python class:

class Edit(object):
    pass

The class doesn’t do anything; it’s just a marker for permission.

You can use such a class with a view:

@App.view(model=Document, name='edit', permission=Edit)
def document_edit(self, request):
    return 'edit document'

You can define which users have what permission on which models by using the morepath.App.permission_rule() decorator. To learn more, read Security.

Manipulating the response¶

Sometimes you want to do things to the response specific to the view, so that you cannot do it in a render function. Let’s say you want to add a cookie using webob.Response.set_cookie(). You don’t have access to the response object in the view, as it has not been created yet. It is only created after the view has returned. We can register a callback function to be called after the view is done and the response is ready using the morepath.Request.after() decorator. Here’s how:

@App.view(model=Document)
def document_default(self, request):
    @request.after
    def manipulate_response(response):
        response.set_cookie('my_cookie', 'cookie_data')
    return "document default"

after only applies if the view was successfully resolved into a response. If your view raises an exception for any reason, or if Morepath itself does, any after set in the view does not apply to the response for this exception. If the view returns a response object directly itself, then after is also not run - you have the response object to manipulate directly. Note that this the case when you use morepath.redirect(): this returns a redirect response object.

request_method¶

By default, a view only answers to a GET request: it doesn’t handle other request methods like POST or PUT or DELETE. To write a view that handles another request method you need to be explicit and pass in the request_method parameter:

@App.view(model=Document, name='edit', request_method='POST')
def document_edit(self, request):
    return "edit view on model: %s" % self.id

Now we have a view that handles POST. Normally you cannot have multiple views for the same document with the same name: the Morepath configuration engine rejects that. But you can if you make sure they each have a different request method:

@App.view(model=Document, name='edit', request_method='GET')
def document_edit_get(self, request):
    return "get edit view on model: %s" % self.id

@App.view(model=Document, name='edit', request_method='POST')
def document_edit_post(self, request):
    return "post edit view on model: %s" % self.id

Grouping views¶

At some point you may have a lot of view decorators that share a lot of information; multiple views for the same model are the most common example.

Instead of writing this:

@App.view(model=Document)
def document_default(self, request):
    return "default"

@App.view(model=Document, name='edit')
def document_edit(self, request):
    return "edit"

You can use the with statement to write this instead:

with App.view(model=Document) as view:
   @view()
   def document_default(self, request):
       return "default"

   @view(name="edit")
   def document_edit(self, request):
       return "edit"

This is equivalent to the above, you just don’t have to repeat model=Document. You can use this for any parameter for @App.view.

This use of the with statement is in fact general; it can be used like this with any Morepath directive, and with any parameter for such a directive. The with statement may even be nested, though we recommend being careful with that, as it introduces a lot of indentation.

Predicates¶

The model, name, request_method and body_model arguments on the @App.view decorator are examples of view predicates. You can add new ones by using the morepath.App.predicate() decorator.

Let’s say we have a view that we only want to kick in when a certain request header is set to something:

import reg

@App.predicate(generic.view, name='something', default=None,
               index=reg.KeyIndex,
               after=morepath.LAST_VIEW_PREDICATE)
def something_predicate(request):
    return request.headers.get('Something')

We can use any information in the request and model to construct the predicate. Now you can use it to make a view that only kicks in when the Something` header is special:

@App.view(model=Document, something='special')
def document_default(self, request):
    return "Only if request header Something is set to special."

If you have a predicate and you don’t use it in a @App.view, or set it to None, the view works for the default value for that predicate. The default parameter is also used when rendering a view using morepath.Request.view() and you don’t pass in a particular value for that predicate.

Let’s look into the predicate directive in a bit more detail.

You can use either self or request as the argument for the predicate function. Morepath sees this argument and sends in either the object instance or the request.

We use reg.KeyIndex as the index for this predicate. You can also have predicate functions that return a Python class. In that case you should use reg.ClassIndex.

morepath.LAST_VIEW_PREDICATE is the last predicate defined by Morepath itself. Here we want to insert the something_predicate after this predicate in the predicate evaluation order.

The after parameter for the predicate determines which predicates match more strongly than another; a predicate after another one matches more weakly. If there are two view candidates that both match the predicates, the strongest match is picked.

request.view¶

It is often useful to be able to compose a view from other views. Let’s look at our earlier Collection example again. What if we wanted a generic view for our collection that included the views for its content? This is easiest demonstrated using a JSON view:

@App.json(model=Collection)
def collection_default(self, request):
    return [request.view(item) for item in self.query()]

Here we have a view that for all items returned by query includes its view in the resulting list. Since this view is generic, we cannot refer to a specific view function here; we just want to use the view function appropriate to whatever item may be. For this we can use morepath.Request.view().

We could for instance have a particular item with a view like this:

@App.json(model=ParticularItem)
def particular_item_default(self, request):
    return {'id': self.id}

And then the result of collection_default is something like:

[{'id': 1}, {'id': 2}]

but if we have a some other item with a view like this:

@App.json(model=SomeOtherItem)
def some_other_item_default(self, request):
    return self.name

where the name is some string like alpha or beta, then the output of collection_default is something like:

['alpha', 'beta']

So request.view can make it much easier to construct composed JSON results where JSON representations are only loosely coupled.

You can also use predicates in request.view. Here we get the view with the name "edit" and the request_method "POST":

request.view(item, name="edit", request_method="POST")

You can also create views that are for internal use only. You can use them with request.view() but they won’t show up to the web; going to such a view is a 404 error. You can do this by passing the internal flag to the directive:

@App.json(model=SomeOtherItem, name='extra', internal=True)
def some_other_item_extra(self, request):
    return self.name

The extra view can be used with request.view(item, name='extra'), but it is not available on the web – there is no /extra view.

Exception views¶

Sometimes your application raises an exception. This can either be a HTTP exception, for instance when the user goes to a URL that does not exist, or an arbitrary exception raised by the application.

HTTP exceptions are by default rendered in the standard WebOb way, which includes some text to describe Not Found, etc. Other exceptions are normally caught by the web server and result in a HTTP 500 error (internal server error).

You may instead want to customize what these exceptions look like. You can do so by declaring a view using the exception class as the model. Here’s how you make a custom 404 Not Found:

from webob.exc import HTTPNotFound

@App.view(model=HTTPNotFound)
def notfound_custom(self, request):
    def set_status_code(response):
        response.status_code = self.code # pass along 404
    request.after(set_status_code)
    return "My custom not found!"

We have to add the set_status_code to make sure the response is still a 404; otherwise we change the 404 to a 200 Ok! This shows that self is indeed an instance of HTTPNotFound and we can access its code attribute.

Your application may also define its own custom exceptions that have a meaning particular to the application. You can create custom views for those as well:

class MyException(Exception):
    pass

@App.view(model=MyException)
def myexception_default(self, request):
     return "My exception"

Without an exception view for MyException any view code that raises MyException would bubble all the way up to the WSGI server and a 500 Internal Server Error is generated.

But with the view for MyException in place, whenever MyException is raised you get the special view instead.

Introduction¶

When you generate HTML from the server (using HTML views) it can be very handy to have a template language available. A template language provides some high-level constructs for generating HTML, which are handy. It can also help you avoid HTML injection security bugs because it takes care of escaping HTML. It may also be useful to separate HTML presentation from code.

This document discusses template rendering on the server. In some modern web applications template rendering is done in the browser instead of on the server. To do client-side template rendering you need to use a Client web framework with Morepath. See also Static resources with Morepath.

Morepath does not have a template language built in. The example in this document uses more.chameleon. more.chameleon integrates the Chameleon template engine, which implements the ZPT template language. If you prefer Jinja2, you can use the more.jinja2 extension instead. You can also integrate other template languages.

To use a template you need to use the template argument with the morepath.App.html() view directive.

Example¶

This example presupposes that more.chameleon and its dependencies have been installed. Here is how we use it:

from more.chameleon import ChameleonApp

class App(ChameleonApp):
    pass

@App.template_directory()
def get_template_directory():
    return 'templates'

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

Let’s examine this code. First we import ChameleonApp and subclass from it in our own app. This enables Chameleon templating for the .pt file extension.

We then need to specify the directory that contains our templates using the morepath.App.template_directory() directive. The directive should return either an absolute or a relative path to this template directory. If a relative path is returned, it is automatically made relative to the directory the Python module is in.

Next we use template='person.pt' in the HTML view directive. person.pt is a file sitting in the templates directory, with this content:

<html>
<body>
  <p>Hello ${name}!</p>
</body>
</html>

Once we have this set up, given a person with a name attribute of "world", the output of the view is the following HTML:

<html>
<body>
  <p>Hello world!</p>
</body>
</html>

The template is applied on the return value of the view function and the request. This results in a rendered template that is returned as the response.

Overrides¶

When you subclass an app you may want to override some of the templates it uses, or add new templates. You can do this by using the template_directory directive in your subclassed app:

class SubApp(App):
    pass

@SubApp.template_directory()
def get_override_template_directory():
   return 'templates_override'

Morepath’s template integration searches for templates in the template directories in application order, so for SubApp here, first templates_override, and then templates as defined by the base App. So for SubApp, you can override a template defined in the directory templates by placing a file with the same name in the directory templates_override. This only affects SubApp, not App itself.

You can also use the before argument with the morepath.App.template_directory() directive to specify more exactly how you want template directories to be searched. This can be useful if you want to organize your templates in multiple directories in the same application. If get_override_template_directory should come before get_template_directory in the directory search path, you should use before=get_template_directory:

@SubApp.template_directory(before=get_template_directory)
def get_override_template_directory():
   return 'templates_override'

but it is usually simpler not to be this explicit and to rely on application inheritance instead.

Details¶

Templates are loaded during configuration time at startup. The file extension of the extension (such as .pt) indicates the template engine to use.

Morepath itself does not support any template language out of the box, but lets you register a template language engine for a file extension. You can reuse a template language integration in the same way you reuse any Morepath code: by subclassing the app class that implements it in your app.

The template language integration works like this:

• During startup time, person.pt is loaded from the configured template directories as a template object.
• When the person_default view is rendered, its return value is passed into the template, along with the request. The template language integration code then makes this information available for use by the template – the details are up to the integration (and should be documented there).

The template argument works not just with html but also with view, json, and any other view functions you may have. It’s most useful for html views however.

Integrating a new template engine¶

A template in Morepath is actually just a convenient way to generate a render function for a view. That render function is then used just like when you write it manually: it’s given the return value of the view function along with a request object, and should return a WebOb response.

Here is an example of how you can integrate the Chameleon template engine for .pt files (taken from more.chameleon):

import chameleon

@App.template_loader(extension='.pt')
def get_template_loader(template_directories, settings):
    settings = settings.chameleon.__dict__.copy()
    # we control the search_path entirely by what we pass here as
    # template_directories, so we never want the template itself
    # to prepend its own path
    settings['prepend_relative_search_path'] = False
    return chameleon.PageTemplateLoader(
        template_directories,
        default_extension='.pt',
        **settings)

@App.template_render(extension='.pt')
def get_chameleon_render(loader, name, original_render):
    template = loader.load(name)

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

@App.setting_section(section='chameleon')
def get_setting_section():
    return {'auto_reload': False}

Some details:

• extension is the file extension. When you refer to a template with a particular extension, this template engine is used.

• The function decorated by morepath.App.template_loader() gets two arguments: directories to look in for templates (earliest in the list first), and Morepath settings from which template engine settings can be extracted.

• The function decorated by morepath.App.template_render() gets three arguments:

  • loader: the loader constructed by the template_loader directive.
  • name: the name of the template to create a render function for.
  • The original_render function as passed into the view decorator, so render_html for instance. It takes the content to render and the request and returns a webob response object. then passed along to Chameleon.

  The decorated function needs to return a render function which takes the content to render (output from view function) and the request as arguments.

  The implementation of this can use the original render function which is passed in as an argument as original_render function. It can also create a morepath.Response object directly.

Introduction¶

Morepath lets you define a JSON representations for arbitrary Python objects. When you return such an object from a json view, the object is automatically converted to JSON. When JSON comes in as the POST or PUT body of the request, this JSON can be automatically converted to a Python object. This system allows you to write views in terms of Python objects instead of JSON.

dump_json¶

The morepath.App.dump_json() directive lets you define a function that turns a model of a particular class into JSON. Here we define it for an Item class:

class Item(object):
   def __init__(self, value):
       self.value = value

@App.dump_json(model=Item)
def dump_item_json(self, request):
    return { 'type': 'Item', 'x': self.value }

So for instance, Item('foo') is represented in JSON as:

{
  'type': 'Item',
  'x': 'foo'
}

If we omit the model argument from the directive, we define a general dump_json function that applies to all objects.

Now we can write a JSON view that just returns an Item instance:

@App.json(model=Item)
def item_default(self, request):
    return self

The self we return in this view is an istance of Item. This is now automatically converted to a JSON object.

load_json¶

The App.load_json() directive lets you define a function that turns incoming JSON into a Python object. We detect JSON with the type field Item and interpret it as an Item instance, and pass through everything else:

@App.load_json()
def load_json(json, request):
    if json.get('type') != 'Item':
        return json
    return Item(json['x'])

When you write a json view you automatically get the Item instance as the body_obj attribute of the request:

@App.json(model=Collection, request_method='POST')
def collection_post(self, request):
    collection.add(request.body_obj)
    return "success!"

Introduction¶

The security infrastructure in Morepath helps you make sure that web resources published by your application are only accessible by those persons that are allowed to do so. If a person is not allowed access, they will get an appropriate HTTP error: HTTP Forbidden 403.

Identity¶

Before we can determine who is allowed to do what, we need to be able to identify who people are in the first place.

The identity policy in Morepath takes a HTTP request and establishes a claimed identity for it. For basic authentication for instance it will extract the username and password. The claimed identity can be accessed by looking at the morepath.Request.identity attribute on the request object.

You use the morepath.App.identity_policy() directive to install an identity policy into a Morepath app:

from morepath.security import BasicAuthIdentityPolicy

@App.identity_policy()
def get_identity_policy():
    return BasicAuthIdentityPolicy()

If you want to create your own identity policy, see the morepath.security.IdentityPolicy API documentation to see what methods you need to implement.

Verify identity¶

The identity policy only establishes who someone is claimed to be. It doesn’t verify whether that person is actually who they say they are. For identity policies where the browser repeatedly sends the username/password combination to the server, such as with basic authentication and cookie-based authentication, we need to check each time whether the claimed identity is actually a real identity.

By default, Morepath will reject any claimed identities. To let your application verify identities, you need to use morepath.App.verify_identity():

@App.verify_identity()
def verify_identity(identity):
    return user_has_password(identity.username, identity.password)

The identity object received here is as established by the identity policy. What the attributes of the identity object are (besides username) is also determined by the specific identity policy you install.

Note that user_has_password stands in for whatever method you use to check a user’s password; it’s not part of Morepath.

Session or ticket identity verification¶

If you use an identity policy based on the session (which you’ve made secure otherwise), or on a cryptographic ticket based authentication system such as the one implemented by mod_auth_tkt, the claimed identity is actually enough.

We know that the claimed identity is actually the one given to the user earlier when they logged in. No database-based identity check is required to establish that this is a legitimate identity. You can therefore implement verify_identity like this:

@App.verify_identity()
def verify_identity(identity):
    # trust the identity established by the identity policy
    return True

Login and logout¶

So now we know how identity gets established, and how it can be verified. We haven’t discussed yet how a user actually logs in to establish an identity in the first place.

For this, we need two things:

• Some kind of login form. Could be taken care of by client-side code or by a server-side view. We leave this as an exercise for the reader.
• The view that the login data is submitted to when the user tries to log in.

How this works in detail is up to your application. What’s common to login systems is the action we take when the user logs in, and the action we take when the user logs in. When the user logs in we need to remember their identity on the response, and when the user logs in we need to forget their identity again.

Here is a sketch of how logging in works. Imagine we’re in a Morepath view where we’ve already retrieved username and password from the request (coming from a login form):

# check whether user has password, using password hash and database
if not user_has_password(username, password):
    return "Sorry, login failed" # or something more fancy

# now that we've established the user, remember it on the response
@request.after
def remember(response):
    identity = morepath.Identity(username)
    morepath.remember_identity(response, request, identity)

This is enough for session-based or cryptographic ticket-based authentication.

For cookie-based authentication where the password is sent as a cookie to the server for each request, we need to make sure include the password the user used to log in, so that remember can then place it in the cookie so that it can be sent back to the server:

@request.after
def remember(response):
    identity = morepath.Identity(username, password=password)
    morepath.remember_identity(response, request, identity)

When you construct the identity using morepath.security.Identity, you can any data you want in the identity object by using keyword parameters.

@request.after
def forget(response):
    morepath.forget_identity(response, request)

from webob.exc import HTTPForbidden

@App.view(model=HTTPForbidden)
def make_unauthorized(self, request):
    @request.after
    def set_status_code(response):
        response.status_code = 401
    return "Unauthorized"

# check whether user has password, using password hash and database
if not user_has_password(username, password):
    return "Sorry, login failed" # or something more fancy

Permissions¶

Now that we have a way to establish identity and a way for the user to log in, we can move on to permissions. Permissions are per view. You can define rules for your application that determine when a user has a permission.

Let’s say we want two permissions in our application, view and edit. We define those as plain Python classes:

class ViewPermission(object):
    pass

class EditPermission(object):
    pass

Now we can protect views with those permissions. Let’s say we have a Document model that we can view and edit:

@App.html(model=Document, permission=ViewPermission)
def document_view(request, model):
    return "<p>The title is: %s</p>" % model.title

@App.html(model=Document, name='edit', permission=EditPermission)
def document_edit(request, model):
    return "some kind of edit form"

This says:

• Only allow access to document_view if the identity has ViewPermission on the Document model.
• Only allow allow access to document_edit if the identity has EditPermission on the Document model.

Permission rules¶

Now that we give people a claimed identity and we have guarded our views with permissions, we need to establish who has what permissions where using some rules. We can use the morepath.App.permission_rule() directive to do that.

This is very flexible. Let’s look at some examples.

Let’s give absolutely everybody view permission on Document:

@App.permission_rule(model=Document, permission=ViewPermission)
def document_view_permission(identity, model, permission)
    return True

Let’s give only those users that are in a list allowed_users on the Document the edit permission:

@App.permission_rule(model=Document, permission=EditPermission)
def document_edit_permission(identity, model, permission):
    return identity.userid in model.allowed_users

This is just is one hypothetical rule. allowed_users on Document objects is totally made up and not part of Morepath. Your application can have any rule at all, using any data, to determine whether someone has a permission.

Morepath Super Powers Go!¶

What if we don’t want to have to define permissions on a per-model basis? In our application, we may have a generic way to check for the edit permission on any kind of model. We can easily do that too, as Morepath knows about inheritance:

@App.permission_rule(model=object, permission=EditPermission)
def has_edit_permission(identity, model, permission):
    ... some generic rule ...

This permission function is registered for model object, so will be valid for all models in our application.

What if we want that policy for all models, except Document where we want to do something else? We can do that too:

@App.permission_rule(model=Document, permission=EditPermission)
def document_edit_permission(identity, model, permission):
    ... some special rule ...

You can also register special rules that depend on identity. If you pass identity=None, you can can register a permission policy for when the user has not logged in yet and has no claimed identity:

@App.permission_rule(model=object, permission=EditPermission, identity=None)
def has_edit_permission_not_logged_in(identity, model, permission):
    return False

This permission check works in addition to the ones we specified above.

If you want to defer to a completely generic permission engine, you could define a permission check that works for any permission:

@App.permission_rule(model=object, permission=object)
def generic_permission_check(identity, model, permission):
     ... generic rule ...

Introduction¶

In this section we’ll look at how you could go about implementing a RESTful web service with Morepath.

REST stands for Representational State Transfer, and is a particular way to design web services. We won’t try to explain here why this can be a good thing for you to do, just explain what is involved.

REST is not only useful for pure web services, but is also highly relevant for web application development, especially when you are building a single-page rich client application in JavaScript in the web browser. It can be beneficial to organize the server-side application as a RESTful web service.

Elements of REST¶

That’s all rather abstract. Let’s get more concrete. It’s useful to refer to the Richardson Maturity Model for REST in this context. In REST we do the following:

• We uses HTTP as a transport system. What you use to communicate is typically JSON or XML, but it could be anything.
• We don’t just use HTTP to tunnel method calls to a single URL. Instead, we model our web service as resources, each with their own URL, that we can interact with.
• We use HTTP methods meaningfully. Most importantly we use GET to retrieve information, and POST when we want to change information. Along with this we also use HTTP response status codes meaningfully.
• We have links between the resources. So, one resource points to another. A container resource could point to a link that you can POST to create a new sub resource in it, for instance, and may have a list of links to the resources in the container. See also HATEOAS.

Morepath has features that help you create RESTful applications.

HTTP as a transport system¶

We don’t really need to say much here, as Morepath is of course all about HTTP in the end. Morepath lets you write a bare-bones view using morepath.App.view(). This also lets you pass in a render function that lets you specify how to render the return value of the view function as a morepath.Response. If you use JSON, for convenience you can use morepath.App.json() has a JSON render function baked in.

We could for instance have a Document model in our application:

class Document(object):
    def __init__(self, id, title, author, content):
        self.id = id
        self.title = title
        self.author = author
        self.content = content

We can expose it on a URL:

@App.path(model=Document, path='documents/{id}')
def get_document(id):
   return document_by_id(id)

We assume here that a document_by_id() function exists that returns a Document instance by id from some database, or None if the document cannot be found. Any way to get your model instance is fine.

Now we want a metadata resource that exposes its metadata as JSON:

@App.json(model=Document, name='metadata')
def document_metadata(self, request):
    return {
      'id': self.id,
      'title': self.title,
      'author': self.author
    }

Modeling as resources¶

Modeling a web service as multiple resources comes pretty naturally to Morepath, as it’s model-oriented in the first place. You can think carefully about how to place models in the URL space and expose them using morepath.App.path(). In Morepath each model class can only be exposed on a single URL (per app), which gives them a canonical URL automatically.

A collection resource could be modelled like this:

class DocumentCollection(object):
    def __init__(self):
        self.documents = []

    def add(self, doc):
        self.documents.append(doc)

We now want to expose this collection to a URL path /documents. We want:

• a resource /documents to GET the ids of all documents in the collection.
• a resource /documents/add that lets you POST an id to it so that this document is added to the collection.

Here is how we could make documents available on a URL:

documents = DocumentCollection()

@App.path(model=DocumentCollection, path='documents')
def documents_collection():
   return documents

When someone accesses /documents they should get a JSON structure which includes ids of all documents in the collection. Here’s how to do that:

@App.json(model=DocumentCollection)
def collection_default(self, request):
    return {
       'type': 'document_collection',
       'ids': [doc.id for doc in self.documents]
    }

Then we want to allow people to POST the document id (as a URL parameter) to the /documents/add resource:

@App.json(model=DocumentCollection, name='add', request_method='POST')
def collection_add_document(self, request):
    doc = document_by_id(request.args['id'])
    self.add(doc)
    return {}

We again use the document_by_id function. We also return an empty JSON object in the response; not very useful, but in this simple view we don’t have anything more interesting to report when the POST succeeds.

Note the use of request_method, which we’ll talk about more next.

Note also that there are some things still missing: giving back a proper response with status codes, and error handling when things go wrong.

HTTP methods¶

As you saw above, we’ve used request_method to make sure that /documents/add only works for POST requests.

By default, request_method is GET, meaning that /documents only responds to a GET request, which is what we want. Let’s make it explicit:

@App.json(model=DocumentCollection, request_method='GET')
def collection_default(self, request):
    ...

What if we had defined our web service differently, and instead of having a /documents/add we wanted to allow the POSTing of document ids on /documents directly? Here’s how you rewrite collection_add_document to be the view directly on /documents`:

@App.json(model=DocumentCollection, request_method='POST')
def collection_add_document(self, request):
    ...

It’s just a matter of removing the name parameter so that it becomes the default view on DocumentCollection.

HTTP response status codes¶

When a view did its thing with success, Morepath automatically returns the HTTP status code 200. When you try to access a URL that cannot be routed to a model or a view, a 404 error is raised.

But what if the view did not manage to do something successfully? Let’s get back to this view:

@App.json(model=DocumentCollection, name='add', request_method='POST')
def collection_add_document(self, request):
    doc = document_by_id(request.args['id'])
    self.add(doc)
    return {}

What if there is no id parameter in the request? That’s something our application cannot handle: a bad request, status code 400.

WebOb, the request/response library upon which Morepath is built, defines a set of HTTP exception classes webob.exc that we can use. In this case we need webob.exc.HTTPBadRequest. We modify our view so it is raised if there was no id:

from webob.exc import HTTPBadRequest

@App.json(model=DocumentCollection, name='add', request_method='POST')
def collection_add_document(self, request):
    id = request.args.get('id')
    if id is None:
        raise HTTPBadRequest()
    doc = document_by_id(id)
    self.add(doc)
    return {}

We also want to deal with the situation where an id was given, but no document with that id exists. Let’s handle that with 400 Bad Request too:

@App.json(model=DocumentCollection, name='add', request_method='POST')
def collection_add_document(self, request):
    id = request.args.get('id')
    if id is None:
        raise BadRequest()
    doc = document_by_id(id)
    if doc is None:
        raise BadRequest()
    self.add(doc)
    return {}

Linking: HATEOAS¶

We’ve now reached the point where many would say that this is a RESTful web service. But in fact a vital ingredient is still missing: hyperlinks. That ugly acronym HATEOAS thing.

Morepath makes it very easy to create hyperlinks, so we won’t have to do much. Let’s first modify our default GET view for the collection so it also has a link to the add resource:

@App.json(model=DocumentCollection)
def collection_default(self, request):
    return {
       'type': 'document_collection',
       'ids': [doc.id for doc in self.documents],
       'add': request.link(documents, 'add')
    }

documents, if you can remember, is the instance of DocumentCollection we were working with, and we want to link to its add view.

Let’s make things more interesting though. Before we had the default view for the collection return a list of document ids. We can change this so we return a list of document URLs instead:

@App.json(model=DocumentCollection)
def collection_default(self, request):
    return {
       'type': 'document_collection',
       'documents': [request.link(doc) for doc in self.documents],
       'add': request.link(documents, 'add')
    }

Or perhaps better, include the id and the URL:

@App.json(model=DocumentCollection)
def collection_default(self, request):
    return {
       'type': 'document_collection',
       'documents': [dict(id=doc.id, link=request.link(doc))
                     for doc in self.documents],
       'add': request.link(documents, 'add')
    }

Now we’ve got HATEOAS: the collection links to the documents it contains, and also to the add URL that can be used to add a new document. The developers looking at the responses your web service sends get a few clues about where to go next. Coupling is looser.

We got HATEOAS, so at last we got true REST. Why is hyperlinking so often ignored? Why don’t more systems implement HATEOAS? Perhaps because they make linking to things too hard or too brittle. Morepath instead makes it easy. Link away!

Compose from reusable apps¶

If you’re going to create a larger RESTful web service, you should start thinking about composing them from smaller applications. See App Reuse for more information.

Introduction¶

A typical application has some settings: if an application logs, a setting is the path to the log file. If an aplication sends email, there are settings to control how email is sent, such as the email address of the sender.

Applications that serve as frameworks for other applications may have settings as well: the transaction_app defined by more.transaction for instance has settings controlling transactional behavior.

Morepath has a powerful settings system that lets you define what settings are available in your application and framework. It allows an app that extends another app to override settings. This lets an app that defines a framework can also define default settings that can be overridden by the extending application if needed.

Defining a setting¶

You can define a setting using the App.setting() directive:

@App.setting(section="logging", name="logfile")
def get_logfile():
    return "/path/to/logfile.log"

You can also use this directive to override a setting in another app:

class Sub(App):
    pass

@Sub.setting(section="logging", name="logfile")
def get_logfile_too():
   return "/a/different/logfile.log"

Settings are grouped logically: a setting is in a section and has a name. This way you can organize all settings that deal with logging under the logging section.

Accessing a setting¶

During runtime, you can access the settings of the current application using the morepath.settings() function, like this:

settings().logging.logfile

In a tween factory (see :doc:tweens) or a directive implementation, you can access a setting through the app object like this:

app.registry.settings.logging.logfile

Defining multiple settings¶

It can be convenient to define multiple settings in a section at once. You can do this using the App.setting_section() directive:

@App.setting_section(section="logging")
def get_setting_section():
    return {
       'logfile': "/path/to/logfile.log",
       'loglevel': logging.WARNING
    }

You can mix setting and setting_section freely, but you cannot define a setting multiple times in the same app, as this will result in a configuration conflict.

Introduction¶

Morepath does not put any requirements on how your Python code is organized. You can organize your Python project as you see fit and put app classes, paths, views, etc, anywhere you like. A single Python package (or even module) may define a single Morepath app, but could also define multiple apps. In this Morepath is like Python itself; the Python language does not restrict you in how you organize functions and classes.

While this leaves you free to organize your code as you see fit, that doesn’t mean that your code shouldn’t be organized. Here are some guidelines on how you may want to organize things in your own project. But remember: these are guidelines to break when you see the need.

Python project¶

It is recommended you organize your code in a Python project with a setup.py where you declare the dependency on Morepath. If you’re unfamiliar with how this works, you can check out this tutorial.

Doing this is good Python practice and makes it easy for you to install and distribute your project using common tools like pip, buildout and PyPI. In addition Morepath itself can also load its code more easily.

Project layout¶

Here’s a quick overview of the files and directories of Morepath project that follows the guidelines in this document:

myproject
    setup.py
    myproject
         __init__.py
        main.py
        model.py
        [collection.py]
        path.py
        view.py

Project setup¶

Here is an example of your project’s setup.py with only those things relevant to Morepath shown and everything else cut out:

from setuptools import setup, find_packages

setup(name='myproject',
      packages=find_packages(),
      install_requires=[
         'morepath'
      ],
      entry_points={
         'console_scripts': [
          'myproject-start = myproject.main:main'
          ]
      })

This setup.py assumes you also have a myproject subdirectory in your project directory that is a Python package, i.e. it contains an __init__.py. This is the directory where you put your code. The find_packages() call finds it for you.

The install_requires section declares the dependency on Morepath. Doing this makes everybody who installs your project automatically also pull in a release of Morepath and its own dependencies. In addition, it lets this package be found and configured when you use morepath.autosetup().

Finally there is an entry_points section that declares a console script (something you can run on the command-prompt of your operating system). When you install this project, a myproject-start script is automatically generated that you can use to start up the web server. It calls the main() function in the myproject.main module. Let’s create this next.

You now need to install this project. If you want to install this project for development purposes you can use python setup.py develop, or pip install -e . from within a virtualenv.

See also the setuptools documentation.

Project naming¶

Its possible to name your project differently than you name your Python package; you could for instance have the name ThisProject in setup.py, and then have your Python package be still called myproject. We recommend naming the project the same as the Python package to avoid confusion.

Namespace packages¶

Sometimes you have projects that are grouped in some way: they are all created by the same organization or they are part of the same larger project. In that case you can use Python namespace packages to make this relationship clear. Let’s say you have a larger project called myproject. The namespace package itself may not contain any code, so unlike the example everywhere else in this document the myproject directory is always empty but for a __init__.py.

Different sub-projects could then be called myproject.core, myproject.wiki, etc. Let’s examine the files and directories of myproject.core:

myproject.core
    setup.py
    myproject
        __init__.py
        core
            __init__.py
            main.py
            model.py
            [collection.py]
            path.py
            view.py

The change is the namespace package directory myproject that contains a single file, __init__.py, that contains the following code to declare it is a namespace package:

__import__('pkg_resources').declare_namespace(__name__)