morepath.directive – Extension API

This module contains the extension API for Morepath. It is useful when you want to define new directives in a Morepath extension. An example an extension that does this is more.static.

If you just use Morepath you should not have to import from morepath.directive in your code. Instead you use the directives defined in here through morepath.App.

Morepath uses the Dectate library to implement its directives. The directives are installed on morepath.App using the dectate.App.directive() decorator.

We won’t repeat the directive documentation here. If you are interested in creating a custom directive in a Morepath extension it pays off to look at the source code of this module. If your custom directive needs to interact with a core directive you can inherit from them, and/or refer to them with group_class.

When configuration is committed it is written into various configuration registries which are attached to the dectate.App.config class attribute. If you implement your own directive dectate.Action that declares one of these registries in dectate.Action.config you can import their class from morepath.directive.

Registry classes

class morepath.directive.ConverterRegistry

A registry for converters.

Used to decode/encode URL parameters and path variables used by the morepath.App.path() directive.

Is aware of inheritance.


Return an actual converter for a given spec.

Parameters:spec – if a type, return the registered converter for that; if a list use its first element as a spec for a converter; else, assume it is a converter and return it.
Returns:a morepath.Converter instance.
argument_and_explicit_converters(arguments, converters)

Use explict converters unless none supplied, then use default args.

register_converter(type, converter)

Register a converter for type.

  • type – the Python type for which to register the converter.
  • converter – a morepath.Converter instance.
class morepath.directive.PathRegistry(app_class, converter_registry)

A registry for routes.

Subclasses morepath.traject.TrajectRegistry.

Used by morepath.App.path() and morepath.App.mount() directives to register routes. Also used by the morepath.App.defer_links() and morepath.App.defer_class_links() directives.

Parameters:converter_registry – a morepath.directive.ConverterRegistry instance

Register factory for app to defer class links to.

See morepath.App.defer_class_links() for more information.

  • model – model class to defer links for.
  • get_variables – get variables dict for obj.
  • app_factory – function that model class, app instance and variables dict as arguments and should return another app instance that does the link generation.

Register factory for app to defer links to.

See morepath.App.defer_links() for more information.

  • model – model class to defer links for.
  • app_factory – function that takes app instance and model object as arguments and should return another app instance that does the link generation.
register_inverse_path(model, path, factory_args, converters=None, absorb=False)

Register information for link generation.

  • model – model class
  • path – the route
  • factory_args – a list of the arguments of the factory function for this path.
  • converters – a converters dict.
  • absorb – bool, if true this is an absorbing path.
register_mount(app, path, variables, converters, required, get_converters, mount_name, code_info, app_factory)

Register a mounted app.

See morepath.App.mount() for more information.

  • appmorepath.App subclass.
  • path – route
  • variables – function that given model instance extracts dictionary with variables used in path and URL parameters.
  • converters – converters structure
  • required – required URL parameters
  • get_converters – get a converter dynamically.
  • mount_name – explicit name of this mount
  • code_info – a dectate.CodeInfo instance used to register this directive.
  • app_factory – function that constructs app instance given variables extracted from path and URL parameters.
register_path(model, path, variables, converters, required, get_converters, absorb, code_info, model_factory)

Register a route.

See morepath.App.path() for more information.

  • model – model class
  • path – route
  • variables – function that given model instance extracts dictionary with variables used in path and URL parameters.
  • converters – converters structure
  • required – required URL parameters
  • get_converters – get a converter dynamically.
  • absorb – absorb path
  • code_info – the dectate.CodeInfo object describing the line of code used to register the path.
  • model_factory – function that constructs model object given variables extracted from path and URL parameters.
register_path_variables(model, func)

Register variables function for a model class.

  • model – model class
  • func – function that gets a model instance argument and returns a variables dict.
class morepath.directive.PredicateRegistry(app_class)

A registry of what predicates are registered for which functions.

It also keeps track of how predicates are to be ordered.


Create Reg predicates.

This creates reg.Predicate objects for a particular dispatch function.

Uses PredicateRegistry.sorted_predicate_infos() to sort the predicate infos.

Parameters:dispatch – the dispatch function to create the predicates for.
Returns:a list of reg.Predicate instances in the correct order.

Install the predicates with reg.

This should be called during configuration once all predicates and fallbacks are known. Uses PredicateRegistry.get_predicates() to get out the predicates in the correct order.

register_predicate(func, dispatch, name, default, index, before, after)

Register a predicate for installation into the reg registry.

