API Reference

pyramid_layout.config

pyramid_layout.config.add_layout(config, layout=None, template=None, name='', context=None, containment=None)

Add a layout configuration to the current configuration state.

Arguments

layout

A layout class or dotted Python name which refers to a layout class. This argument is not required. If the layout argument is not provided, a default layout class is used which merely has context and request as instance attributes.

template

A string implying a path or an asset specification for a template file. The file referred to by this argument must have a suffix that maps to a known renderer. This template will be available to other templates as the renderer global main_template. This argument is required.

name

The layout name.

context

An object or a dotted Python name referring to an interface or class object that the context must be an instance of, or the interface that the context must provide in order for this layout to be found and used. This predicate is true when the context is an instance of the represented class or if the context provides the represented interface; it is otherwise false.

containment

This value should be a Python class or interface (or a dotted Python name) that an object in the lineage of the context must provide in order for this view to be found and called. The nodes in your object graph must be “location-aware” to use this feature.
pyramid_layout.config.add_panel(config, panel=None, name='', context=None, renderer=None, attr=None)

Add a panel configuration to the current configuration state.

Arguments

panel

A panel callable or a dotted Python name which refers to a panel callable. This argument is required unless a renderer argument also exists. If a renderer argument is passed, and a panel argument is not provided, the panel callable defaults to a callable that returns an empty dictionary.

attr

The panel machinery defaults to using the __call__ method of the panel callable (or the function itself, if the panel callable is a function) to obtain a response. The attr value allows you to vary the method attribute used to obtain the response. For example, if your panel was a class, and the class has a method named index and you wanted to use this method instead of the class’ __call__ method to return the response, you’d say attr="index" in the panel configuration for the panel. This is most useful when the panel definition is a class.

renderer

This is either a single string term (e.g. json) or a string implying a path or asset specification (e.g. templates/panels.pt) naming a renderer implementation. If the renderer value does not contain a dot ., the specified string will be used to look up a renderer implementation, and that renderer implementation will be used to construct a response from the panel return value. If the renderer value contains a dot (.), the specified term will be treated as a path, and the filename extension of the last element in the path will be used to look up the renderer implementation, which will be passed the full path. The renderer implementation will be used to construct a response from the panel return value.

Note that if the panel itself returns an instance of basestring (or just str in Python 3), the specified renderer implementation is never called.

When the renderer is a path, although a path is usually just a simple relative pathname (e.g. templates/foo.pt, implying that a template named “foo.pt” is in the “templates” directory relative to the directory of the current package of the Configurator), a path can be absolute, starting with a slash on UNIX or a drive letter prefix on Windows. The path can alternately be an asset specification in the form some.dotted.package_name:relative/path, making it possible to address template assets which live in a separate package.

The renderer attribute is optional. If it is not defined, the “null” renderer is assumed (no rendering is performed and the value is passed back to the upstream Pyramid machinery unmodified).

name

The optional panel name, which defaults to an empty string.

context

An object or a dotted Python name referring to an interface or class object that the context must be an instance of, or the interface that the context must provide in order for this panel to be found and called. This predicate is true when the context is an instance of the represented class or if the context provides the represented interface; it is otherwise false.

pyramid_layout.layout

class pyramid_layout.layout.LayoutManager(context, request)

An instance of LayoutManager will be available as the layout_manager attribute of the request object in views and allows the view to access or change the current layout.

layout

Property which gets the current layout.

render_panel(name='', *args, **kw)

Renders the named panel, returning a unicode object that is the rendered HTML for the panel. The panel is looked up using the current context (or the context given as keyword argument, to override the context in which the panel is called) and an optional given name (which defaults to an empty string). The panel is called passing in the current context, request and any additional parameters passed into the render_panel call. In case a panel isn’t found, None is returned.

use_layout(name)

Makes a layout with the given name the current layout. By default an unnamed layout which matches the current context and containment will be the current layout. By specifying a named layout using LayoutManager.use_layout(), a named view matching the current context, containment, and given name will be used.

pyramid_layout.layout.layout_config(name='', context=None, template=None, containment=None)

A class decorator which allows a developer to create layout registrations.

For example, this code in a module layout.py:

@layout_config(name='my_layout', template='mypackage:templates/layout.pt')
class MyLayout(object):

    def __init__(self, context, request):
        self.context = context
        self.request = request

The following arguments are supported as arguments to pyramid_layout.layout.layout_config: context, name, template, containment.

The meanings of these arguments are the same as the arguments passed to pyramid_layout.config.add_layout().

pyramid_layout.panel

pyramid_layout.panel.panel_config(name='', context=None, renderer=None, attr=None)

A function, class or method decorator which allows a developer to create panel registrations.

For example, this code in a module panels.py:

from resources import MyResource

@panel_config(name='my_panel', context=MyResource):
def my_panel(context, request):
    return 'OK'

The following arguments are supported as arguments to pyramid_layout.panel.panel_config: context, name, renderer, attr.

The meanings of these arguments are the same as the arguments passed to pyramid_layout.config.add_panel().