[Checkins] SVN: grok/trunk/doc/reference/ Updated reference markup,
identation etc.
Uli Fouquet
uli at gnufix.de
Tue Jan 15 19:15:24 EST 2008
Log message for revision 82908:
Updated reference markup, identation etc.
Changed:
U grok/trunk/doc/reference/components.rst
U grok/trunk/doc/reference/decorators.rst
U grok/trunk/doc/reference/directives.rst
U grok/trunk/doc/reference/events.rst
U grok/trunk/doc/reference/exceptions.rst
U grok/trunk/doc/reference/functions.rst
-=-
Modified: grok/trunk/doc/reference/components.rst
===================================================================
--- grok/trunk/doc/reference/components.rst 2008-01-16 00:00:30 UTC (rev 82907)
+++ grok/trunk/doc/reference/components.rst 2008-01-16 00:15:24 UTC (rev 82908)
@@ -40,8 +40,8 @@
.. class:: grok.Adapter
- Base class to define an adapter. Adapters are automatically registered when a
- module is "grokked".
+ Base class to define an adapter. Adapters are automatically
+ registered when a module is "grokked".
.. attribute:: grok.Adapter.context
@@ -50,39 +50,42 @@
**Directives:**
:func:`grok.context(context_obj_or_interface)`
- Maybe required. Identifies the type of objects or interface for the adaptation.
+ Maybe required. Identifies the type of objects or interface for
+ the adaptation.
.. seealso::
- :function:`grok.context`
+ :func:`grok.context`
:func:`grok.implements(\*interfaces)`
Required. Identifies the interface(s) the adapter implements.
.. seealso::
- :function:`grok.implements`
+ :func:`grok.implements`
:func:`grok.name(name)`
- Optional. Identifies the name used for the adapter registration. If ommitted, no
- name will be used.
+ Optional. Identifies the name used for the adapter
+ registration. If ommitted, no name will be used.
- When a name is used for the adapter registration, the adapter can only be
- retrieved by explicitely using its name.
+ When a name is used for the adapter registration, the adapter
+ can only be retrieved by explicitely using its name.
.. seealso::
- :function:`grok.name`
+ :func:`grok.name`
:func:`grok.provides(name)`
Maybe required.
.. seealso::
- :function:`grok.provides`
+ :func:`grok.provides`
-**Example 1:** ::
+**Example 1:**
+.. code-block:: python
+
import grok
from zope import interface
@@ -97,15 +100,17 @@
home = IHome(cave)
-**Example 2: Register and retrieve the adapter under a specific name** ::
+**Example 2: Register and retrieve the adapter under a specific name**
+
+.. code-block:: python
+
import grok
from zope import interface
class Cave(grok.Model):
pass
-
- class IHome(interface.Interface):
+ class IHome(interface.Interface):
pass
class Home(grok.Adapter):
@@ -115,6 +120,7 @@
from zope.component import getAdapter
home = getAdapter(cave, IHome, name='home')
+
:class:`grok.MultiAdapter`
==========================
@@ -144,8 +150,10 @@
:func:`grok.provides` is required to disambiguate for what interface the
adapter will be registered.
-**Example:** ::
+**Example:**
+.. code-block:: python
+
import grok
from zope import interface
@@ -171,6 +179,7 @@
:class:`grok.Annotation`
========================
+
Utilities
~~~~~~~~~
@@ -199,6 +208,7 @@
:func:`grok.provides` is required to disambiguate for what interface the
global utility will be registered.
+
:class:`grok.LocalUtility`
==========================
@@ -240,7 +250,7 @@
:class:`grok.View`
==================
-:class:`grok.JSON
+:class:`grok.JSON`
==================
:class:`grok.XMLRPC`
@@ -291,8 +301,10 @@
it is important to define permissions, which restrict access to
certain principals or roles.
- **Example:** ::
+ **Example:**
+ .. code-block:: python
+
import grok
grok.define_permission('cave.enter')
@@ -302,6 +314,7 @@
:func:`grok.require`, :class:`grok.Permission`, :class:`grok.Role`
.. versionchanged:: 0.11
+
replaced by :class:`grok.Permission`.
:class:`Role`
Modified: grok/trunk/doc/reference/decorators.rst
===================================================================
--- grok/trunk/doc/reference/decorators.rst 2008-01-16 00:00:30 UTC (rev 82907)
+++ grok/trunk/doc/reference/decorators.rst 2008-01-16 00:15:24 UTC (rev 82908)
@@ -13,14 +13,14 @@
.. function:: subscribe(*classes_or_interfaces)
-Declare that the decorated function subscribes to an event or a combination of
-objects and events and register it.
+ Declare that the decorated function subscribes to an event or a
+ combination of objects and events and register it.
-Applicable on module-level for functions. Requires at least one class or
-interface as argument.
+ Applicable on module-level for functions. Requires at least one
+ class or interface as argument.
-(Similar to Zope 3's :func:`subscriber` decorator, but automatically performs
-the registration of the component.)
+ (Similar to Zope 3's :func:`subscriber` decorator, but automatically
+ performs the registration of the component.)
:func:`grok.action` -- Declare a form submit handler
@@ -33,43 +33,48 @@
:func:`grok.adapter/grok.implementer` -- Declare an adapter factory
====================================================================
-.. XXX these two decorators are always used together, but are named separately because they are separate in the Zope 3 API. Should grok implement this as one decorator with two arguments?
+.. XXX these two decorators are always used together, but are named
+ separately because they are separate in the Zope 3 API. Should
+ grok implement this as one decorator with two arguments?
These decorators are always used in tandem to declare an adapter factory.
.. function:: grok.adapter(*interfaces)
-`*interfaces` -- the interfaces *adapted* by the object created by this factory.
+ `*interfaces` -- the interfaces *adapted* by the object created by
+ this factory.
+
.. function:: grok.implementer(interface)
-`interface` -- the interface *provided* by the object created by this factory.
+ `interface` -- the interface *provided* by the object created by
+ this factory.
-**Example 1:** ::
+**Example 1:**
+.. code-block:: python
+
@grok.adapter(ICave)
@grok.implementer(IHome)
def home_for_cave(cave):
return Home()
-**Example 2: adapt a regular class instead of an interface ** ::
+**Example 2: adapt a regular class instead of an interface**
+.. code-block:: python
+
@grok.adapter(Cave)
@grok.implementer(IHome)
def home_for_cave(cave):
return Home()
-**Example 3: declare a multi-adapter factory ** ::
+**Example 3: declare a multi-adapter factory**
+.. code-block:: python
+
@grok.adapter(ICave,IFire)
@grok.implementer(ICozy)
def cozy_dwelling(cave, fire):
return Dwelling()
-
-
-
-
-
-
Modified: grok/trunk/doc/reference/directives.rst
===================================================================
--- grok/trunk/doc/reference/directives.rst 2008-01-16 00:00:30 UTC (rev 82907)
+++ grok/trunk/doc/reference/directives.rst 2008-01-16 00:15:24 UTC (rev 82908)
@@ -23,74 +23,83 @@
:func:`grok.context` -- Declare the context for views, adapters, etc.
=====================================================================
+A class or module level directive to indicate the context for
+something (class or module) in the same scope.
.. function:: grok.context(*class_or_interface)
-A class or module level directive to indicate the context for something
-(class or module) in the same scope. When used on module level, it will set
-the context for all views, adapters, etc. in that module. When used on class
-level, it will set the context for that particular class.
+ When used on module level, it will set the context for all views,
+ adapters, etc. in that module. When used on class level, it will set
+ the context for that particular class.
-With Grok contexts are set automatically for some objects, if they are
-unambigous. For example a :class:`grok.View` will get the only
-:class:`grok.Application` or :class:`grok.Model` class as context, iff there
-exists exactly one in the same module. If there are more possible contexts
-or you want to set a type (class/interface) from another module as context,
-than the one choosen by default, then you have to call :func:`grok.context`
-explicitly.
+ With Grok contexts are set automatically for some objects, if they are
+ unambigous. For example a :class:`grok.View` will get the only
+ :class:`grok.Application` or :class:`grok.Model` class as context,
+ iff there exists exactly one in the same module. If there are more
+ possible contexts or you want to set a type (class/interface) from
+ another module as context, than the one choosen by default, then you
+ have to call :func:`grok.context` explicitly.
-**Example:**
+ **Example:**
-Here the :func:`grok.context` directive indicates, that
-:class:`Mammoth` instances will be the context of :class:`Index`
-views (and not instances of :class:`Cave`) ::
+ Here the :func:`grok.context` directive indicates, that
+ :class:`Mammoth` instances will be the context of :class:`Index`
+ views (and not instances of :class:`Cave`):
- import grok
+ .. code-block:: python
- class Mammoth(grok.Model):
- pass
+ import grok
- class Cave(grok.Model):
- pass
+ class Mammoth(grok.Model):
+ pass
- class Index(grok.View):
- grok.context(Mammoth)
+ class Cave(grok.Model):
+ pass
-.. seealso::
+ class Index(grok.View):
+ grok.context(Mammoth)
- :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
+ .. seealso::
+ :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
+
+
:func:`grok.name` -- associate a component with a name
======================================================
+A class level directive used to associate a component with a single
+name `name`.
+
.. function:: grok.name(name)
-A class level directive used to associate a component with a single name
-`name`. Typically this directive is optional. The default behaviour when no
-name is given depends on the component. The same applies to the semantics of
-this directive: for what exactly a name is set when using this directive,
-depends on the component.
+ Typically this directive is optional. The default behaviour when no
+ name is given depends on the component. The same applies to the
+ semantics of this directive: for what exactly a name is set when
+ using this directive, depends on the component.
-**Example:** ::
+ **Example:**
- import grok
+ .. code-block:: python
- class Mammoth(grok.Model):
+ import grok
+
+ class Mammoth(grok.Model):
pass
- # a common use case is to have a URL for a view named differently than
- # the name of the view class itself.
- class SomeView(grok.View):
- grok.name('index')
+ # a common use case is to have a URL for a view named differently than
+ # the name of the view class itself.
+ class SomeView(grok.View):
+ grok.name('index')
-.. seealso::
+ .. seealso::
- :class:`grok.Adapter`, :class:`grok.Annotation`,
- :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
- :class:`grok.MultiAdapter`, :class:`grok.Role`,
- :class:`grok.View`
+ :class:`grok.Adapter`, :class:`grok.Annotation`,
+ :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
+ :class:`grok.MultiAdapter`, :class:`grok.Role`,
+ :class:`grok.View`
+
:func:`grok.title`
========================
@@ -101,139 +110,154 @@
:func:`grok.implements` -- indicate, that a class implements an interface
=========================================================================
+A class level directive to declare one or more `interfaces`, as
+implementers of the surrounding class.
+
.. function:: grok.implements(*interfaces)
-A class level directive to declare one or more `interfaces`, as implementers
-of the surrounding class. This directive allows several parameters.
+ This directive allows several parameters.
-:func:`grok.implements` is currently an alias for
-:func:`zope.interface.implements`.
+ :func:`grok.implements` is currently an alias for
+ :func:`zope.interface.implements`.
-**Example:** ::
+ **Example:**
- >>> import grok
- >>> from zope import interface
- >>> class IPaintable(interface.Interface):
- ... pass
- ...
- >>> class Cave(object):
- ... pass
- ...
- >>> cave = Cave()
- >>> IPaintable.providedBy(cave)
- False
- >>> class PaintableCave(object):
- ... grok.implements(IPaintable)
- ...
- >>> cave = PaintableCave()
- >>> IPaintable.providedBy(cave)
- True
+ .. code-block:: python
-:func:`grok.provides`
-=====================
+ >>> import grok
+ >>> from zope import interface
+ >>> class IPaintable(interface.Interface):
+ ... pass
+ ...
+ >>> class Cave(object):
+ ... pass
+ ...
+ >>> cave = Cave()
+ >>> IPaintable.providedBy(cave)
+ False
+ >>> class PaintableCave(object):
+ ... grok.implements(IPaintable)
+ ...
+ >>> cave = PaintableCave()
+ >>> IPaintable.providedBy(cave)
+ True
+
+:func:`grok.provides` -- Declare, that a component provides a certain interface
+===============================================================================
+
.. function:: grok.provides(interface)
-If the component implements more than one interface, :func:`grok.provides`
-is required to disambiguate for what interface the component will be
-registered.
+ If the component implements more than one interface,
+ :func:`grok.provides` is required to disambiguate for what interface
+ the component will be registered.
-.. seealso::
+ .. seealso::
- :func:`grok.implements`
+ :func:`grok.implements`
+
:func:`grok.adapts` -- Declare that a class adapts certain objects
==================================================================
.. function:: grok.adapts(*classes_or_interfaces)
-A class-level directive to declare that a class adapts objects of the
-classes or interfaces given in `\*classes_or_interfaces`.
+ A class-level directive to declare that a class adapts objects of
+ the classes or interfaces given in `\*classes_or_interfaces`.
-This directive accepts several arguments.
+ This directive accepts several arguments.
-It works much like the :mod:`zope.component`\ s :func:`adapts()`, but you do
-not have to make a ZCML entry to register the adapter.
+ It works much like the :mod:`zope.component`\ s :func:`adapts()`,
+ but you do not have to make a ZCML entry to register the adapter.
-**Example:** ::
+ **Example:**
- import grok
- from zope import interface, schema
- from zope.size.interfaces import ISized
+ .. code-block:: python
- class IMammoth(interface.Interface):
- name = schema.TextLine(title=u"Name")
- size = schema.TextLine(title=u"Size", default=u"Quite normal")
+ import grok
+ from zope import interface, schema
+ from zope.size.interfaces import ISized
- class Mammoth(grok.Model):
- interface.implements(IMammoth)
+ class IMammoth(interface.Interface):
+ name = schema.TextLine(title=u"Name")
+ size = schema.TextLine(title=u"Size", default=u"Quite normal")
- class MammothSize(object):
- grok.implements(ISized)
- grok.adapts(IMammoth)
+ class Mammoth(grok.Model):
+ interface.implements(IMammoth)
- def __init__(self, context):
- self.context = context
+ class MammothSize(object):
+ grok.implements(ISized)
+ grok.adapts(IMammoth)
- def sizeForSorting(self):
- return ('byte', 1000)
+ def __init__(self, context):
+ self.context = context
- def sizeForDisplay(self):
- return ('1000 bytes')
+ def sizeForSorting(self):
+ return ('byte', 1000)
-Having :class:`MammothSize` available, you can register it as an adapter,
-without a single line of ZCML::
+ def sizeForDisplay(self):
+ return ('1000 bytes')
- >>> manfred = Mammoth()
- >>> from zope.component import provideAdapter
- >>> provideAdapter(MammothSize)
- >>> from zope.size.interfaces import ISized
- >>> size = ISized(manfred)
- >>> size.sizeForDisplay()
- '1000 bytes'
+ Having :class:`MammothSize` available, you can register it as an adapter,
+ without a single line of ZCML:
-.. seealso::
+ .. code-block:: python
- :func:`grok.implements`
+ >>> manfred = Mammoth()
+ >>> from zope.component import provideAdapter
+ >>> provideAdapter(MammothSize)
+ >>> from zope.size.interfaces import ISized
+ >>> size = ISized(manfred)
+ >>> size.sizeForDisplay()
+ '1000 bytes'
+ .. seealso::
+
+ :func:`grok.implements`
+
+
:func:`grok.baseclass` -- declare a class as base
=================================================
.. function:: grok.baseclass()
-A class-level directive without argument to mark something as a base class.
-Base classes are are not grokked.
+ A class-level directive without argument to mark something as a base
+ class. Base classes are are not grokked.
-Another way to indicate that something is a base class, is by postfixing the
-classname with ``'Base'``.
+ Another way to indicate that something is a base class, is by
+ postfixing the classname with ``'Base'``.
-The baseclass mark is not inherited by subclasses, so those subclasses will
-be grokked (except they are explicitly declared as baseclasses as well).
+ The baseclass mark is not inherited by subclasses, so those
+ subclasses will be grokked (except they are explicitly declared as
+ baseclasses as well).
-**Example:** ::
+ **Example:**
- import grok
+ .. code-block:: python
- class ModelBase(grok.Model):
- pass
+ import grok
- class ViewBase(grok.View):
- def render(self):
- return "hello world"
+ class ModelBase(grok.Model):
+ pass
+
+ class ViewBase(grok.View):
+ def render(self):
+ return "hello world"
- class AnotherView(grok.View):
- grok.baseclass()
+ class AnotherView(grok.View):
+ grok.baseclass()
- def render(self):
- return "hello world"
+ def render(self):
+ return "hello world"
- class WorkingView(grok.View):
- pass
+ class WorkingView(grok.View):
+ pass
-Using this example, only the :class:`WorkingView` will serve as a view,
-while calling the :class:`ViewBase` or :class:`AnotherView` will lead to a
-:exc:`ComponentLookupError`.
+ Using this example, only the :class:`WorkingView` will serve as a
+ view, while calling the :class:`ViewBase` or :class:`AnotherView`
+ will lead to a :exc:`ComponentLookupError`.
+
Utility directives
~~~~~~~~~~~~~~~~~~
@@ -242,31 +266,34 @@
.. function:: grok.global_utility(factory[, provides=None[, name=u'']])
-A module level directive to register a global utility.
+ A module level directive to register a global utility.
-`factory` - the factory that creates the utility.
+ `factory` - the factory that creates the utility.
-`provides` - the interface the utility should be looked up with.
+ `provides` - the interface the utility should be looked up with.
-`name` - the name of the utility.
+ `name` - the name of the utility.
-The latter two parameters are optional.
+ The latter two parameters are optional.
-To register the utility correctly, Grok must be able to identify an
-interface provided by the utility. If none is given, Grok checks whether
-(exactly) one interface is implemented by the factory to be registered (see
-example below). If more than one interface is implemented by a class, use
-:func:`grok.provides` to specify which one to use. If no interface is
-implemented by the instances delivered by the factory, use
-:func:`grok.implements` to specify one.
+ To register the utility correctly, Grok must be able to identify an
+ interface provided by the utility. If none is given, Grok checks
+ whether (exactly) one interface is implemented by the factory to be
+ registered (see example below). If more than one interface is
+ implemented by a class, use :func:`grok.provides` to specify which
+ one to use. If no interface is implemented by the instances
+ delivered by the factory, use :func:`grok.implements` to specify
+ one.
-Another way to register global utilities with Grok is to subclass from
-:class:`grok.GlobalUtility`.
+ Another way to register global utilities with Grok is to subclass from
+ :class:`grok.GlobalUtility`.
-**Example:**
+ **Example:**
- Given the following module code: ::
+ Given the following module code:
+ .. code-block:: python
+
import grok
from zope import interface
@@ -279,8 +306,10 @@
grok.global_utility(Fireplace)
grok.global_utility(Fireplace, name='hot')
- Then the following works: ::
+ Then the following works:
+ .. code-block:: python
+
>>> from zope import component
>>> fireplace = component.getUtility(IFireplace)
>>> IFireplace.providedBy(fireplace)
@@ -294,57 +323,62 @@
>>> isinstance(fireplace, Fireplace)
True
-.. seealso::
+ .. seealso::
- :class:`grok.GlobalUtility`, :func:`grok.provides`,
- :func:`grok.implements`
+ :class:`grok.GlobalUtility`, :func:`grok.provides`,
+ :func:`grok.implements`
+
:func:`grok.local_utility` -- register a local utility
======================================================
.. function:: grok.local_utility(factory[, provides=None[, name=u''[, setup=None[, public=False[, name_in_container=None]]]]])
-A class level directive to register a local utility.
+ A class level directive to register a local utility.
-`factory` -- the factory that creates the utility.
+ `factory` -- the factory that creates the utility.
-`provides` -- the interface the utility should be looked up with.
+ `provides` -- the interface the utility should be looked up with.
-`name` -- the name of the utility.
+ `name` -- the name of the utility.
-`setup` -- a callable that receives the utility as its single
- argument, it is called after the utility has been created and
- stored.
+ `setup` -- a callable that receives the utility as its single
+ argument, it is called after the utility has been created
+ and stored.
-`public` -- if `False`, the utility will be stored below
- `++etc++site`. If `True`, the utility will be stored directly
- in the site. The site should in this case be a container.
+ `public` -- if `False`, the utility will be stored below
+ `++etc++site`. If `True`, the utility will be stored
+ directly in the site. The site should in this case be a
+ container.
-`name_in_container` -- the name to use for storing the utility.
+ `name_in_container` -- the name to use for storing the utility.
-All but the first parameter are optional.
+ All but the first parameter are optional.
-To register a local utility correctly, Grok must know about the interface,
-the utility should be looked up with. If none is given, Grok looks up any
-interfaces implemented by instances delivered by `factory` and if exactly
-one can be found, it is taken. See :func:`grok.global_utility`.
+ To register a local utility correctly, Grok must know about the
+ interface, the utility should be looked up with. If none is given,
+ Grok looks up any interfaces implemented by instances delivered by
+ `factory` and if exactly one can be found, it is taken. See
+ :func:`grok.global_utility`.
-Every single combination of interfaces and names can only be registered once
-per module.
+ Every single combination of interfaces and names can only be
+ registered once per module.
-It is not possible to declare a local utility as public, if the site is not
-a container. Grok will remind you of this. To store a utility in a
-container, a `name_in_container` is needed. If none is given, Grok will make
-up one automatically.
+ It is not possible to declare a local utility as public, if the site
+ is not a container. Grok will remind you of this. To store a utility
+ in a container, a `name_in_container` is needed. If none is given,
+ Grok will make up one automatically.
-An alternative way to define a local utility is to subclass from
-:class:`grok.LocalUtility`.
+ An alternative way to define a local utility is to subclass from
+ :class:`grok.LocalUtility`.
-**Example:**
+ **Example:**
- The following code registers a local unnamed utility `fireplace` in
- instances of :class:`Cave` ::
+ The following code registers a local unnamed utility `fireplace` in
+ instances of :class:`Cave`
+ .. code-block:: python
+
import grok
from zope import interface
@@ -358,51 +392,58 @@
grok.local_utility(Fireplace, public=True,
name_in_container='fireplace')
-.. seealso::
+ .. seealso::
:func:`grok.global_utility`, :class:`grok.LocalUtility`
+
:func:`grok.resourcedir --- XXX Not implemented yet`
====================================================
.. function:: grok.resourcedir(*arg)
- foobar
+ Resource directories are used to embed static resources like HTML-,
+ JavaScript-, CSS- and other files in your application.
-Resource directories are used to embed static resources like HTML-,
-JavaScript-, CSS- and other files in your application.
+ .. XXX insert directive description here (first: define the name,
+ second: describe the default behaviour if the directive isn't
+ given)
-XXX insert directive description here (first: define the name, second:
-describe the default behaviour if the directive isn't given)
+ A resource directory is created when a package contains a directory
+ with the name :file:`static`. All files from this directory become
+ accessible from a browser under the URL
+ :file:`http://<servername>/++resource++<packagename>/<filename>`.
-A resource directory is created when a package contains a directory with the
-name :file:`static`. All files from this directory become accessible from a
-browser under the URL
-:file:`http://<servername>/++resource++<packagename>/<filename>`.
+ **Example:**
-**Example:**
+ The package :mod:`a.b.c` is grokked and contains a directory
+ :file:`static` which contains the file :file:`example.css`. The
+ stylesheet will be available via
+ :file:`http://<servername>/++resource++a.b.c/example.css`.
-The package :mod:`a.b.c` is grokked and contains a directory :file:`static`
-which contains the file :file:`example.css`. The stylesheet will be
-available via :file:`http://<servername>/++resource++a.b.c/example.css`.
+ .. note::
-.. note::
+ A package can never have both a :file:`static` directory and a
+ Python module with the name :file:`static.py` at the same
+ time. grok will remind you of this conflict when grokking a
+ package by displaying an error message.
-A package can never have both a :file:`static` directory and a Python module
-with the name :file:`static.py` at the same time. grok will remind you of
-this conflict when grokking a package by displaying an error message.
-Linking to resources from templates
------------------------------------
+ **Linking to resources from templates**
-grok provides a convenient way to calculate the URLs to static resource using
-the keyword :keyword:`static` in page templates::
+ grok provides a convenient way to calculate the URLs to static
+ resource using the keyword :keyword:`static` in page templates:
-<link rel="stylesheet" tal:attributes="href static/example.css" type="text/css">
+ .. code-block:: html
-The keyword :keyword:`static` will be replaced by the reference to the resource
-directory for the package in which the template was registered.
+ <link rel="stylesheet" tal:attributes="href static/example.css"
+ type="text/css">
+ The keyword :keyword:`static` will be replaced by the reference to
+ the resource directory for the package in which the template was
+ registered.
+
+
Security directives
~~~~~~~~~~~~~~~~~~~
@@ -411,73 +452,86 @@
.. function:: grok.require(permission)
-A class level directive used to protect a View by requiring a certain permission.
+ A class level directive used to protect a View by requiring a
+ certain permission.
-`permission` -- the name of the permission that is required
+ `permission` -- the name of the permission that is required
-** Example **::
+ **Example**
- class ViewPainting(grok.Permission):
- grok.name('grok.ViewPainting')
+ .. code-block:: python
+
+ class ViewPainting(grok.Permission):
+ grok.name('grok.ViewPainting')
+ .. seealso::
-.. seealso::
+ :class:`grok.Permission` component, :func:`@grok.require` decorator
- :class:`grok.Permission` component, :func:`@grok.require` decorator
-
Template directives
~~~~~~~~~~~~~~~~~~~
:func:`grok.template`
=====================
+A class level directive used to specify the template to be rendered
+for the View when no render method is defined.
+
.. function:: grok.template(template)
-A class level directive used to specify the template to be rendered for the View when no render method is defined.
+ `template` -- name of the template file
-`template` -- name of the template file
+ **Convention**
-** Convention **
+ When not specified, Grok will look for a template file with the same
+ name as the view class itself, lowercased, in the templates directory
+ for this module.
-When not specified, Grok will look for a template file with the same name as the view class itself, lowercased, in the templates directory for this module.
+ .. seealso::
-.. seealso::
+ :func:`grok.templatedir`
- :func:`grok.templatedir`
:func:`grok.templatedir`
========================
-A module level directive used to specify the directory where Grok should look for template files.
+A module level directive used to specify the directory where Grok
+should look for template files.
-.. function:: grok.templatedir(directory)
+ .. function:: grok.templatedir(directory)
-`directory` -- the name of the directory inside the same package as the module
+ `directory` -- the name of the directory inside the same package
+ as the module
-** Convention **
+ ** Convention **
-When not specified, Grok will look template files in a diretory named `<module>_templates` where `<module>` is the name of the current module.
+ When not specified, Grok will look template files in a diretory
+ named `<module>_templates` where `<module>` is the name of the current
+ module.
-.. seealso::
+ .. seealso::
- :func:`grok.template`
+ :func:`grok.template`
+
Uncategorized directives
~~~~~~~~~~~~~~~~~~~~~~~~
:func:`grok.site`
=================
+A class level directive used in `grok.Indexes` sub-classes to define
+in which local component registry the indexes should be located.
+
.. function:: grok.site(*arg)
-A class level directive used in `grok.Indexes` sub-classes to define in which local component registry the indexes should be located.
+ **Example**
-** Example **
-::
+ .. code-block:: python
- class MammothIndexes(grok.Indexes):
- grok.site(Herd)
- grok.context(IMammoth)
+ class MammothIndexes(grok.Indexes):
+ grok.site(Herd)
+ grok.context(IMammoth)
- name = index.Field()
+ name = index.Field()
Modified: grok/trunk/doc/reference/events.rst
===================================================================
--- grok/trunk/doc/reference/events.rst 2008-01-16 00:00:30 UTC (rev 82907)
+++ grok/trunk/doc/reference/events.rst 2008-01-16 00:15:24 UTC (rev 82908)
@@ -3,9 +3,9 @@
Events
******
-grok provides convenient access to a set of often-used events from Zope 3. Those
-events include object and containment events. All events are available as
-interface and implemented class.
+grok provides convenient access to a set of often-used events from
+Zope 3. Those events include object and containment events. All events
+are available as interface and implemented class.
grok.IContainerModifiedEvent
Modified: grok/trunk/doc/reference/exceptions.rst
===================================================================
--- grok/trunk/doc/reference/exceptions.rst 2008-01-16 00:00:30 UTC (rev 82907)
+++ grok/trunk/doc/reference/exceptions.rst 2008-01-16 00:15:24 UTC (rev 82908)
@@ -3,32 +3,34 @@
Exceptions
**********
-grok tries to inform you about errors early and with as much guidance as
-possible. grok can detect some errors already while importing a module, which
-will lead to the :class:`GrokImportError`. Other errors require more context
-and can only be detected while executing the :func:`grok` function.
+grok tries to inform you about errors early and with as much guidance
+as possible. grok can detect some errors already while importing a
+module, which will lead to the :class:`GrokImportError`. Other errors
+require more context and can only be detected while executing the
+:func:`grok` function.
:class:`grok.GrokImportError` -- errors while importing a module
================================================================
-This exception is raised if a grok-specific problem was found while importing a
-module of your application. :class:`GrokImportError` means there was a problem
-in how you are using a part of grok. The error message tries to be as
-informative as possible tell you why something went wrong and how you can fix
-it.
+This exception is raised if a grok-specific problem was found while
+importing a module of your application. :class:`GrokImportError` means
+there was a problem in how you are using a part of grok. The error
+message tries to be as informative as possible tell you why something
+went wrong and how you can fix it.
-:class:`GrokImportError` is a subclass of Python's :class:`ImportError`.
+:class:`GrokImportError` is a subclass of Python's
+:class:`ImportError`.
Examples of situations in which a GrokImportError occurs:
-* Using a directive in the wrong context (e.g. grok.templatedir on class-level
- instead of module-level.)
+ * Using a directive in the wrong context (e.g. grok.templatedir on
+ class-level instead of module-level.)
-* Using a decorator with wrong arguments (e.g. grok.subscribe without any
- argument)
+ * Using a decorator with wrong arguments (e.g. grok.subscribe
+ without any argument)
-* ...
+ * ...
:class:`grok.GrokError` -- errors while grokking a module
@@ -36,23 +38,23 @@
This exception is raised if an error occurs while grokking a module.
-Typically a :class:`GrokError` will be raised if one of your modules uses a
-feature of grok that requires some sort of unambigous context to establish a
-reasonable default.
+Typically a :class:`GrokError` will be raised if one of your modules
+uses a feature of grok that requires some sort of unambigous context
+to establish a reasonable default.
-For example, the :class:`grok.View` requires exactly one model to be defined
-locally in the module to assume a default module to be associated with. Having
-no model defined, or more than one model, will lead to an error because the
-context is either underspecified or ambigous.
+For example, the :class:`grok.View` requires exactly one model to be
+defined locally in the module to assume a default module to be
+associated with. Having no model defined, or more than one model, will
+lead to an error because the context is either underspecified or
+ambigous.
-The error message of a :class:`GrokError` will include the reason for the error,
-the place in your code that triggered the error, and a hint, to help you fix the
-error.
+The error message of a :class:`GrokError` will include the reason for
+the error, the place in your code that triggered the error, and a
+hint, to help you fix the error.
.. class:: GrokError(Exception)
-
.. attribute:: GrokError.component
The component that was grokked and triggered the error.
Modified: grok/trunk/doc/reference/functions.rst
===================================================================
--- grok/trunk/doc/reference/functions.rst 2008-01-16 00:00:30 UTC (rev 82907)
+++ grok/trunk/doc/reference/functions.rst 2008-01-16 00:15:24 UTC (rev 82908)
@@ -27,31 +27,34 @@
directive, in that one field is omitted from the form before
rendering:
-**Example:** ::
+ **Example:**
- import grok
- from zope import interface, schema
+ .. code-block:: python
- class IMammoth(interface.Interface):
- name = schema.TextLine(title=u"Name")
- size = schema.TextLine(title=u"Size", default=u"Quite normal")
+ import grok
+ from zope import interface, schema
- class Mammoth(grok.Model):
- interface.implements(IMammoth)
+ class IMammoth(interface.Interface):
+ name = schema.TextLine(title=u"Name")
+ size = schema.TextLine(title=u"Size", default=u"Quite normal")
- class Edit(grok.EditForm):
- grok.context(Mammoth)
+ class Mammoth(grok.Model):
+ interface.implements(IMammoth)
- form_fields = grok.AutoFields(Mammoth).omit('size')
+ class Edit(grok.EditForm):
+ grok.context(Mammoth)
-In this example the ``size`` attribute will not show up in the
-resulting edit view.
+ form_fields = grok.AutoFields(Mammoth).omit('size')
+ In this example the ``size`` attribute will not show up in the
+ resulting edit view.
-.. seealso::
- :class:`grok.EditForm`, :func:`grok.Fields`
+ .. seealso::
+ :class:`grok.EditForm`, :func:`grok.Fields`
+
+
:func:`grok.Fields` -- declare schema fields of a form
======================================================
@@ -63,8 +66,10 @@
A :class:`grok.Fields` can receive keyword parameters with schema
fields. These should be available in the definition order.
- **Example:** ::
+ **Example:**
+ .. code-block:: python
+
import grok
from zope import schema
@@ -85,10 +90,10 @@
:func:`grok.AutoFields`, :class:`grok.Form`
+
:func:`grok.getSite`
===============================================
-
.. function:: grok.getSite()
Get the current site object.
@@ -103,7 +108,7 @@
.. seealso::
`Web Component Development With Zope 3, second edition <http://worldcookery.com/WhereToBuy>`_
- By Philiip von Weitershaussen; Chapter 18 describes the use of Site objects.
+ By Philipp von Weitershausen; Chapter 18 describes the use of Site objects.
:func:`grok.notify`
@@ -114,8 +119,10 @@
Send `event` to event subscribers.
- Example::
+ **Example:**
+ .. code-block:: python
+
import grok
class Mammoth(object):
@@ -135,7 +142,8 @@
.. seealso::
`Web Component Development With Zope 3, second edition <http://worldcookery.com/WhereToBuy>`_
- By Philiip von Weitershaussen; Chapter 16 describes the Zope 3 event system.
+ By Philipp von Weitershausen; Chapter 16 describes the Zope 3
+ event system.
:func:`grok.url`
@@ -146,16 +154,17 @@
Construct a URL for the given `request` and `object`.
- `name` may be a string that gets appended to the object URL. Commonly used to
- construct an URL to a particular view on the object.
+ `name` may be a string that gets appended to the object
+ URL. Commonly used to construct an URL to a particular view on the
+ object.
This function returns the constructed URL as a string.
.. seealso::
- View classes derived from :class:`grok.View` have a similar :meth:`url` method
- for constructing URLs.
+ View classes derived from :class:`grok.View` have a similar
+ :meth:`url` method for constructing URLs.
:func:`grok.grok` -- Grok a package or module
@@ -164,37 +173,40 @@
.. function:: grok(dotted_name)
-.. note:: Usually you don't need to invoke this funtion in your code, since it's triggered from the `configure.zcml`. Grokking test fixtures is one situation where it is useful to call this explicitly.
+.. note:: Usually you don't need to invoke this funtion in your code,
+ since it's triggered from the `configure.zcml`. Grokking
+ test fixtures is one situation where it is useful to call
+ this explicitly.
-Grokking a package or module activates the contained components (like models,
-views, adapters, templates, etc.) and registers them with Zope 3's component
-architecture.
+ Grokking a package or module activates the contained components
+ (like models, views, adapters, templates, etc.) and registers them
+ with Zope 3's component architecture.
-The `dotted_name` must specify either a Python module or package that is
-available from the current PYTHONPATH.
+ The `dotted_name` must specify either a Python module or package
+ that is available from the current PYTHONPATH.
-Grokking a module:
+ Grokking a module:
-#. Scan the module for known components: models, adapters, utilities, views,
- traversers, templates and subscribers.
+ #. Scan the module for known components: models, adapters,
+ utilities, views, traversers, templates and subscribers.
-#. Check whether a directory with file system templates exists
-(:file:`<modulename>_templates`). If it exists, load the file system templates
-into the template registry for this module.
+ #. Check whether a directory with file system templates exists
+ (:file:`<modulename>_templates`). If it exists, load the file
+ system templates into the template registry for this module.
-#. Determine the module context.
+ #. Determine the module context.
-#. Register all components with the Zope 3 component architecture.
+ #. Register all components with the Zope 3 component architecture.
-#. Initialize schemata for registered models
+ #. Initialize schemata for registered models
- Grokking a package:
+ Grokking a package:
-#. Grok the package as a module.
+ #. Grok the package as a module.
-#. Check for a static resource directory (:file:`static`) and register it if
-it exists.
+ #. Check for a static resource directory (:file:`static`) and
+ register it if it exists.
-#. Recursively grok all sub-modules and sub-packages.
+ #. Recursively grok all sub-modules and sub-packages.
More information about the Checkins
mailing list