API reference

Content model and container components

class grok.Application

Mixin for creating Grok application objects.

When a grokcore.content.Container (or a grokcore.content.Model, though most developers use containers) also inherits from grokcore.site.Application, it not only gains the component registration abilities of a grokcore.site.site, but will also be listed in the Grok admin control panel as one of the applications that the admin can install directly at the root of their Zope database.

class grok.Container

The base class for containers in Grok applications.

When an application class inherits from grok.Container, it not only has the features of a grok.Model (persistance, location, and the ability to serve as a default context for other classes), but it also behaves like a persistent dictionary. To store items inside a container, simply use the standard Python getitem/setitem protocol:

mycontainer['counter'] = 72
mycontainer['address'] = mymodel
mycontainer['subfolder'] = another_container

By default, the URL of each item inside a container is the container’s own URL followed by a slash and the key (like ‘counter’ or ‘address’) under which that item has been stored.

class grok.Model

The base class for models in Grok applications.

When an application class inherits from grok.Model, it gains the ability to persist itself in the Zope object database along with all of its attributes, and to remember the container in which it has been placed (its “parent”) so that its URL can be computed. It also inherits the IContext marker interface, which can make it the default context for views in its module; the rule is that if a module contains grok.View classes or other adapters that do not define a grok.context(), but the module also defines exactly one class that provides the IContext interface, then that class will automatically be made the grok.context() of each of the views.

class grok.OrderedContainer

A Grok container that remembers the order of its items.

This straightforward extension of the basic grok.Container remembers the order in which items have been inserted, so that keys(), values(), items(), and iteration across the container can all return the items in the order they were inserted. The only way of changing the order is to call the updateOrder() method.

class grok.Site

Mixin for creating sites in Grok applications.

When an application grok.Model or grok.Container also inherits from grokcore.site.Site, then it can additionally support the registration of local Component Architecture entities like grokcore.site.LocalUtility and grok.Indexes objects; see those classes for more information.

grok.getApplication()

Return the nearest enclosing grokcore.site.Application.

Raises ValueError if no application can be found.

grok.getSite()

View components

class grok.DirectoryResource(context, request)

class grok.layer(*args, **kw)

class grok.PageTemplate(string=None, filename=None, _prefix=None)

class grok.PageTemplateFile(filename, _prefix=None)

class grok.path(*args, **kw)

class grok.skin(*args, **kw)

class grok.template(*args, **kw)

class grok.view(*args, **kw)

class grok.View(context, request)

The base class for views with templates in Grok applications.

Implements the grokcore.view.interfaces.IGrokView interface.

Each class that inherits from grok.View is designed to “render” a category of content objects by reducing them to a document (often an HTML document). Every view has a name, and is invoked when users visit the URL of an eligible context object followed by the name of the view itself:

http://example.com/app/folder/object/viewname

If the view name might conflict with actual content inside of the context (in the above URL, the context might already contain an attribute or item named viewname), then the URL can be explicit that it is asking for a view by preceding its name with @@:

http://example.com/app/folder/object/@@viewname

Instead of returning a full document, views are sometimes used to provide only a snippet of information for inclusion in some larger document; the view can then be called from inside of another view’s page template:

<li tal:content="context/@@viewname">snippet goes here</li>

A view class can specify the category of objects that it can render by calling the grok.context() directive with either a class or an interface. Otherwise, Grok will attempt to determine the context automatically by searching the view’s module for exactly one grok.Model or grok.Container class (or some other class providing the interface IContext) and using that class, if found.

Grok normally creates a view’s name (the name used in URLs) by downcasing the name of the view class itself. The developer can override this by supplying the grok.name() directive instead.

The view name index is special (this works whether the view class itself is named Index, or whether grok.name('index') is used instead). A view named index is used to render an object when the user visits its URL without appending a view name.

Each view needs to generate and return a document. There are two ways of doing so: either the view can provide a render() method that returns a document, or the view can be associated with a page template that Grok will. Page templates can be associated with a view in three different ways:

• Grok will automatically associate a view with a page template defined in an accompanying templates directory. If a view class MammothList occurs in a module <src>/animal.py, for example, then Grok will look for a page template with the name <src>/animal_templates/mammothlist.pt, where .pt can be any page-template extension recognized by Grok.

