[Checkins] SVN: grok/trunk/src/grok/components.py Finished adding initial docstrings to components.py. Well, kind of
Brandon Rhodes
brandon at rhodesmill.org
Thu Jan 8 16:06:31 EST 2009
Log message for revision 94663:
Finished adding initial docstrings to components.py. Well, kind of
finished; a few of them, for things like REST and JSON, are woefully
incomplete because I didn't yet go look up those subsystems to say
exactly how they work (all those '++' strings just make my eyes glaze
over).
Also, writing these docstrings made me think more about
cross-referencing; it would be neat to know that cross-references really
worked so that I could just point at a directive and not repeat, over
and over again, the rules that grok.context() uses for finding a context
if you don't use the directive explicitly. Maybe I should go look at
the admin interface or whatever it is that lets you browse the
docstrings. Anyway, for the first time, components.py has some sort of
docstring on every class.
Changed:
U grok/trunk/src/grok/components.py
-=-
Modified: grok/trunk/src/grok/components.py
===================================================================
--- grok/trunk/src/grok/components.py 2009-01-08 20:54:47 UTC (rev 94662)
+++ grok/trunk/src/grok/components.py 2009-01-08 21:06:31 UTC (rev 94663)
@@ -226,10 +226,10 @@
http://example.com/app/folder/object/viewname
- If ``viewname`` might conflict with actual content inside of the
- context (because the context already contains an attribute or item
- named ``viewname``), then the URL can be explicit that it is asking
- for the view by preceding its name with ``@@``::
+ 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
@@ -241,11 +241,11 @@
<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()` 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.
+ 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
@@ -256,21 +256,34 @@
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 should either provide a `render()` method that simply
- returns a document, or should have an accompanying page template.
- Grok will automatically find the correct page template if (a) it is
- in a directory next to the view's module, whose name is the module
- name followed by `_templates`; (b) its filename is the downcased
- name of the view class; and (c) it has an extension (such as ``.pt``
- for Zope Page Templates) that Grok recognizes. Otherwise, the
- developer can name a page template file explicitly with the
- `grok.template()` directive. Before the 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.
+ 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:
- Both `render()` methods and `update()` methods will find the context
- for which the view is being rendered under ``self.context``.
+ * 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``.
+
"""
interface.implements(interfaces.IGrokView)
@@ -292,25 +305,65 @@
class Form(grokcore.formlib.Form, View):
+ """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`
+
+ """
interface.implements(interfaces.IGrokForm)
class AddForm(grokcore.formlib.AddForm, View):
+ """Base class for add forms in Grok applications."""
interface.implements(interfaces.IGrokForm)
class DisplayForm(grokcore.formlib.DisplayForm, View):
+ """Base class for display forms in Grok applications."""
interface.implements(interfaces.IGrokForm)
class EditForm(grokcore.formlib.EditForm, View):
+ """Base class for edit forms in Grok applications."""
interface.implements(interfaces.IGrokForm)
class XMLRPC(object):
- pass
+ """Base class for XML-RPC endpoints in Grok applications.
+ When an application creates a subclass of `grok.XMLRPC`, it is
+ creating an XML-RPC view. Like other Grok views, each `grok.XMLRPC`
+ component can either use an explicit `grok.context()` directive to
+ specify the kind of object it wraps, or else Grok will look through
+ the same module for exactly one `grok.Model` or `grok.Container` (or
+ other `IGrokContext` implementor) and make that class its context
+ instead.
+
+ Every object that is an instance of the wrapped class or interface
+ becomes a legitimate XML-RPC server URL, offering as available
+ procedures whatever methods have been defined inside of that
+ `grok.XMLRPC` component. When a method is called over XML-RPC, any
+ parameters are translated into normal Python data types and supplied
+ as normal positional arguments. When the method returns a value or
+ raises an exception, the result is converted back into an XML-RPC
+ response for the client. In both directions, values are marshalled
+ transparently to and from XML-RPC data structures.
+
+ During the execution of an XML-RPC method, the object whose URL was
+ used for the XML-RPC call is available as ``self.context``.
+
+ """
+
+
class REST(zope.location.Location):
+ """Base class for REST views in Grok applications."""
interface.implements(interfaces.IREST)
def __init__(self, context, request):
@@ -322,9 +375,11 @@
def response(self):
return self.request.response
+
class JSON(BrowserPage):
+ """Base class for JSON views in Grok applications."""
interface.implements(interfaces.IGrokSecurityView)
-
+
def __call__(self):
view_name = self.__view_name__
method = getattr(self, view_name)
@@ -333,6 +388,7 @@
class Traverser(object):
+ """Base class for traversers in Grok applications."""
interface.implements(IBrowserPublisher)
def __init__(self, context, request):
@@ -385,6 +441,14 @@
class ContextTraverser(Traverser):
+ """Base class for context traversers in Grok applications.
+
+ A context traverser is like a normal `grok.Traverser` but, instead
+ of supplying its own `traverse()` method, it directs Grok to go call
+ the ``traverse()`` method on the context itself in order to process
+ the next name in the URL.
+
+ """
component.adapts(interfaces.IContext, IHTTPRequest)
def traverse(self, name):
@@ -394,6 +458,15 @@
class ContainerTraverser(Traverser):
+ """Base class for container traversers in Grok applications.
+
+ A container traverser is like a normal `grok.Traverser` but, instead
+ of supplying its own ``traverse()`` method, Grok will either call
+ the ``traverse()`` method on the context itself, if any, else call
+ ``get()`` on the container (a getitem-style lookup) in order to
+ resolve the next name in the URL.
+
+ """
component.adapts(interfaces.IContainer, IHTTPRequest)
def traverse(self, name):
@@ -407,6 +480,36 @@
class IndexesClass(object):
+ """Base class for index collections in a Grok application.
+
+ A `grok.Indexes` utility provides one or more Zope Database content
+ indexes for use in a `grok.Site` or `grok.Application`. The site or
+ application that the indexes are intended for should be named with
+ the `grok.site()` directive, and the kind of object to index should
+ be named with a `grok.context()` directive.
+
+ Inside their class, the developer should specify one or more
+ `grok.index.Field` instances naming object attributes that should be
+ indexed (and therefore searchable)::
+
+ class ArticleIndex(grok.Indexes):
+ grok.site(Newspaper)
+ grok.context(Article)
+ author = index.Field()
+ title = index.Field()
+ body = index.Text()
+
+ See the `grok.index` module for more information on field types.
+
+ Note that indexes are persistent: they are stored in the Zope
+ database alongside the site or application that they index. They
+ are created when the site or application is first created, and so an
+ already-created site will not change just because the definition of
+ one of its `grok.Indexes` changes; it will either have to be deleted
+ and re-created, or some other operation performed to bring its
+ indexes up to date.
+
+ """
def __init__(self, name, bases=(), attrs=None):
if attrs is None:
return
@@ -429,6 +532,15 @@
class Role(securitypolicy_Role):
- pass
+ """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')
+
+ """
More information about the Checkins
mailing list