Morepath is a micro-framework, and this makes it small and easy to learn. This quickstart guide should help you get started. We assume you've already installed Morepath; if not, see the installation section.
Let's look at a minimal "Hello world!" application in Morepath:
code_examples/hello.py
You can save this as hello.py and then run it with Python:
$ python hello.py
Running <__main__.App object at 0x10f8398d0>
Listening on http://127.0.0.1:5000
Press Ctrl-C to stop...Making the server externally accessible
The default configuration of morepath.run uses the 127.0.0.1 hostname. This means you can access the web server from your own computer, but not from anywhere else. During development this is often the best way to go about things.
But sometimes do want to make the development server accessible from the outside world. This can be done by passing an explicit host argument of 0.0.0.0 to the morepath.run() function. :
morepath.run(App(), host='0.0.0.0')Alternatively, you can specify 0.0.0.0 on the command line:
$ python hello.py --host 0.0.0.0Note that the built-in web server is absolutely unsuitable for actual deployment. For those cases don't use morepath.run() at all, but instead use an external WSGI server such as waitress, Apache mod_wsgi or nginx mod_wsgi.
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.
Morepath uses port 5000 by default, and it might be the case that another service is already listening on that port. If that happens you can specify a different port on the command line:
$ python hello.py --port 6000This 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.
- We import
morepath. - We create a subclass of
morepath.AppnamedApp. This class contains our application's configuration: what models and views are available. It can also be instantiated into a WSGI application object. We then set up a
Rootclass. Morepath is model-driven and in order to create any views, we first need at least one model, in this case the emptyRootclass.We set up the model as the root of the website (the empty string
''indicates the root, but'/'works too) using themorepath.App.pathdecorator.Now we can create the "Hello world" view. It's just a function that takes
selfandrequestas arguments (we don't need to use either in this case), and returns the string"Hello world!". Theselfargument is the instance of themodelclass that is being viewed.We then need to hook up this view with the
morepath.App.viewdecorator. We say it's associated with theRootmodel. Since we supply no explicitnameto the decorator, the function is the default view for theRootmodel on/.- The
if __name__ == '__main__'section is a way in Python to make the code only run if thehello.pymodule 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. - We then instantiate the
Appclass to create aWSGIapp 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.
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.
Why route to models?
Why does Morepath route to models? It allows for some nice features. The most concrete feature is automatic hyperlink generation - we'll go into more detail about this later.
A more abstract feature is that Morepath through model-driven design allows for greater code reuse: this is the basis for Morepath's super-powers. We'll show a few of these special things you can do with Morepath later.
Finally Morepath's model-oriented nature makes it a more natural fit for REST applications. This is useful when you need to create a web service or the foundation to a rich client-side application.
A model is any Python object that represents the content of your application: say a document, or a user, an address, and so on. A model may be a plain in-memory Python object or be backed by a database using an ORM such as SQLAlchemy, or some NoSQL database such as the ZODB. This is entirely up to you; Morepath does not put special requirements on models.
Above we've exposed a Root model to the root route /, which is rather boring. To make things more interesting, let's imagine we have an application to manage users. Here's our User class:
- class User(object):
- def __init__(self, username, fullname, email):
self.username = username self.fullname = fullname self.email = email
We also create a simple users database:
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)
import morepath class App(morepath.App): pass
Custom variables function
The default behavior is for Morepath to retrieve the variables by name using getattr from the model objects. This only works if those variables exist on the model under that name. If not, you can supply a custom variables function that given the model returns a dictionary with all the variables in it. Here's how:
@App.path(model=User, path='/users/{username}',
variables=lambda model: dict(username=model.username))
def get_user(username):
return users.get(username)Of course this variables is not necessary as it has the same behavior as the default, but you can do whatever you want in the variables function in order to get the username.
Getting variables right is important for link generation.
We want our application to have URLs that look like this:
/users/faassen
/users/bobHere's the code to expose our users database to such a URL:
@App.path(model=User, path='/users/{username}') def get_user(username): return users.get(username)
The get_user function gets a user model from the users database by using the dictionary get method. If the user doesn't exist, it returns None. We could've fitted a SQLAlchemy query in here instead.
Now let's look at the decorator. The model argument has the class of the model that we're putting on the web. The path argument has the URL path under which it should appear.
The path can have variables in it which are between curly braces ({ and }). These variables become arguments to the function being decorated. Any arguments the function has that are not in the path are interpreted as URL parameters.
What if the user doesn't exist? We want the end-user to see a 404 error. Morepath does this automatically for you when you return None for a model, which is what get_user does when the model cannot be found.
Now we've published the model to the web but we can't view it yet.
converters
A common use case is for path variables to be a database id. These are often integers only. If a non-integer is seen in the path we know it doesn't match. You can specify a path variable contains an integer using the integer converter. For instance:
@App.path(model=Post, path='posts/{post_id}', converters=dict(post_id=int))
def get_post(post_id):
return query_post(post_id)You can do this more succinctly too by using a default parameter for post_id that is an int, for instance:
@App.path(model=Post, path='posts/{post_id}')
def get_post(post_id=0):
return query_post(post_id)For more on this, see paths_and_linking.
In order to actually see a web page for a user model, we need to create a view for it:
@App.view(model=User) def user_info(self, request): return "User's full name is: %s" % self.fullname
The view is a function decorated by morepath.App.view (or related decorators such as morepath.App.json and morepath.App.html) that gets two arguments: self, which is the model that this view is working for, so in this case an instance of User, and request which is the current request. request is a morepath.request.Request object (a subclass of webob.request.BaseRequest).
Now the URLs listed above such as /users/faassen will work.
What if we want to provide an alternative view for the user, such as an edit view which allows us to edit it? We need to give it a name:
@App.view(model=User, name='edit') def edit_user(self, request): return "An editing UI goes here"
Now we have functionality on URLs like /users/faassen/edit and /users/bob/edit.
For more on this, see views.
request = App().request({'PATH_INFO': '/', 'wsgi.url_scheme': 'http', 'HTTP_HOST': 'example.com'})
Morepath is great at creating links to models: it can do it for you automatically. Previously we've defined an instance of User called bob. What now if we want to link to the default view of bob? We simply do this:
>>> request.link(bob) 'http://example.com/users/bob'
What if we want to see Bob's edit view? We do this:
>>> request.link(bob, 'edit') 'http://example.com/users/bob/edit'
Using morepath.Request.link everywhere for link generation is easy. You only need models and remember which view names are available, that's it. If you ever have to change the path of your model, you won't need to adjust any linking code.
For more on this, see paths_and_linking.
Link generation compared
If you're familiar with routing frameworks where links are generated to views (such as Flask or Django) link generation is more involved. You need to give each route a name, and then refer back to this route name when you want to generate a link. You also need to supply the variables that go into the route. With Morepath, you don't need a route name, and if the default way of getting variables from a model is not correct, you only need to explain once how to create the variables for a route, with the variables argument to @App.path.
In addition, Morepath links are completely generic: you can pass in anything linkable. This means that writing a generic view that uses links becomes easier -- there is no dependency on particular named URL paths anymore.
@App.view is rather bare-bones. You usually know more about what you want to return than that. If you want to return JSON, you can use the shortcut @App.json instead to declare your view:
@App.json(model=User, name='info')
def user_json_info(self, request):
return {'username': self.username,
'fullname': self.fullname,
'email': self.email}This automatically serializes what is returned from the function JSON, and sets the content-type header to application/json.
If we want to return HTML, we can use @App.html:
@App.html(model=User)
def user_info(self, request):
return "<p>User's full name is: %s</p>" % self.fullnameThis automatically sets the content type to text/html. It doesn't do any HTML escaping though, so the use of % above is unsafe! We recommend the use of a HTML template language in that case.
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.GETcontains any URL parameters (?key=value). Seewebob.request.BaseRequest.GET.request.POSTcontains any HTTP form data that was submitted. Seewebob.request.BaseRequest.POST.request.methodgets the HTTP method (GET,POST, etc). Seewebob.request.BaseRequest.method.request.cookiescontains the cookies. Seewebob.request.BaseRequest.cookies.response.set_cookiecan be used to set cookies. Seewebob.response.Response.set_cookie.
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'))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.