• Grok will automatically associate a view with a page template object in the same module whose name is the downcased name of the view class itself. For example, a view MammothList might be defined in a module alongside an actual template instance named mammothlist.

• The developer can explicitly define the path to the page template file by providing the grok.template() directive.

Before a page template is rendered, Grok will call the update() method on the view, if one is supplied, which can pre-compute values that the template will need to display. Both render() methods and update() methods will find the context for which the view is being rendered under self.context.

class grok.Viewlet(context, request, view, manager)

Batteries included viewlet.

class grok.viewletmanager(*args, **kw)

class grok.ViewletManager(context, request, view)

grok.url(request, obj, name=None, skin=<object object>, data=None)

Forms

class grok.action(label, actions=None, **options)

We override the action decorator we pass in our custom Action.

class grok.AddForm(context, request)

Base class for add forms in Grok applications.

class grok.DisplayForm(context, request)

Base class for display forms in Grok applications.

class grok.EditForm(context, request)

Base class for edit forms in Grok applications.

class grok.Form(context, request)

The base class for forms in Grok applications.

A class that inherits from grok.Form is a grok.View whose template will be given information about the fields in its context, and use that information to render an HTML form for adding or editing the form. Generally developers use one of the subclasses:

• grok.AddForm

• grok.DisplayForm

• grok.EditForm

grok.AutoFields(context)

Get the form fields for context.

grok.Fields(*args, **kw)

Utilities, Adapters, Subscriptions

class grok.adapter(*interfaces, **kw)

Registers the function as an adapter for the specific interface.

The name argument must be a keyword argument and is optional. If given, a named adapter is registered.

class grok.Adapter(context)

Base class for an adapter that adapts a single object (commonly referred to as the context).

Use the context directive to specify which object to adapt and the implements directive to specify which interface the adapter will provide. If it’s a named adapter, you may use the name directive to specify the name.

context

The adapted object.

class grok.Annotation

The base class for annotation classes in Grok applications.

Inherits from the persistent.Persistent class.

class grok.global_utility(*args, **kw)

Registers an instance of class (or class itself, depending on the value of the direct parameter) as a global utility.

This allows you to register global utilities that don’t inherit from the GlobalUtility base class.

Parameters:

• class – The class to register as a global utility.

• provides – Optionally, the interface the utility will provide.

• name (string or unicode) – Optionally, a name for a named utility registration.

• direct (boolean) – Optionally, a flag indicating the class directly provides the interfaces, and it needs not to be instantiated.

class grok.GlobalUtility

Base class to define a globally registered utility.

Base class for a globally registered utility. Unless you use the direct directive to indicate that the class itself should be registered as a utility, the class will automatically be instantiated, therefore the constructor may not take any arguments. Use the implements directive to specify which interface the utility provides, or if that is not unambiguous, also use the provides directive to specify which of the implemented interfaces should be used when registering the utility. If it’s a named utility, you may use the name directive to specify the name.

class grok.implementer(*interfaces)

Declares that the function implements a certain interface (or a number of interfaces).

This is useful when a function serves as an object factory, e.g. as an adapter.

class grok.local_utility(*args, **kw)

The grokcore.site.local_utility() directive.

Place this directive inside of a grokcore.site.Site subclass, and provide the name of a utility you want activated inside of that site:

class MySite(grokcore.site.Site):
    grok.local_utility(MyMammothUtility)
    ...

This directive can be supplied several times within the same site. Thanks to the presence of this directive, any time an instance of your class is created in the Zope database it will have a copy of the given local utility installed along with it.

This directive accepts several normal Component-registration keyword arguments, like provides and name, and uses them each time it registers your local utility.

If you do not supply a provides keyword, then Grok attempts to guess a sensible default. Its first choice is to use any interface(s) that you listed with the grok.provides() directive when defining your utility. Otherwise, if your utility is a subclass of grokcore.site.LocalUtility, then Grok will use any interfaces that your utility supplies beyond those are supplied because of its inheritance from grokcore.site.LocalUtility. Else, as a final fallback, it checks to see whether the class you are registering supplies one, and only one, interface; if so, then it can register the utility unambiguously as providing that one interface.

class grok.LocalUtility

The base class for local utilities in Grok applications.

Defines a utility that will be registered local to a Site or grok.Application.

