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.

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’)

Note 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.

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.

We create an instance of morepath.App. This is a WSGI
application that we can run. It also contains our application’s
configuration: what models and views are available.

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.AppBase.path() decorator.

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 "Helloworld!". 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.AppBase.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 /.

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.

func: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.

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
application 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:

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:

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:

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)

which generates the path /users/bob for us.

What if we want to see Bob’s edit view? We do this:

request.link(bob,'edit')

And we get /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.

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.