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.

argument_and_explicit_converters(arguments, converters)

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

converter_for_explicit_or_type(c)

Given a converter or a type, turn it into an explicit one.

converter_for_explicit_or_type_or_list(c)

Given a converter or type or list, turn it into an explicit one.

Parameters:c – can either be a converter, or a type for which a converter can be looked up, or a list with a converter or a type in it.
Returns:a Converter instance.
converter_for_type(type)

Get converter for type.

Is aware of inheritance; if nothing is registered for given type it returns the converter registered for its base class.

Parameters:type – The type for which to look up the converter.
Returns:a morepath.Converter instance.
converter_for_value(v)

Get converter for value.

Is aware of inheritance; if nothing is registered for type of given value it returns the converter registered for its base class.

Parameters:value – The value for which to look up the converter.
Returns:a morepath.Converter instance.
explicit_converters(converters)

Given converter dictionary, make everything in it explicit.

This means types have converters looked up for them, and lists are turned into ListConverter.

register_converter(type, converter)

Register a converter for type.

Parameters:
  • type – the Python type for which to register the converter.
  • converter – a morepath.Converter instance.
class morepath.directive.IdentityPolicyRegistry(reg_registry, setting_registry)

Register the current identity policy.

Used by the morepath.App.identity_policy directive.

Parameters:
register_identity_policy_function(factory, dispatch, name)

Register a method from the identity policy as a function.

The identity policy is registered as a class, but their methods are really registered with dispatch functions that are then exposed to the public API and are used in the framework.

Parameters:
  • factory – factory to create identity policy instance, typically the identity policy class object.
  • dispatch – the dispatch function we want to register a method on.
  • name – the name of the method to register.
class morepath.directive.PathRegistry(reg_registry, 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:

Register factory for app to defer class links to.

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

Parameters:
  • 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.

Parameters:
  • 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.

Parameters:
  • 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, app_factory)

Register a mounted app.

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

Parameters:
  • 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
  • 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, model_factory)

Register a route.

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

Parameters:
  • 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
  • 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.

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

A registry of what predicates are registered for which functions.

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

Parameters:reg_registry – the morepath.directive.RegRegistry in which the predicates are installed.
get_predicates(dispatch)

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_predicates()

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.

Parameters:
  • 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.

Parameters:
  • dispatch – the dispatch function to register fallback on.
  • func – the predicate function to register fallback for.
  • fallback_func – the fallback function.
sorted_predicate_infos(dispatch)

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

A reg.Registry with a cached lookup.

Morepath uses Reg to implement generic function lookups which are used for various aspects of configuration, in particular view lookup.

We cache the lookup using a reg.CachingKeyLookup so that generic function lookups are faster.

caching_lookup

Cached reg.Lookup

Property is reified with morepath.reify.reify() so cache is shared between morepath.App instances that use this registry.

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 as well as the morepath.settings() function.

register_setting(section_name, setting_name, func)

Register a setting.

Parameters:
  • 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.

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

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.

Parameters:
  • 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.

Parameters:
  • 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.

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

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).
sorted_tween_factories()

Sort tween factories topologically by over and under.

Returns:a sorted list of tween infos.
wrap(app)

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.
class morepath.directive.ViewRegistry(reg_registry, template_engine_registry)

A registry of views.

Parameters:
predicate_key(key_dict)

Given a dictionary create a unique predicate key.

See also reg.Registry.key_dict_to_predicate_key().

Parameters:key_dict – a dict containing view registration info, for instance model, request_method, etc.
Result:an immutable object representing the predicate.
register_view(key_dict, view, render=<function render_view>, template=None, permission=None, internal=False)

Register a view.

Parameters:
  • key_dict – a dict containing view registration info, for instance model, request_method, etc.
  • view – the view function as registered.
  • render_view – the render function to use to turn the view function result value into a response. By default the content is interpreted as a string body.
  • template – the template used to render the view function result value into a response. By default there is no template.
  • permission – the permission class used to check whether the identity is permitted to use the view on the model instance.
  • internal – whether this view is internal or not.

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/directive.py.

class morepath.directive.SettingAction

morepath.App.setting()

class morepath.directive.SettingSectionAction

morepath.App.setting_section()

class morepath.directive.PredicateFallbackAction

morepath.App.predicate_fallback()

class morepath.directive.PredicateAction

morepath.App.predicate()

class morepath.directive.FunctionAction

morepath.App.function()

class morepath.directive.ConverterAction

morepath.App.converter()

class morepath.directive.PathAction

Helps to implement morepath.App.path()

class morepath.directive.PathCompositeAction

morepath.App.path()

class morepath.directive.PermissionRuleAction

morepath.App.permission_rule()

class morepath.directive.TemplateDirectoryAction

morepath.App.template_directory()

class morepath.directive.TemplateLoaderAction

morepath.App.template_loader()

class morepath.directive.TemplateRenderAction

morepath.App.template_render()

class morepath.directive.ViewAction

morepath.App.view()

class morepath.directive.JsonAction

morepath.App.json()

class morepath.directive.HtmlAction

morepath.App.html()

class morepath.directive.MountAction

morepath.App.mount()

class morepath.directive.DeferLinksAction

morepath.App.defer_links()

class morepath.directive.DeferClassLinksAction

morepath.App.defer_class_links()

class morepath.directive.TweenFactoryAction

morepath.App.tween_factory()

class morepath.directive.IdentityPolicyFunctionAction

Helps to implement morepath.App.identity_policy()

class morepath.directive.IdentityPolicyAction

morepath.App.identity_policy()

class morepath.directive.VerifyIdentityAction

morepath.App.verify_identity()

class morepath.directive.DumpJsonAction

morepath.App.dump_json()

class morepath.directive.LoadJsonAction

morepath.App.load_json()

class morepath.directive.LinkPrefixAction

morepath.App.link_prefix()