Although application developers can create local utilies without actually subclassing LocalUtility, they gain three benefits from doing so. First, their code is more readable because their classes “look like” local utilities to casual readers. Second, their utility will know how to persist itself to the Zope database, which means that they can set its object attributes and know that the values are getting automatically saved. Third, they can omit the grok.provides() directive naming the interface that the utility provides, if their class only grok.implements() a single interface (unless the interface is one that the grok.LocalUtility already implements, in which case Grok cannot tell them apart, and grok.provides() must be used explicitly anyway).

class grok.MultiAdapter

Base class for an adapter that adapts n objects (where n>=1).

Use the adapts directive to specify which kinds of objects are adapted and the implements directive to specify which interface the adapter will provide. If it’s a named multi-adapter, you may use the name directive to specify the name.

Note that contrary to the Adapter, the MultiAdapter base class does not provide an __init__ method. An __init__ needs to accept the same number of arguments as are used in the adapts directive.

class grok.MultiSubscription

Base class for a subscription multi-adapter.

MultiSubscriptions are similar to multi adapters, except that it is possible to register multiple unnamed subscriptions for identical adapts and provides.

Use the adapts directive to explicitly set the multiple interfaces to adapt from. Use the implements directive to specify which interface the subscription provides, or if that is not unambiguous, also use the provides directive to specify which of the implemented interfaces should be used when registering the multi subscription.

class grok.Subscription(context)

Base class for a subscription adapter.

Subscriptions are similar to adapters, except that it is possible to register multiple unnamed subscriptions for identical context and provides.

Use the context directive to explicitly set the interface to adapt from. When omitted the current context is assumed. Use the implements directive to specify which interface the subscription provides, or if that is not unambiguous, also use the provides directive to specify which of the implemented interfaces should be used when registering the subscription.

grok.adapts(*interfaces)

Declares the types of objects that a multi-adapter adapts.

grok.implements(*args, **kw)

Declare interfaces implemented by instances of a class. The arguments are one or more interfaces or interface specifications (IDeclaration objects).

Since the original implementer from zope.interface is not supported anymore; grokcore.component continues to support it on its own.

:param interface or interfaces to be implement by a class.

Security

class grok.Permission(id, title='', description='')

class grok.permissions(*args, **kw)

The grokcore.security.permissions() directive.

This directive is used inside of a grok.Role subclass to list the permissions which each member of the role should always possess. Note that permissions should be passed as strings, and that several permissions they can simply be supplied as multiple arguments; there is no need to place them inside of a tuple or list:

class MyRole(grokcore.security.Role):
    grokcore.security.permissions('page.CreatePage', 'page.EditPage')
    ...

grok.Public

alias of zope.Public

class grok.require(*args, **kw)

class grok.Role(id, title, description='')

Base class for roles in Grok applications.

A role is a description of a class of users that gives them a machine-readable name, a human-readable title, and a set of permissions which users belong to that role should possess:

class Editor(grok.Role):
    grok.name('news.Editor')
    grok.title('Editor')
    grok.permissions('news.EditArticle', 'news.PublishArticle')

Traversal

class grok.Traverser(context, request)

Base class for traversers in Grok applications.

class grok.traversable(*args, **kw)

The grok.traversable() directive.

Each time this directive is used inside of a class, it designates an attribute of that class which URLs should be able to traverse. For example, the declaration:

class Mammoth(grok.Model):

grok.traversable(‘thighbone’)

means that if the URL /app/mymammoth designates a Mammoth, then /app/mymammoth/thighbone will also be a valid URL (assuming that the Mammoth instance, at runtime, indeed has an attribute by that name)! By default, the name that must be appended to the URL should simply be the same as the name of the attribute; but by providing a name keyword argument, the programmer can designate another name to appear in the URL instead of the raw attribute name.

Indexes

grok.Indexes

alias of <grokcore.catalog.components.IndexesClass object>

class grok.index.Field(*args, **kw)

A grokcore.catalog.Indexes index that matches against an entire field.

class grok.index.Set(*args, **kw)

A grokcore.catalog.Indexes index supporting keyword searches of a field.

class grok.index.Text(*args, **kw)

A grokcore.catalog.Indexes index supporting full-text searches of a field.

Events and event handling

class grok.ApplicationAddedEvent(app)

A Grok Application has been added.

