[Checkins] SVN: grok/trunk/doc/reference/ clean up directives in the ref docs, mostly formatting and consistency issues for now, still needs another edit.
Kevin Teague
kevin at bud.ca
Thu Sep 25 05:16:46 EDT 2008
Log message for revision 91472:
clean up directives in the ref docs, mostly formatting and consistency issues for now, still needs another edit.
Changed:
U grok/trunk/doc/reference/components.rst
U grok/trunk/doc/reference/directives.rst
-=-
Modified: grok/trunk/doc/reference/components.rst
===================================================================
--- grok/trunk/doc/reference/components.rst 2008-09-25 09:14:43 UTC (rev 91471)
+++ grok/trunk/doc/reference/components.rst 2008-09-25 09:16:46 UTC (rev 91472)
@@ -11,9 +11,9 @@
components of different types, that provide basic Zope 3 functionality in a
convenient way. Grok applications are built by subclassing these components.
-Components in Grok and Zope 3 can be any plain Python object, that you have
-declared implements one or more Interface(s). The inclusion of these Grok base
-classes in your own Python classes inheritance automatically handles the
+Components in Grok and Zope 3 are any plain Python object, that declare they
+provide one or more Interface(s). The inclusion of these Grok base
+classes in your own class inheritance automatically handles the
component registration with the Zope Component Architecture. This process of
introspecting your Grok code during initialization and wiring together
components based on common conventions that you follow in the structure
Modified: grok/trunk/doc/reference/directives.rst
===================================================================
--- grok/trunk/doc/reference/directives.rst 2008-09-25 09:14:43 UTC (rev 91471)
+++ grok/trunk/doc/reference/directives.rst 2008-09-25 09:16:46 UTC (rev 91472)
@@ -23,64 +23,72 @@
: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)
- 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.
+ A class or module level directive to indicate the context for
+ something (class or module) in the same scope.
- 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.
+ 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.
- **Example:**
+ 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.
- 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`):
+**Example:**
- .. code-block:: python
+Here the :func:`grok.context` directive indicates that the :class:`Index`
+View applies to the context of a :class:`Mammoth` instance, and not instances
+of :class:`Cave`. By declaring the class or interface with :func:`grok.context`
+for an object, you are stating that your object depends upon the methods
+and attributes of that context.
+.. code-block:: python
+
import grok
class Mammoth(grok.Model):
- pass
+ hair = 'Wooly'
class Cave(grok.Model):
- pass
+ texture = 'rough'
class Index(grok.View):
grok.context(Mammoth)
- .. seealso::
+ def render(self):
+ # self.context will always have the interface of a Mammoth object,
+ # since this view declares that it depends upon the context of a
+ # Mammoth class.
+ return "It feels %s" % self.context.hair
+.. 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)
- 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.
+ A class level directive used to associate a component with a single
+ name `name`.
- **Example:**
+ 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.
- .. code-block:: python
+**Example:**
+.. code-block:: python
+
import grok
class Mammoth(grok.Model):
@@ -92,7 +100,7 @@
grok.name('index')
- .. seealso::
+.. seealso::
:class:`grok.Adapter`, :class:`grok.Annotation`,
:class:`grok.GlobalUtility`, :class:`grok.Indexes`,
@@ -100,59 +108,72 @@
:class:`grok.View`
-:func:`grok.title`
-========================
+:func:`grok.title` -- Succincint description
+============================================
.. function:: grok.title(*arg)
- foobar
+ A descriptive title for a component.
+
: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)
- This directive allows several parameters.
+ A class level directive to declare one or more `interfaces`, as
+ implementers of the surrounding class.
- :func:`grok.implements` is currently an alias for
- :func:`zope.interface.implements`.
+ This directive allows several parameters.
- **Example:**
+ :func:`grok.implements` is currently an alias for
+ :func:`zope.interface.implements`.
- .. code-block:: python
+**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
+ import grok
+ from zope import interface
+
+ class IPaintable(interface.Interface):
+ def paint(color):
+ "Paint with a color"
+ class Cave(object):
+ pass
+
+ cave = Cave()
+ IPaintable.providedBy(cave)
+
+This would return `False` since Cave does not implement the IPaintable
+interface.
+
+.. code-block:: python
+
+ class PaintableCave(object):
+ grok.implements(IPaintable)
+
+ def paint(color):
+ self._painted_color = color
+
+ cave = PaintableCave()
+ IPaintable.providedBy(cave)
+
+This would return `True` since the PaintableCave class declares that it
+implements the IPaintable interface.
+
+
: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`
@@ -162,17 +183,17 @@
.. 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:**
- .. code-block:: python
+.. code-block:: python
import grok
from zope import interface, schema
@@ -198,20 +219,20 @@
def sizeForDisplay(self):
return ('1000 bytes')
- Having :class:`MammothSize` available, you can register it as an adapter,
- without a single line of ZCML:
+Having :class:`MammothSize` available, you can register it as an adapter,
+without a single line of ZCML:
- .. code-block:: python
+.. code-block:: python
- >>> manfred = Mammoth()
- >>> from zope.component import provideAdapter
- >>> provideAdapter(MammothSize)
- >>> from zope.size.interfaces import ISized
- >>> size = ISized(manfred)
- >>> size.sizeForDisplay()
- '1000 bytes'
+ manfred = Mammoth()
+ from zope.component import provideAdapter
+ provideAdapter(MammothSize)
+ from zope.size.interfaces import ISized
+ size = ISized(manfred)
+ size.sizeForDisplay()
+ # would return '1000 bytes'
- .. seealso::
+.. seealso::
:func:`grok.implements`
@@ -221,20 +242,24 @@
.. 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:**
- .. code-block:: python
+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`.
+.. code-block:: python
+
import grok
class ModelBase(grok.Model):
@@ -253,11 +278,7 @@
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`.
-
Utility directives
~~~~~~~~~~~~~~~~~~
@@ -266,65 +287,56 @@
.. 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
+.. code-block:: python
- import grok
- from zope import interface
+ import grok
+ from zope import interface
- class IFireplace(interface.Interface):
- pass
+ class IFireplace(interface.Interface):
+ pass
- class Fireplace(object):
- grok.implements(IFireplace)
+ class Fireplace(object):
+ grok.implements(IFireplace)
- grok.global_utility(Fireplace)
- grok.global_utility(Fireplace, name='hot')
+ grok.global_utility(Fireplace)
+ grok.global_utility(Fireplace, name='hot')
- Then the following works:
+Then the following works:
- .. code-block:: python
+.. code-block:: python
- >>> from zope import component
- >>> fireplace = component.getUtility(IFireplace)
- >>> IFireplace.providedBy(fireplace)
- True
- >>> isinstance(fireplace, Fireplace)
- True
+ from zope import component
+ fireplace = component.getUtility(IFireplace)
+ hot_fireplace = component.getUtility(IFireplace, name='hot')
- >>> fireplace = component.getUtility(IFireplace, name='hot')
- >>> IFireplace.providedBy(fireplace)
- True
- >>> isinstance(fireplace, Fireplace)
- True
+.. seealso::
- .. seealso::
-
:class:`grok.GlobalUtility`, :func:`grok.provides`,
:func:`grok.implements`
@@ -334,45 +346,45 @@
.. 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
+ `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
+ `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`
@@ -392,58 +404,11 @@
grok.local_utility(Fireplace, public=True,
name_in_container='fireplace')
- .. seealso::
+.. seealso::
- :func:`grok.global_utility`, :class:`grok.LocalUtility`
+ :func:`grok.global_utility`, :class:`grok.LocalUtility`
-:func:`grok.resourcedir --- XXX Not implemented yet`
-====================================================
-
-.. function:: grok.resourcedir(*arg)
-
- 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)
-
- 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:**
-
- 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::
-
- 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**
-
- grok provides a convenient way to calculate the URLs to static
- resource using the keyword `static` in page templates:
-
- .. code-block:: html
-
- <link rel="stylesheet" tal:attributes="href static/example.css"
- type="text/css">
-
- The keyword `static` will be replaced by the reference to
- the resource directory for the package in which the template was
- registered.
-
-
Security directives
~~~~~~~~~~~~~~~~~~~
@@ -452,19 +417,19 @@
.. 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**
- .. code-block:: python
+.. code-block:: python
class ViewPainting(grok.Permission):
- grok.name('grok.ViewPainting')
+ grok.name('grok.ViewPainting')
- .. seealso::
+.. seealso::
:class:`grok.Permission` component, :func:`@grok.require` decorator
@@ -480,15 +445,15 @@
.. function:: grok.template(template)
- `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`
@@ -499,24 +464,24 @@
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
- ** 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`
-Uncategorized directives
-~~~~~~~~~~~~~~~~~~~~~~~~
+Component registry directives
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:func:`grok.site`
=================
@@ -526,9 +491,9 @@
.. function:: grok.site(*arg)
- **Example**
+**Example**
- .. code-block:: python
+.. code-block:: python
class MammothIndexes(grok.Indexes):
grok.site(Herd)
@@ -537,6 +502,9 @@
name = index.Field()
+URL Traversal directives
+~~~~~~~~~~~~~~~~~~~~~~~~
+
:func:`grok.traversable`
========================
@@ -546,22 +514,21 @@
.. function:: grok.traversable(attr, name=None)
- **Example**
+**Example**
- .. code-block:: python
+.. code-block:: python
+ class Foo(grok.Model):
+ grok.traversable('bar')
+ grok.traversable('foo')
+ grok.traversable(attr='bar', name='namedbar')
- class Foo(grok.Model):
- grok.traversable('bar')
- grok.traversable('foo')
- grok.traversable(attr='bar', name='namedbar')
+ def __init__(self, name):
+ self.name = name
- def __init__(self, name):
- self.name = name
+ foo = Bar('foo')
+ def bar(self):
+ return Bar('bar')
- foo = Bar('foo')
- def bar(self):
- return Bar('bar')
-
The result is that you can now access http://localhost/foo/bar,
-http://localhost/foo/foo and http://localhost/foo/namedbar.
\ No newline at end of file
+http://localhost/foo/foo and http://localhost/foo/namedbar.
More information about the Checkins
mailing list