[Checkins] SVN: grok/trunk/src/grok/components.py Added further docstrings to the `grok.components` module, until a
Brandon Rhodes
brandon at rhodesmill.org
Sat Jan 3 09:34:20 EST 2009
Log message for revision 94473:
Added further docstrings to the `grok.components` module, until a
question occurred to me that I will take to the Grok mailing list.
I will also alert them to the undocumented/untested method I found,
that is marked with an "XXX" in this commit.
Changed:
U grok/trunk/src/grok/components.py
-=-
Modified: grok/trunk/src/grok/components.py
===================================================================
--- grok/trunk/src/grok/components.py 2009-01-03 13:38:18 UTC (rev 94472)
+++ grok/trunk/src/grok/components.py 2009-01-03 14:34:20 UTC (rev 94473)
@@ -86,7 +86,11 @@
This straightforward extension of the basic `grok.Container`
remembers the order in which its keys pairs have been inserted, and
- allows their order to be modified later.
+ allows their order to be modified later. This means that keys and
+ items returned by `keys()`, `values()`, and `items()`, as well as by
+ iterating over the container, will appear in the same order as they
+ were added to the container. The only way of changing the item
+ order in the container is through the method `updateOrder()`.
"""
interface.implements(IOrderedContainer)
@@ -121,6 +125,15 @@
self._order.remove(key)
def updateOrder(self, order):
+ """Impose a new order on the items in this container.
+
+ Items in this container are, by default, returned in the order
+ in which they were inserted. To impose a different ordering on
+ the items instead, provide an `order` argument to this method
+ that is a list containing every key already in the container,
+ but in a new order.
+
+ """
if set(order) != set(self._order):
raise ValueError("Incompatible key set.")
@@ -172,17 +185,47 @@
class LocalUtility(Model):
- pass
+ """The base class for local utilities in Grok applications.
+ By inheriting from this `grok.LocalUtility` class when designing a
+ local utility, Grok application authors accomplish three things.
+ First, this class is knows how to persist itself to the database,
+ which is important because local utilities must be stored in the
+ Zope database alongside the `grok.Site` or `grok.Application` for
+ which they are registered. Second, Grok can deduce the interface
+ that the utility is designed to provide if the utility simply
+ `implements()` one interface (that is not already an interface
+ provided by `grok.LocalUtility`, otherwise Grok cannot tell the
+ difference); this saves the developer from having to supply an
+ explicit `grok.provides()` directive. Third, of course, their code
+ will be easier to read if their local utilities inherit from
+ something with "local utility" in its name.
+ """
+
+
class Annotation(persistent.Persistent):
- pass
+ """The base class for annotation classes in Grok applications."""
class View(grokcore.view.View):
+ """The base class for views in Grok applications.
+
+ Grok automatically registers each subclass of `grok.View` as able to
+ render instances of its `grok.context()` for consumption by web
+ browsers, when a specific `/name` is appended to the context's URL.
+ The name can either be explicitly provided with `grok.name()`, or by
+ default will be the downcased name of the class itself; Grok views
+ with the name ``index`` are used by default if no `/name` is
+ appended to the context's URL.
+
+ """
+ # XXX the above description needs either more detail, or less; I
+ # will ask the Grok mailing list this morning - Brandon
interface.implements(interfaces.IGrokView)
def application_url(self, name=None):
+ """Return the URL of the nearest enclosing `grok.Application`."""
obj = self.context
while obj is not None:
if isinstance(obj, Application):
@@ -191,6 +234,8 @@
raise ValueError("No application found.")
def flash(self, message, type='message'):
+ """Send a short message to the user."""
+ # XXX this has no tests or documentation, anywhere
source = component.getUtility(
z3c.flashmessage.interfaces.IMessageSource, name='session')
source.send(message, type)
More information about the Checkins
mailing list