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.
PathRegistry
(app_class, converter_registry)¶ A registry for routes.
Subclasses
morepath.traject.TrajectRegistry
.Used by
morepath.App.path()
andmorepath.App.mount()
directives to register routes. Also used by themorepath.App.defer_links()
andmorepath.App.defer_class_links()
directives.Parameters: converter_registry – a morepath.directive.ConverterRegistry
instance-
register_defer_class_links
(model, get_variables, app_factory)¶ 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_defer_links
(model, app_factory)¶ 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: - app –
morepath.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.
- app –
-
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
(app_class)¶ A registry of what predicates are registered for which functions.
It also keeps track of how predicates are to be ordered.
-
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.
SettingRegistry
¶ Registry of settings.
Used by the
morepath.App.setting
directive andmorepath.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.
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()
andmorepath.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_render –
render
function supplied with the view directive.
Returns: a
render
function that uses the template to render the result of a view function.- name – filename of the template (with extension, without path),
such as
-
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.
- extension – template extension like
-
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
- configurable –
dectate.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.
- extension – template extension like
-
sorted_template_directories
()¶ Get sorted template directories.
Use explicit
before
andafter
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 amorepath.Request
argument and returns amorepath.Response
(or awebob.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
(template_engine_registry, app_class)¶ A registry of views.
Parameters: template_engine_registry – a morepath.directive.TemplateEngineRegistry
used to render templated views.-
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
¶
-
class
morepath.directive.
SettingSectionAction
¶
-
class
morepath.directive.
PredicateFallbackAction
¶
-
class
morepath.directive.
PredicateAction
¶
-
class
morepath.directive.
FunctionAction
¶ morepath.App.function()
-
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.
LoadJsonAction
¶
-
class
morepath.directive.
LinkPrefixAction
¶