See morepath.App.predicate() for details.

  • func – the function that implements the predicate.
  • dispatch – the dispatch function to register the predicate on.
  • name – name of the predicate.
  • default – default value.
  • index – index to use.
  • before – predicate function to have priority over.
  • after – predicate function that has priority over this one.
register_predicate_fallback(dispatch, func, fallback_func)

Register a predicate fallback for installation into reg registry.

See morepath.App.predicate_fallback() for details.

  • dispatch – the dispatch function to register fallback on.
  • func – the predicate function to register fallback for.
  • fallback_func – the fallback function.

Topologically sort predicate infos for a dispatch function.

Parameters:dispatch – the dispatch function to sort for.
Returns:a list of sorted PredicateInfo instances.
class morepath.directive.SettingRegistry

Registry of settings.

Used by the morepath.App.setting directive and morepath.App.setting_section directives.

Stores sections as attributes, which then have the settings as attributes.

This settings registry is exposed through morepath.App.settings.

register_setting(section_name, setting_name, func)

Register a setting.

  • section_name – name of section to register in
  • setting_name – name of setting
  • func – function that when called without arguments creates the setting value.
class morepath.directive.TemplateEngineRegistry(setting_registry)

A registry of template engines.

Is used by the morepath.App.view(), morepath.App.json() and morepath.App.html() directives for template-based rendering.

Parameters:setting_registry – a morepath.directive.SettingRegistry instance.
get_template_render(name, original_render)

Get a template render function.

  • name – filename of the template (with extension, without path), such as
  • original_renderrender function supplied with the view directive.

a render function that uses the template to render the result of a view function.

initialize_template_loader(extension, func)

Initialize a template loader for an extension.

Used by the morepath.App.template_loader() directive.

  • extension – template extension like .p.t
  • func – function that given a list of template directories returns a load object that be used to load the template for use.
register_template_directory_info(key, directory, before, after, configurable)

Register a directory to look for templates.

Used by the morepath.App.template_directory() directive.

  • key – unique key identifying this directory
  • directory – absolute path to template directory
  • before – key to before in template lookup
  • after – key to sort after in template lookup
  • configurabledectate.Configurable used that registered this template directory. Used for implicit sorting by app inheritance.
register_template_render(extension, func)

Register way to get a view render function for a file extension.

Used by the morepath.App.template_render() directive. See there for more information about parameters.

  • extension – template extension like .pt
  • func – function that given loader, name and original_renderer constructs a view render function.

Get sorted template directories.

Use explicit before and after information but also App inheritance to sort template directories in order of template lookup.

Returns:a list of template directory paths in the right order
class morepath.directive.TweenRegistry

Registry for tweens.

register_tween_factory(tween_factory, over, under)

Register a tween factory.

Parameters:tween_factory – a function that constructs a tween given a morepath.App instance and a function that takes a morepath.Request argument and returns a morepath.Response (or a webob.response.Response).
Over:this tween factory wraps the tween created by the over factory (possibly indirectly).
Under:the under factory wraps the tween created by this one (possibly indirectly).

Sort tween factories topologically by over and under.

Returns:a sorted list of tween infos.

Wrap app with tweens.

This wraps morepath.publish.publish() with tweens.

Parameters:app – an instance of morepath.App.
Returns:the application wrapped with tweens. This is a function that takes request and returns a a response.

Action classes

To instantiate an action you need to give it the same arguments as the directive it implements. Reading the source of existing actions is helpful when you want to implement your own actions. See morepath/

class morepath.directive.SettingAction


class morepath.directive.SettingSectionAction


class morepath.directive.PredicateFallbackAction


class morepath.directive.PredicateAction


class morepath.directive.FunctionAction


class morepath.directive.ConverterAction


class morepath.directive.PathAction

Helps to implement morepath.App.path()

class morepath.directive.PathCompositeAction


class morepath.directive.PermissionRuleAction


class morepath.directive.TemplateDirectoryAction


class morepath.directive.TemplateLoaderAction


class morepath.directive.TemplateRenderAction


class morepath.directive.ViewAction


class morepath.directive.JsonAction


class morepath.directive.HtmlAction


class morepath.directive.MountAction


class morepath.directive.DeferLinksAction


class morepath.directive.DeferClassLinksAction


class morepath.directive.TweenFactoryAction


class morepath.directive.IdentityPolicyFunctionAction

Helps to implement morepath.App.identity_policy()

class morepath.directive.IdentityPolicyAction


class morepath.directive.VerifyIdentityAction


class morepath.directive.DumpJsonAction


class morepath.directive.LinkPrefixAction