class grok.ContainerModifiedEvent(object, *descriptions)

The container has been modified.

class grok.ObjectAddedEvent(object, newParent=None, newName=None)

An object has been added to a container.

If newParent or newName is not provided or is None, they will be taken from the values of object.__parent__ or object.__name__, respectively.

class grok.ObjectCopiedEvent(object, original)

An object has been copied

class grok.ObjectCreatedEvent(object)

An object has been created

class grok.ObjectModifiedEvent(object, *descriptions)

An object has been modified

class grok.ObjectMovedEvent(object, oldParent, oldName, newParent, newName)

An object has been moved

class grok.ObjectRemovedEvent(object, oldParent=None, oldName=None)

An object has been removed from a container.

If oldParent or oldName is not provided or is None, they will be taken from the values of object.__parent__ or object.__name__, respectively.

class grok.viewletmanager(*args, **kw)

grok.notify(event)

Notify all subscribers of event.

grok.subscribe(*args)

Declares that a function is to be registered as an event handler for the specified objects.

Normally, an event handler is simply registered as a subscriber for the event interface. In case of object events, the event handler is registered as a subscriber for the object type and the event interface.

Directives

class grok.baseclass(*args, **kw)

Marker directive. Declares that a subclass of an otherwise automatically configured component should not be registered, and that it serves as a base class instead.

class grok.context(*args, **kw)

Declares the type of object that the adapter (or a similar context- dependent component) adapts.

Parameters:

context – Interface (in this case all objects providing this interface will be eligible contexts for the adaptation) or a class (then only instances of that particular class are eligible).

class grok.description(*args, **kw)

class grok.direct(*args, **kw)

Declares that a GlobalUtility class should be registered as a utility itself, rather than an instance of it.

class grok.global_utility(*args, **kw)

Registers an instance of class (or class itself, depending on the value of the direct parameter) as a global utility.

This allows you to register global utilities that don’t inherit from the GlobalUtility base class.

Parameters:

• class – The class to register as a global utility.

• provides – Optionally, the interface the utility will provide.

• name (string or unicode) – Optionally, a name for a named utility registration.

• direct (boolean) – Optionally, a flag indicating the class directly provides the interfaces, and it needs not to be instantiated.

class grok.layer(*args, **kw)

class grok.name(*args, **kw)

Declares the name of a named utility, named adapter, etc.

class grok.permissions(*args, **kw)

The grokcore.security.permissions() directive.

This directive is used inside of a grok.Role subclass to list the permissions which each member of the role should always possess. Note that permissions should be passed as strings, and that several permissions they can simply be supplied as multiple arguments; there is no need to place them inside of a tuple or list:

class MyRole(grokcore.security.Role):
    grokcore.security.permissions('page.CreatePage', 'page.EditPage')
    ...

class grok.provides(*args, **kw)

Declares the interface that a adapter or utility provides for the registration, as opposed to potentially multiple interfaces that the class implements.

Parameters:

interface – The interface the registered component will provide.

class grok.require(*args, **kw)

class grok.site(*args, **kw)

This directive is used to indicate the Grok site object for which the component should be used/registered.

class grok.skin(*args, **kw)

class grok.template(*args, **kw)

class grok.title(*args, **kw)

Declares the human-readable title of a component (such as a permission, role, etc.)

class grok.view(*args, **kw)

class grok.viewletmanager(*args, **kw)

Grokkers

class grok.ClassGrokker

Grokker that groks classes in a module.

class grok.GlobalGrokker

Grokker that groks once per module.

class grok.GrokError(message, component)

class grok.GrokImportError

class grok.InstanceGrokker

Grokker that groks instances in a module.

grok.testing.grok(module_name=None)

Grok a module.

Test helper to ‘grok’ a module named by module_name, a dotted path to a module like 'mypkg.mymodule'. ‘grokking’ hereby means to do all the ZCML configurations triggered by directives like grok.context() etc. This is only needed if your module was not grokked during test setup time as it normally happens with functional tests.

grok.testing.warn(message, category=None, stacklevel=1)

Intended to replace warnings.warn in tests.

Modified copy from zope.deprecation.tests to:

• make the signature identical to warnings.warn

• to check for .pyc and .pyo files.

When zope.deprecation is fixed, this warn function can be removed again.