[Zope3-checkins] SVN: Zope3/trunk/src/zope/ Merge ReSTification and
consistency changes from ZopeX3-3.0 branch.
Fred L. Drake, Jr.
fred at zope.com
Fri Jul 16 17:14:43 EDT 2004
Log message for revision 26600:
Merge ReSTification and consistency changes from ZopeX3-3.0 branch.
This includes changes from revisions 26583 - 26589 (inclusive).
Changed:
U Zope3/trunk/src/zope/app/README.txt
U Zope3/trunk/src/zope/app/apidoc/README.txt
U Zope3/trunk/src/zope/app/apidoc/TODO.txt
U Zope3/trunk/src/zope/app/form/browser/README.txt
U Zope3/trunk/src/zope/app/form/browser/complexsample/README.txt
U Zope3/trunk/src/zope/app/form/browser/widgets.txt
U Zope3/trunk/src/zope/app/ftp/README.txt
U Zope3/trunk/src/zope/app/locales/README.txt
U Zope3/trunk/src/zope/app/locales/TRANSLATE.txt
U Zope3/trunk/src/zope/app/observable/README.txt
U Zope3/trunk/src/zope/app/pluggableauth/README.txt
U Zope3/trunk/src/zope/app/registration/README.txt
U Zope3/trunk/src/zope/app/sqlscript/README.txt
U Zope3/trunk/src/zope/app/tree/CHANGES.txt
U Zope3/trunk/src/zope/app/tree/README.txt
U Zope3/trunk/src/zope/app/tree/TODO.txt
U Zope3/trunk/src/zope/event/README.txt
U Zope3/trunk/src/zope/i18n/locales/README.txt
U Zope3/trunk/src/zope/interface/README.txt
U Zope3/trunk/src/zope/interface/adapter.txt
U Zope3/trunk/src/zope/interface/tests/foodforthought.txt
U Zope3/trunk/src/zope/schema/fields.txt
-=-
Modified: Zope3/trunk/src/zope/app/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,7 +1,8 @@
Zope application server
+-----------------------
-This package, the zope.app package, contains the packages and other
-modules that are specific to the Zope application server. These
-packages and modules are not usable outside of Zope. If there's
-something in zope.app you want to use elsewhere, let us know and we
-can talk about abstracting some of it up out of zope.app.
+This package, the `zope.app` package, contains the packages and other
+modules that are specific to the Zope application server. These
+packages and modules are not usable outside of Zope. If there's
+something in `zope.app` you want to use elsewhere, let us know and we
+can talk about abstracting some of it up out of `zope.app`.
Modified: Zope3/trunk/src/zope/app/apidoc/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/apidoc/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -9,25 +9,26 @@
Developing a Module
-------------------
- 1. Implement a class that realizes the 'IDocumentationModule' interface.
+1. Implement a class that realizes the `IDocumentationModule`
+ interface.
- 2. Register this class as a utility using something like this::
+2. Register this class as a utility using something like this::
- <utility
- provides="zope.app.apidoc.interfaces.IDocumentationModule"
- factory=".examplemodule.ExampleModule"
- name="Example" />
+ <utility
+ provides="zope.app.apidoc.interfaces.IDocumentationModule"
+ factory=".examplemodule.ExampleModule"
+ name="Example" />
- 3. Take care of security by allowing at least 'IDocumentationModule':
+3. Take care of security by allowing at least `IDocumentationModule`::
- <class class=".ExampleModule">
- <allow interface="zope.app.apidoc.interfaces.IDocumentationModule" />
- </class>
+ <class class=".ExampleModule">
+ <allow interface="zope.app.apidoc.interfaces.IDocumentationModule" />
+ </class>
- 4. Provide a browser view called 'menu.html'.
+4. Provide a browser view called ``menu.html``.
- 5. Provide another view, usually 'index.html', that can show the details for
- the various menu items.
+5. Provide another view, usually ``index.html``, that can show the
+ details for the various menu items.
- Note: There are several modules that come with the product. Just look in
- them for some guidance.
+Note: There are several modules that come with the product. Just look
+in them for some guidance.
Modified: Zope3/trunk/src/zope/app/apidoc/TODO.txt
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/TODO.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/apidoc/TODO.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,6 +1,6 @@
TO DO
=====
- - better README.txt
+- better README.txt
- - Refactor some of the views, so that templates can be reused
+- Refactor some of the views, so that templates can be reused
Modified: Zope3/trunk/src/zope/app/form/browser/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/form/browser/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -3,10 +3,10 @@
===============
This directory contains widgets: views on bound schema fields. Many of these
-are straightforward. For instance, see the TextWidget in textwidgets.py, which
-is a subclass of BrowserWidget in widget.py. It is registered as an
-IBrowserRequest view of an ITextLine schema field, providing the IInputWidget
-interface::
+are straightforward. For instance, see the `TextWidget` in textwidgets.py,
+which is a subclass of BrowserWidget in widget.py. It is registered as an
+`IBrowserRequest` view of an `ITextLine` schema field, providing the
+`IInputWidget` interface::
<view
type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -17,26 +17,26 @@
/>
The widget then receives the field and the request as arguments to the factory
-(i.e., the TextWidget class).
+(i.e., the `TextWidget` class).
Some widgets in Zope 3 extend this pattern. This extension is configurable:
simply do not load the zope/app/form/browser/configure.zcml file if you do not
wish to participate in the extension. The widget registration is extended for
-Choice fields and for the collection fields.
+`Choice` fields and for the collection fields.
Default Choice Field Widget Registration and Lookup
===================================================
As described above, all field widgets are obtained by looking up a browser
-IInputWidget or IDisplayWidget view for the field object. For Choice fields,
-the default registered widget defers all of its behavior to the result of
-another lookup: a browser widget view for the field *and* the Choice field's
+`IInputWidget` or `IDisplayWidget` view for the field object. For `Choice`
+fields, the default registered widget defers all of its behavior to the result
+of another lookup: a browser widget view for the field *and* the Choice field's
vocabulary.
This allows registration of Choice widgets that differ on the basis of the
vocabulary type. For example, a widget for a vocabulary of images might have
a significantly different user interface than a widget for a vocabulary of
-words. A dynamic vocabulary might implement IIterableVocabulary if its
+words. A dynamic vocabulary might implement `IIterableVocabulary` if its
contents are below a certain length, but not implement the marker "iterable"
interface if the number of possible values is above the threshhold.
@@ -45,12 +45,12 @@
arguments, choice widgets receive the field, vocabulary, and request as
arguments.
-Some Choice widgets may also need to provide a query interface, particularly if
-the number of items in the vocabulary are too big to iterate. The vocabulary
+Some `Choice` widgets may also need to provide a query interface,
+particularly if the vocabulary is too big to iterate over. The vocabulary
may provide a query which implements an interface appropriate for that
vocabulary. You then can register a query view--a view registered for the
query interface and the field interface--that implements
-zope.app.forms.browser.interfaces.IVocabularyQueryView.
+`zope.app.forms.browser.interfaces.IVocabularyQueryView`.
Default Collection Field Widget Registration and Lookup
=======================================================
@@ -58,36 +58,36 @@
The default configured lookup for collection fields--List, Tuple, and Set, for
instance--begins with the usual lookup for a browser widget view for the
field object. This widget defers its display to the result of another lookup:
-a browser widget view registered for the field and the field's value_type (the
-type of the contained values). This allows registrations for collection
+a browser widget view registered for the field and the field's `value_type`
+(the type of the contained values). This allows registrations for collection
widgets that differ on the basis of the members--a widget for entering a list
of text strings might differ significantly from a widget for entering a list of
dates...or even a list of choices, as discussed below.
This registration pattern has three implications that should be highlighted.
- * First, collection fields that do not specify a value_type probably cannot
- have a reasonable widget.
+* First, collection fields that do not specify a `value_type` probably cannot
+ have a reasonable widget.
- * Second, collection widgets that wish to be the default widget for a
- collection with any value_type should be registered for the collection
- field and a generic value_type: the IField interface. Do not register the
- generic widget for the collection field only or you will break the lookup
- behavior as described here.
-
- * Third, like choice widget factories, sequence widget factories (classes or
- functions) take three arguments. Typical sequence widgets receive the
- field, the value_type, and the request as arguments.
+* Second, collection widgets that wish to be the default widget for a
+ collection with any `value_type` should be registered for the collection
+ field and a generic value_type: the `IField` interface. Do not register the
+ generic widget for the collection field only or you will break the lookup
+ behavior as described here.
+* Third, like choice widget factories, sequence widget factories (classes or
+ functions) take three arguments. Typical sequence widgets receive the
+ field, the `value_type`, and the request as arguments.
+
Collections of Choices
----------------------
-If a collection field's value_type is a Choice field, the second widget again
-defers its behavior, this time to a third lookup based on the collection field
-and the choice's vocabulary. This means that a widget for a list of large
-image choices can be different than a widget for a list of small image choices
-(with a different vocabulary interface), different from a widget for a list of
-keyword choices, and different from a set of keyword choices.
+If a collection field's `value_type` is a `Choice` field, the second widget
+again defers its behavior, this time to a third lookup based on the collection
+field and the choice's vocabulary. This means that a widget for a list of
+large image choices can be different than a widget for a list of small image
+choices (with a different vocabulary interface), different from a widget for a
+list of keyword choices, and different from a set of keyword choices.
Some advanced applications may wish to do a further lookup on the basis of the
unique attribute of the collection field--perhaps looking up a named view with
@@ -105,7 +105,7 @@
The only hard requirement is that the developer must register the bag + choice
widget: the widget is just the factory for the third dispatch as described
-above, so the developer can use the already implemented widgets listed below.
+above, so the developer can use the already implemented widgets listed below::
<view
type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -127,7 +127,7 @@
Beyond this, the developer may also have a generic bag widget she wishes to
register. This might look something like this, assuming there's a
-BagSequenceWidget available in this package::
+`BagSequenceWidget` available in this package::
<view
type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -139,8 +139,8 @@
/>
Then any widgets for the bag and a vocabulary would be registered according to
-this general pattern, in which IIterableVocabulary would be the interface of
-any appropriate vocabulary and BagWidget is some appropriate widget::
+this general pattern, in which `IIterableVocabulary` would be the interface of
+any appropriate vocabulary and `BagWidget` is some appropriate widget::
<view
type="zope.publisher.interfaces.browser.IBrowserRequest"
Modified: Zope3/trunk/src/zope/app/form/browser/complexsample/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/complexsample/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/form/browser/complexsample/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -20,7 +20,7 @@
kind of query behaviors the sample widget expects.
widgetapi.py
- Alternate base implementation of the IBrowserWidget interface.
+ Alternate base implementation of the `IBrowserWidget` interface.
This completely bypasses the implementation from the
- zope.app.form.browser.widget module, and is really designed for
+ `zope.app.form.browser.widget` module, and is really designed for
use with widgets of the sort demonstrated in this package.
Modified: Zope3/trunk/src/zope/app/form/browser/widgets.txt
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/widgets.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/form/browser/widgets.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -5,14 +5,14 @@
zope/app/demo/poll) which has poll options defined as:
label
- A TextLine holding the label of the option
+ A `TextLine` holding the label of the option
description
- Another TextLine holding the description of the option
+ Another `TextLine` holding the description of the option
Simple stuff.
-Our Poll product holds an editable list of the PollOption instances. This
-is shown in the ``poll.py`` source below::
+Our Poll product holds an editable list of the `PollOption` instances.
+This is shown in the ``poll.py`` source below::
from persistent import Persistent
from interfaces import IPoll, IPollOption
@@ -42,7 +42,7 @@
options = property(get_options, set_options, None, 'fiddle options')
-And the Schemas are define in the ``interfaces.py`` file below::
+And the Schemas are defined in the ``interfaces.py`` file below::
from zope.interface import Interface
from zope.schema import Object, Tuple, TextLine
@@ -63,10 +63,11 @@
def choose(option): 'user chooses an option'
-Note the use of the Tuple and Object schema fields above. The Tuple
-could optionally have restrictions on the min or max number of items -
-these will be enforce by the SequenceWidget form handling code. The Object
-must specify the schema that is used to generate its data.
+Note the use of the `Tuple` and `Object` schema fields above. The
+`Tuple` could optionally have restrictions on the min or max number of
+items - these will be enforced by the `SequenceWidget` form handling
+code. The `Object` must specify the schema that is used to generate its
+data.
Now we have to specify the actual add and edit views. We use the existing
AddView and EditView, but we pre-define the widget for the sequence because
@@ -107,20 +108,20 @@
options_widget = sw
-Note the creation of the widget via a CustomWidgetFactory. So,
+Note the creation of the widget via a `CustomWidgetFactory`. So,
whenever the options_widget is used, a new
``SequenceWidget(subwidget=CustomWidgetFactory(ObjectWidget,
PollOption))`` is created. The subwidget argument indicates that each
item in the sequence should be represented by the indicated widget
instead of their default. If the contents of the sequence were just
-Text Fields, then the default would be just fine - the only odd cases
+`Text` fields, then the default would be just fine - the only odd cases
are Sequence and Object Widgets because they need additional arguments
when they're created.
Each item in the sequence will be represented by a
``CustomWidgetFactory(ObjectWidget, PollOption)`` - thus a new
``ObjectWidget(context, request, PollOption)`` is created for each
-one. The PollOption class ("factory") is used to create new instances
+one. The `PollOption` class ("factory") is used to create new instances
when new data is created in add forms (or edit forms when we're adding
new items to a Sequence).
@@ -190,10 +191,10 @@
</configure>
-Note the use of the "class" argument to the addform and editform
-directives. Otherwise, nothing much exciting here.
+Note the use of the ``class`` attribute on the ``addform`` and
+``editform`` elements. Otherwise, nothing much exciting here.
-Finally, we have some additiona views...
+Finally, we have some additional views...
``results.zpt``::
Modified: Zope3/trunk/src/zope/app/ftp/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/ftp/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/ftp/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,26 +1,26 @@
+=====================
+How FTP Works in Zope
+=====================
-Here are some notes about the way FTP actually works in zope.
+- The FTP server implementation is in `zope.server.ftp.server`. See
+ the README.txt file there.
- - The FTP server implementation is in zope.server.ftp.server. See
- the README.txt file there.
+ The publisher-based ftp server is in `zope.server.ftp.publisher`.
- The publisher-based ftp server is in zope.server.ftp.publisher.
+ The FTP server gets wired up with a request factory that creates
+ ftp requests with ftp publication objects.
- The FTP server gets wired up with a request factory that creates
- ftp requests with ftp publication objects.
+- The ftp request object is defined in `zope.publisher.ftp`.
- - The ftp request object is defined in zope.publisher.ftp.
+- The ftp publication object is defined in `zope.app.publication.ftp`.
- - The ftp publication object is defined in zope.app.publication.ftp.
+ The publication object gets views to handle ftp requests. It
+ looks up a separate view for each method defined in
+ `zope.publisher.interfaces.ftp.IFTPPublisher`.
- The publication object gets views to handle ftp requests. It
- looks up a separate view for each method defined in
- zope.publisher.interfaces.ftp.IFTPPublisher.
+ We provide a single class here that implements all of these methods.
- We provide a single class here that implements all of these
- methods.
+ The view, in turn, uses adapters for the `IReadFile`, `IWriteFile`,
+ `IReadDirectory`, `IWriteDirectory`, `IFileFactory`, and
+ `IDirectoryFactory`, defined in `zope.app.filerepresentation.interfaces`.
- The view, in turn, uses adapters for the IReadFile, IWriteFile,
- IReadDirectory, IWriteDirectory, IFileFactory, and
- IDirectoryFactory, defined in zope.app.filerepresentation.interfaces.
-
Modified: Zope3/trunk/src/zope/app/locales/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/locales/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/locales/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,6 +1,6 @@
Software translation files
==========================
-This directory containes translation files and utilities for
-translating the software strings for the zope application server
+This directory contains translation files and utilities for
+translating the software strings for the Zope application server
software.
Modified: Zope3/trunk/src/zope/app/locales/TRANSLATE.txt
===================================================================
--- Zope3/trunk/src/zope/app/locales/TRANSLATE.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/locales/TRANSLATE.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,31 +1,33 @@
+===================================================
Internationalization (I18n) and Localization (L10n)
-=====================================================
+===================================================
- Creating/Updating Message Catalog Template (POT) Files
- -----------------------------------------------------
- 1. Execute i18nextract.py from ZOPE/utilities directory::
+Creating/Updating Message Catalog Template (POT) Files
+------------------------------------------------------
- python2.3 i18nextract.py
+1. Execute i18nextract.py from Zope's utilities/ directory::
+ python2.3 i18nextract.py
- Updating Message Catalog (PO) Files
- -----------------------------------
- 1. For each language do simply::
+Updating Message Catalog (PO) Files
+------------------------------------
- msgmerge -U de/LC_MESSAGES/zope.po zope.pot
+1. For each language do simply::
- 2. Translate the updated PO file.
- Note: KBabel is a great tool for this task!
+ msgmerge -U de/LC_MESSAGES/zope.po zope.pot
+2. Translate the updated PO file.
+ Note: KBabel is a great tool for this task!
- Compiling Message Catalogs (PO) to binary (MO) Files
- ----------------------------------------------------
- 1. Go to the right directory, such as
- 'zope/app/locales/de/LC_MESSAGES'.
+Compiling Message Catalogs (PO) to binary (MO) Files
+----------------------------------------------------
- 2. Run the following command::
+1. Go to the right directory, such as
+ zope/app/locales/de/LC_MESSAGES.
- msgfmt -o zope.mo zope.po
+2. Run the following command::
+
+ msgfmt -o zope.mo zope.po
Modified: Zope3/trunk/src/zope/app/observable/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/observable/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/observable/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -8,20 +8,13 @@
The package provides an event channel for dispatching events to the
appropriate instance as well as an adapter from IAnnotatable to
-IObservable. This is important because an object must support
-IAnnotatable (and therefore IAnnotations) in order to support
+`IObservable`. This is important because an object must support
+`IAnnotatable` (and therefore `IAnnotations`) in order to support
instance-based subscriptions.
Subscriptions for a particular instance are stored in the instance's
-annotations, in a key defined in zope.app.observable.observable.key
+annotations, in a key defined in `zope.app.observable.observable.key`
(currently 'zope.app.observable'). The annotation stored in the key
is actually an Observers object, which is a local registry that is not
aware of the global registry in any way. More information on the
Observers object is available in observers.txt.
-
-
-
-
-
-
-$Id$
Modified: Zope3/trunk/src/zope/app/pluggableauth/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/pluggableauth/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/pluggableauth/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,8 +1,10 @@
-$Id$
+=================================
+New Authentication Service Design
+=================================
-The current implementation will be replaced. Following is design
+The current implementation will be replaced. The following is a design
I came up with together with Jim Fulton.
- -- itamar
+-- itamar
Note that this design is implemented (in some form) by the pluggable
auth service. This document needs to be updated to reflect the final
@@ -10,49 +12,56 @@
Design notes for new AuthenticationService
-==========================================
+------------------------------------------
The service contains a list of user sources. They implement interfaces,
-starting with:
+starting with::
class IUserPassUserSource:
"""Authenticate using username and password."""
+
def authenticate(username, password):
"Returns boolean saying if such username/password pair exists"
class IDigestSupportingUserSource(IUserPassUserSource):
"""Allow fetching password, which is required by digest auth methods"""
+
def getPassword(username):
"Return password for username"
-etc.. Probably there will be others as well, for dealing with certificate
-authentication and what not. Probably we need to expand above interfaces
+etc. Probably there will be others as well, for dealing with certificate
+authentication and what not. Probably we need to expand above interfaces
to deal with principal titles and descriptions, and so on.
-A login method - cookie auth, HTTP basic auth, digest auth, FTP auth,
+A login method (cookie auth, HTTP basic auth, digest auth, FTP auth),
is registered as a view on one of the above interfaces.
+::
class ILoginMethodView:
+
def authenticate():
"""Return principal for request, or None."""
+
def unauthorized():
"""Tell request that a login is required."""
-The authentication service is then implemented something like this:
+The authentication service is then implemented something like this::
- class AuthenticationService:
- def authenticate(self, request):
- for us in self.userSources:
- loginView = getView(self, us, "login", request)
- principal = loginView.authenticate()
- if principal is not None:
- return principal
- def unauthorized(self, request):
- loginView = getView(self, self.userSources[0], request)
- loginView.unauthorized()
+ class AuthenticationService:
+
+ def authenticate(self, request):
+ for us in self.userSources:
+ loginView = getView(self, us, "login", request)
+ principal = loginView.authenticate()
+ if principal is not None:
+ return principal
+
+ def unauthorized(self, request):
+ loginView = getView(self, self.userSources[0], request)
+ loginView.unauthorized()
Modified: Zope3/trunk/src/zope/app/registration/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/registration/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/registration/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -76,25 +76,21 @@
There are several major concepts/terms that need to be understood
-- Registerables
-
+Registerables
Registerables are objects that can be registered. They implement the
`IRegisterable` interface.
-- Registries
-
+Registries
Registeries are objects that registerables are registered with.
Typically, these are component-management services like the adapter
or utility service.
-- Registration objects
-
+Registration objects
Registration objects store data about registrations. They store
registration data and represent the relationship between registries
and registerables.
-- Registration managers
-
+Registration managers
Registration managers are containers for managing registrations.
Registrations are stored in registration managers. All of the
registrations for objects stored in a site-management folder are
@@ -103,8 +99,7 @@
this so that the registration manager is exposed as a folder tab
rather than as an item.
-- Registration stack
-
+Registration stack
Registries allow multiple registrations for the same set of
registration parameters. At most one registration for a set of
parameters can be active at one time, but multiple registrations are
@@ -125,8 +120,7 @@
registration object passed need not be in in the stack. It is used
soley to provide the parameters.
-- Registered
-
+Registered
The interface `IRegistered` provides storage and access to the
registrations for a registerable. When we make a registration, we
refer to it in a registration stack and in the registered object.
Modified: Zope3/trunk/src/zope/app/sqlscript/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/sqlscript/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/sqlscript/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,131 +1,137 @@
+=======================================
Using additional DTML tags in SQLScript
+=======================================
- Inserting optional tests with 'sqlgroup'
+Inserting optional tests with 'sqlgroup'
+----------------------------------------
- It is sometimes useful to make inputs to an SQL statement
- optinal. Doing so can be difficult, because not only must the
- test be inserted conditionally, but SQL boolean operators may or
- may not need to be inserted depending on whether other, possibly
- optional, comparisons have been done. The 'sqlgroup' tag
- automates the conditional insertion of boolean operators.
+It is sometimes useful to make inputs to an SQL statement optinal.
+Doing so can be difficult, because not only must the test be inserted
+conditionally, but SQL boolean operators may or may not need to be
+inserted depending on whether other, possibly optional, comparisons
+have been done. The 'sqlgroup' tag automates the conditional
+insertion of boolean operators.
- The 'sqlgroup' tag is a block tag that has no attributes. It can
- have any number of 'and' and 'or' continuation tags.
+The 'sqlgroup' tag is a block tag that has no attributes. It can have
+any number of 'and' and 'or' continuation tags.
- Suppose we want to find all people with a given first or nick name
- and optionally constrain the search by city and minimum and
- maximum age. Suppose we want all inputs to be optional. We can
- use DTML source like the following::
+Suppose we want to find all people with a given first or nick name and
+optionally constrain the search by city and minimum and maximum age.
+Suppose we want all inputs to be optional. We can use DTML source
+like the following::
- <dtml-sqlgroup>
- <dtml-sqlgroup>
- <dtml-sqltest name column=nick_name type=nb multiple optional>
- <dtml-or>
- <dtml-sqltest name column=first_name type=nb multiple optional>
- </dtml-sqlgroup>
- <dtml-and>
- <dtml-sqltest home_town type=nb optional>
- <dtml-and>
- <dtml-if minimum_age>
- age >= <dtml-sqlvar minimum_age type=int>
- </dtml-if>
- <dtml-and>
- <dtml-if maximum_age>
- age <= <dtml-sqlvar maximum_age type=int>
- </dtml-if>
- </dtml-sqlgroup>
+ <dtml-sqlgroup>
+ <dtml-sqlgroup>
+ <dtml-sqltest name column=nick_name type=nb multiple optional>
+ <dtml-or>
+ <dtml-sqltest name column=first_name type=nb multiple optional>
+ </dtml-sqlgroup>
+ <dtml-and>
+ <dtml-sqltest home_town type=nb optional>
+ <dtml-and>
+ <dtml-if minimum_age>
+ age >= <dtml-sqlvar minimum_age type=int>
+ </dtml-if>
+ <dtml-and>
+ <dtml-if maximum_age>
+ age <= <dtml-sqlvar maximum_age type=int>
+ </dtml-if>
+ </dtml-sqlgroup>
- This example illustrates how groups can be nested to control
- boolean evaluation order. It also illustrates that the grouping
- facility can also be used with other DTML tags like 'if' tags.
+This example illustrates how groups can be nested to control boolean
+evaluation order. It also illustrates that the grouping facility can
+also be used with other DTML tags like 'if' tags.
- The 'sqlgroup' tag checks to see if text to be inserted contains
- other than whitespace characters. If it does, then it is inserted
- with the appropriate boolean operator, as indicated by use of an
- 'and' or 'or' tag, otherwise, no text is inserted.
+The 'sqlgroup' tag checks to see if text to be inserted contains other
+than whitespace characters. If it does, then it is inserted with the
+appropriate boolean operator, as indicated by use of an 'and' or 'or'
+tag, otherwise, no text is inserted.
- Inserting optional tests with 'sqlgroup'
+Inserting optional tests with 'sqlgroup'
+----------------------------------------
- It is sometimes useful to make inputs to an SQL statement
- optinal. Doing so can be difficult, because not only must the
- test be inserted conditionally, but SQL boolean operators may or
- may not need to be inserted depending on whether other, possibly
- optional, comparisons have been done. The 'sqlgroup' tag
- automates the conditional insertion of boolean operators.
+It is sometimes useful to make inputs to an SQL statement optinal.
+Doing so can be difficult, because not only must the test be inserted
+conditionally, but SQL boolean operators may or may not need to be
+inserted depending on whether other, possibly optional, comparisons
+have been done. The 'sqlgroup' tag automates the conditional
+insertion of boolean operators.
- The 'sqlgroup' tag is a block tag. It can
- have any number of 'and' and 'or' continuation tags.
+The 'sqlgroup' tag is a block tag. It can have any number of 'and' and
+'or' continuation tags.
- The 'sqlgroup' tag has an optional attribure, 'required' to
- specify groups that must include at least one test. This is
- useful when you want to make sure that a query is qualified, but
- want to be very flexible about how it is qualified.
+The 'sqlgroup' tag has an optional attribure, 'required' to specify
+groups that must include at least one test. This is useful when you
+want to make sure that a query is qualified, but want to be very
+flexible about how it is qualified.
- Suppose we want to find people with a given first or nick name,
- city or minimum and maximum age. Suppose we want all inputs to be
- optional, but want to require *some* input. We can
- use DTML source like the following::
+Suppose we want to find people with a given first or nick name, city
+or minimum and maximum age. Suppose we want all inputs to be
+optional, but want to require *some* input. We can use DTML source
+like the following::
- <dtml-sqlgroup required>
- <dtml-sqlgroup>
- <dtml-sqltest name column=nick_name type=nb multiple optional>
- <dtml-or>
- <dtml-sqltest name column=first_name type=nb multiple optional>
- </dtml-sqlgroup>
- <dtml-and>
- <dtml-sqltest home_town type=nb optional>
- <dtml-and>
- <dtml-if minimum_age>
- age >= <dtml-sqlvar minimum_age type=int>
- </dtml-if>
- <dtml-and>
- <dtml-if maximum_age>
- age <= <dtml-sqlvar maximum_age type=int>
- </dtml-if>
- </dtml-sqlgroup>
+ <dtml-sqlgroup required>
+ <dtml-sqlgroup>
+ <dtml-sqltest name column=nick_name type=nb multiple optional>
+ <dtml-or>
+ <dtml-sqltest name column=first_name type=nb multiple optional>
+ </dtml-sqlgroup>
+ <dtml-and>
+ <dtml-sqltest home_town type=nb optional>
+ <dtml-and>
+ <dtml-if minimum_age>
+ age >= <dtml-sqlvar minimum_age type=int>
+ </dtml-if>
+ <dtml-and>
+ <dtml-if maximum_age>
+ age <= <dtml-sqlvar maximum_age type=int>
+ </dtml-if>
+ </dtml-sqlgroup>
- This example illustrates how groups can be nested to control
- boolean evaluation order. It also illustrates that the grouping
- facility can also be used with other DTML tags like 'if' tags.
+This example illustrates how groups can be nested to control boolean
+evaluation order. It also illustrates that the grouping facility can
+also be used with other DTML tags like 'if' tags.
- The 'sqlgroup' tag checks to see if text to be inserted contains
- other than whitespace characters. If it does, then it is inserted
- with the appropriate boolean operator, as indicated by use of an
- 'and' or 'or' tag, otherwise, no text is inserted.
+The 'sqlgroup' tag checks to see if text to be inserted contains other
+than whitespace characters. If it does, then it is inserted with the
+appropriate boolean operator, as indicated by use of an 'and' or 'or'
+tag, otherwise, no text is inserted.
- Inserting values with the 'sqlvar' tag
+Inserting values with the 'sqlvar' tag
+--------------------------------------
- The 'sqlvar' tag is used to type-safely insert values into SQL
- text. The 'sqlvar' tag is similar to the 'var' tag, except that
- it replaces text formatting parameters with SQL type information.
+The 'sqlvar' tag is used to type-safely insert values into SQL text.
+The 'sqlvar' tag is similar to the 'var' tag, except that it replaces
+text formatting parameters with SQL type information.
- The sqlvar tag has the following attributes:
+The sqlvar tag has the following attributes:
- name -- The name of the variable to insert. As with other
- DTML tags, the 'name=' prefix may be, and usually is,
- ommitted.
+`name`
+ The name of the variable to insert. As with other DTML tags, the
+ 'name=' prefix may be, and usually is, ommitted.
- type -- The data type of the value to be inserted. This
- attribute is required and may be one of 'string',
- 'int', 'float', or 'nb'. The 'nb' data type indicates a
- string that must have a length that is greater than 0.
+`type`
+ The data type of the value to be inserted. This attribute is
+ required and may be one of 'string', 'int', 'float', or 'nb'. The
+ 'nb' data type indicates a string that must have a length that is
+ greater than 0.
- optional -- A flag indicating that a value is optional. If a
- value is optional and is not provided (or is blank
- when a non-blank value is expected), then the string
- 'null' is inserted.
+`optional`
+ A flag indicating that a value is optional. If a value is optional
+ and is not provided (or is blank when a non-blank value is
+ expected), then the string 'null' is inserted.
- For example, given the tag::
+For example, given the tag::
- <dtml-sqlvar x type=nb optional>
+ <dtml-sqlvar x type=nb optional>
- if the value of 'x' is::
+if the value of 'x' is::
- Let\'s do it
+ Let\'s do it
- then the text inserted is:
+then the text inserted is:
- 'Let''s do it'
+ 'Let''s do it'
- however, if x is ommitted or an empty string, then the value
- inserted is 'null'.
+however, if x is ommitted or an empty string, then the value inserted
+is 'null'.
Modified: Zope3/trunk/src/zope/app/tree/CHANGES.txt
===================================================================
--- Zope3/trunk/src/zope/app/tree/CHANGES.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/tree/CHANGES.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,3 +1,4 @@
+=======
CHANGES
=======
@@ -2,46 +3,50 @@
v1.2 (2004-02-19) -- 'Scruffy'
+------------------------------
- - Moved to zope.app.tree
+- Moved to `zope.app.tree`
- - It is now called 'ZopeTree' again. Hoorray!
+- It is now called 'ZopeTree' again. Hoorray!
- - Refactored browser stuff into its own browser subpackage.
+- Refactored browser stuff into its own browser subpackage.
- - Separated the handling of tree state from the cookie functionality
- to provide a base class for views based on other tree state sources.
+- Separated the handling of tree state from the cookie functionality
+ to provide a base class for views based on other tree state sources.
v1.1 (2004-02-16) -- 'Zapp'
+---------------------------
- - Added support for displaying lines in a tree (Stephan Richter)
+- Added support for displaying lines in a tree (Stephan Richter)
- + Changes in Node.getFlatDict() to provide more data. Removed
- 'depth' from node info, but added 'row-state' and
- 'last-level-node'. Changed interface and test accordingly.
+ - Changes in `Node.getFlatDict()` to provide more data. Removed
+ 'depth' from node info, but added 'row-state' and
+ 'last-level-node'. Changed interface and test accordingly.
- + Updated templates for StaticTree skin and example. Note that
- third party templates from 1.0.x will not work anymore and must be
- updated as well!
+ - Updated templates for `StaticTree` skin and example. Note that
+ third party templates from 1.0.x will not work anymore and must be
+ updated as well!
v1.0.1 (2004-01-16) -- 'Nibbler'
+--------------------------------
- - Added last remaining pieces for unit tests
+- Added last remaining pieces for unit tests
- - Updated documentation
+- Updated documentation
- - Rounded some rough edges in the skin
+- Rounded some rough edges in the skin
- - Integrated it into the Zope3 distribution below the zope.products
- package
+- Integrated it into the Zope3 distribution below the `zope.products`
+ package
v1.0 (2003-11-24) -- 'Lur'
+--------------------------
- - Ported to Zope 3
+- Ported to Zope 3
- - Renamed it to 'statictree'
+- Renamed it to 'statictree'
- - Much more unit tests
+- Much more unit tests
- - Added filter functionality
+- Added filter functionality
- - Provided sample implementations as well as an alternate
- rotterdam-like skin using the static tree
+- Provided sample implementations as well as an alternate
+ rotterdam-like skin using the static tree
Modified: Zope3/trunk/src/zope/app/tree/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/tree/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/tree/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -8,9 +8,9 @@
ZopeTree is a port of Philipp's Zope2 product ZopeTree. ZopeTree was
meant to be a light-weight and easy-to-use static tree implementation,
mainly designed for use in ZPTs. It was originally written because
-Zope2's ZTUtils.Tree was found to be too complicated and inflexible.
+Zope2's `ZTUtils.Tree` was found to be too complicated and inflexible.
-The ZTUtils package has not been ported to Zope3. Parts of it, like
+The `ZTUtils` package has not been ported to Zope3. Parts of it, like
batching, have found their way into Zope3, though. Only support for
static tree generation is not in the core.
@@ -19,7 +19,7 @@
-------------
Using the skin
---------------
+~~~~~~~~~~~~~~
ZopeTree comes with a pre-defined skin, StaticTree. It looks just
like Zope3's default skin, Rotterdam, except that it displays a static
@@ -27,18 +27,21 @@
tree.
Using predefined views on objects
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ZopeTree comes with several predefined views:
-- cookie_tree: simple view using cookies for tree state storage.
+`cookie_tree`
+ simple view using cookies for tree state storage.
-- folder_cookie_tree: same as above, however only showing folders.
+`folder_cookie_tree`
+ same as above, however only showing folders.
-- site_cookie_tree: same as above, with the nearest site as root node.
+`site_cookie_tree`
+ same as above, with the nearest site as root node.
-- root_cookie_tree: same as above, with the root container as root
- node.
+`root_cookie_tree`
+ same as above, with the root container as root node.
The example page template(s) in the browser package give an idea how
to use these views for HTML templating.
@@ -47,7 +50,7 @@
-------------
The best way to customize ZopeTree is to define your own view for
-objects (usually *). If you want to use the cookie functionality,
+objects (usually '*'). If you want to use the cookie functionality,
simply extend the cookie browser view::
from zope.app.tree.filters import OnlyInterfacesFilter
@@ -78,14 +81,16 @@
License and Copyright
---------------------
-This product is released under the terms of the Zope Public License
-(ZPL) v2.0. See the 'ZopePublicLicense.txt' file at the root of your
+This product is released under the terms of the `Zope Public License
+(ZPL) v2.1`__. See the `ZopePublicLicense.txt` file at the root of your
Zope distribution.
Copyright (c) 2003 Philipp "philiKON" von Weitershausen
Copyright (c) 2004 Zope Corporation and Contributors
+.. __: http://www.zope.org/Resources/ZPL/ZPL-2.1
+
Credits
-------
Modified: Zope3/trunk/src/zope/app/tree/TODO.txt
===================================================================
--- Zope3/trunk/src/zope/app/tree/TODO.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/tree/TODO.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,5 +1,6 @@
-
+====
TODO
+====
for v1.3
Modified: Zope3/trunk/src/zope/event/README.txt
===================================================================
--- Zope3/trunk/src/zope/event/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/event/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -14,14 +14,16 @@
The package has a list of subscribers. Application code can manage
subscriptions by manipulating this list. For the examples here, we'll
save the current contents away and empty the list. We'll restore the
-contents when we're done with out examples.
+contents when we're done with our examples.
+::
+
>>> import zope.event
>>> old_subscribers = zope.event.subscribers[:]
>>> del zope.event.subscribers[:]
The package provides a `notify` function, which is used to
-notify subscribers that something has happened:
+notify subscribers that something has happened::
>>> class MyEvent:
... pass
@@ -30,18 +32,18 @@
>>> zope.event.notify(event)
The notify function is called with a single object, which we call an
-event. Any object will do:
+event. Any object will do::
>>> zope.event.notify(None)
>>> zope.event.notify(42)
An extremely trivial subscription mechanism is provided. Subscribers
-are simply callback functions:
+are simply callback functions::
>>> def f(event):
... print 'got:', event
-that are put into the subscriptions list:
+that are put into the subscriptions list::
>>> zope.event.subscribers.append(f)
@@ -57,7 +59,7 @@
got: 42
also got: 42
-To unsubscribe, simply remove a subscriber from the list:
+To unsubscribe, simply remove a subscriber from the list::
>>> zope.event.subscribers.remove(f)
>>> zope.event.notify(42)
@@ -68,6 +70,6 @@
frameworks will install subscribers that then dispatch to other
subscribers based on event types or data.
-We're done, so we'll restore the subscribers:
+We're done, so we'll restore the subscribers::
>>> zope.event.subscribers[:] = old_subscribers
Modified: Zope3/trunk/src/zope/i18n/locales/README.txt
===================================================================
--- Zope3/trunk/src/zope/i18n/locales/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/i18n/locales/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,33 +1,35 @@
+=================
Locales XML Files
+=================
- The XML locale files were produced as part of the ICU I18n and L10n
- framework. They are provided here under the original ICU License - ICU 1.8.1
- and later license.
+The XML locale files were produced as part of the ICU I18n and L10n
+framework. They are provided here under the original ICU License - ICU 1.8.1
+and later license.
- ICU Web site
+ICU Web site
+------------
- http://oss.software.ibm.com/icu/
+ http://oss.software.ibm.com/icu/
- Locale Data Markup Language
+Locale Data Markup Language
+---------------------------
- The XML files follow the now public and completed LDML format.
+The XML files follow the now public and completed LDML format.
- The DTD can be found at
+The DTD can be found at
- http://www.openi18n.org/spec/ldml/1.0/ldml-spec.htm
+ http://www.openi18n.org/spec/ldml/1.0/ldml-spec.htm
- The specification is at
+The specification is at
- http://www.openi18n.org/spec/ldml/1.0/ldml.dtd
+ http://www.openi18n.org/spec/ldml/1.0/ldml.dtd
-
- Download
- ::
+Download::
- $ cvs -d :pserver:anoncvs at oss.software.ibm.com:/usr/cvs/icu login
- Password: anoncvs
- $ cvs -d :pserver:anoncvs at oss.software.ibm.com:/usr/cvs/icu co \
- -d new_locales locale/common/main -d data
+ $ cvs -d :pserver:anoncvs at oss.software.ibm.com:/usr/cvs/icu login
+ Password: anoncvs
+ $ cvs -d :pserver:anoncvs at oss.software.ibm.com:/usr/cvs/icu co \
+ -d new_locales locale/common/main -d data
Modified: Zope3/trunk/src/zope/interface/README.txt
===================================================================
--- Zope3/trunk/src/zope/interface/README.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/interface/README.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -37,23 +37,23 @@
In the example above, we've created an interface, `IFoo`. We
subclassed `zope.interface.Interface`, which is an ancestor interface for
all interfaces, much as `object` is an ancestor of all new-style
-classes [#create]_. The interface is not a class, It's an Interface,
-an instance of `InterfaceClass`:
+classes [#create]_. The interface is not a class, it's an Interface,
+an instance of `InterfaceClass`::
>>> type(IFoo)
<class 'zope.interface.interface.InterfaceClass'>
-We can ask for the interfaces documentation:
+We can ask for the interfaces documentation::
>>> IFoo.__doc__
'Foo blah blah'
-and it's name:
+and it's name::
>>> IFoo.__name__
'IFoo'
-and even it's module:
+and even it's module::
>>> IFoo.__module__
'__main__'
@@ -80,7 +80,7 @@
methods that are not instance methods.
You can access the attributes defined by an interface using mapping
-syntax:
+syntax::
>>> x = IFoo['x']
>>> type(x)
@@ -90,12 +90,12 @@
>>> x.__doc__
'X blah blah'
-You can use `in` to determine if an interface defines a name:
+You can use `in` to determine if an interface defines a name::
>>> 'x' in IFoo
True
-You can iterate over interfaces to get the names they define:
+You can iterate over interfaces to get the names they define::
>>> names = list(IFoo)
>>> names.sort()
@@ -103,14 +103,14 @@
['bar', 'x']
Remember that interfaces aren't classes. You can't access attribute
-definitions as attributes of interfaces:
+definitions as attributes of interfaces::
>>> IFoo.x
Traceback (most recent call last):
File "<stdin>", line 1, in ?
AttributeError: 'InterfaceClass' object has no attribute 'x'
-Methods provide access to the method signature:
+Methods provide access to the method signature::
>>> bar = IFoo['bar']
>>> bar.getSignatureString()
@@ -146,7 +146,7 @@
declaring interfaces.
The most common way to declare interfaces is using the implements
-function in a class statement:
+function in a class statement::
>>> class Foo:
... zope.interface.implements(IFoo)
@@ -164,28 +164,28 @@
In this example, we declared that `Foo` implements `IFoo`. This means
that instances of `Foo` provide `IFoo`. Having made this declaration,
there are several ways we can introspect the declarations. First, we
-can ask an interface whether it is implemented by a class:
+can ask an interface whether it is implemented by a class::
>>> IFoo.implementedBy(Foo)
True
-And we can ask whether an interface is provided by an object:
+And we can ask whether an interface is provided by an object::
>>> foo = Foo()
>>> IFoo.providedBy(foo)
True
-Of course, `Foo` doesn't provide `IFoo`, it implements it.
+Of course, `Foo` doesn't provide `IFoo`, it implements it::
>>> IFoo.providedBy(Foo)
False
-We can also ask what interfaces are implemented by an object:
+We can also ask what interfaces are implemented by an object::
>>> list(zope.interface.implementedBy(Foo))
[<InterfaceClass __main__.IFoo>]
-It's an error to ask for interfaces implemented by a non-class:
+It's an error to ask for interfaces implemented by a non-class::
>>> IFoo.implementedBy(foo)
Traceback (most recent call last):
@@ -197,7 +197,7 @@
...
TypeError: ('ImplementedBy called for non-type', Foo(None))
-Similarly, we can ask what interfaces are provided by an object:
+Similarly, we can ask what interfaces are provided by an object::
>>> list(zope.interface.providedBy(foo))
[<InterfaceClass __main__.IFoo>]
@@ -208,7 +208,7 @@
we want to document what the `__init__` method of the `Foo` class
does. It's not *really* part of `IFoo`. You wouldn't normally call
the `__init__` method on Foo instances. Rather, the `__init__` method
-is part of the `Foo`'s `__call__` method:
+is part of the `Foo`'s `__call__` method::
>>> class IFooFactory(zope.interface.Interface):
... """Create foos"""
@@ -220,11 +220,11 @@
... """
It's the class that provides this interface, so we declare the
-interface on the class:
+interface on the class::
>>> zope.interface.directlyProvides(Foo, IFooFactory)
-And then, we'll see that Foo provides some interfaces:
+And then, we'll see that Foo provides some interfaces::
>>> list(zope.interface.providedBy(Foo))
[<InterfaceClass __main__.IFooFactory>]
@@ -233,7 +233,7 @@
Declaring class interfaces is common enough that there's a special
declaration function for it, `classProvides`, that allows the
-declaration from within a class statement:
+declaration from within a class statement::
>>> class Foo2:
... zope.interface.implements(IFoo)
@@ -260,7 +260,7 @@
Sometimes, we want to declare interfaces on instances, even though
those instances get interfaces from their classes. Suppose we create
-a new interface, `ISpecial`:
+a new interface, `ISpecial`::
>>> class ISpecial(zope.interface.Interface):
... reason = zope.interface.Attribute("Reason why we're special")
@@ -268,7 +268,7 @@
... "Brag about being special"
We can make a an existing foo instance special by providing `reason`
-and `brag` attributes:
+and `brag` attributes::
>>> foo.reason = 'I just am'
>>> def brag():
@@ -279,18 +279,18 @@
>>> foo.brag()
"I'm special!"
-and by declaring the interface:
+and by declaring the interface::
>>> zope.interface.directlyProvides(foo, ISpecial)
-then the new interface is included in the provided interfaces:
+then the new interface is included in the provided interfaces::
>>> ISpecial.providedBy(foo)
True
>>> list(zope.interface.providedBy(foo))
[<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]
-We can find out what interfaces are directly provided by an object:
+We can find out what interfaces are directly provided by an object::
>>> list(zope.interface.directlyProvidedBy(foo))
[<InterfaceClass __main__.ISpecial>]
@@ -302,7 +302,7 @@
Inherited declarations
----------------------
-Normally, declarations are inherited:
+Normally, declarations are inherited::
>>> class SpecialFoo(Foo):
... zope.interface.implements(ISpecial)
@@ -317,7 +317,7 @@
[<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]
Sometimes, you don't want to inherit declarations. In that case, you
-can use `implementsOnly`, instead of `implements`:
+can use `implementsOnly`, instead of `implements`::
>>> class Special(Foo):
... zope.interface.implementsOnly(ISpecial)
@@ -338,7 +338,7 @@
definition. Sometimes, we may want to make declarations from outside
the class definition. For example, we might want to declare interfaces
for classes that we didn't write. The function `classImplements` can
-be used for this purpose:
+be used for this purpose::
>>> class C:
... pass
@@ -347,7 +347,7 @@
>>> list(zope.interface.implementedBy(C))
[<InterfaceClass __main__.IFoo>]
-We can use `classImplementsOnly` to exclude inherited interfaces:
+We can use `classImplementsOnly` to exclude inherited interfaces::
>>> class C(Foo):
... pass
@@ -362,7 +362,7 @@
-------------------
When we declare interfaces, we create *declaration* objects. When we
-query declarations, declaration objects are returned:
+query declarations, declaration objects are returned::
>>> type(zope.interface.implementedBy(Special))
<class 'zope.interface.declarations.Implements'>
@@ -370,7 +370,7 @@
Declaration objects and interface objects are similar in many ways. In
fact, they share a common base class. The important thing to realize
about them is that they can be used where interfaces are expected in
-declarations. Here's a silly example:
+declarations. Here's a silly example::
>>> class Special2(Foo):
... zope.interface.implementsOnly(
@@ -383,7 +383,7 @@
The declaration here is almost the same as
``zope.interface.implements(ISpecial)``, except that the order of
-interfaces in the resulting declaration is different:
+interfaces in the resulting declaration is different::
>>> list(zope.interface.implementedBy(Special2))
[<InterfaceClass __main__.IFoo>, <InterfaceClass __main__.ISpecial>]
@@ -395,7 +395,7 @@
=====================
Interfaces can extend other interfaces. They do this simply by listing
-the other interfaces as base interfaces:
+the other interfaces as base interfaces::
>>> class IBlat(zope.interface.Interface):
... """Blat blah blah"""
@@ -421,7 +421,7 @@
>>> names
['bar', 'eek', 'x', 'y']
-Note that `IBaz` overrides eek:
+Note that `IBaz` overrides eek::
>>> IBlat['eek'].__doc__
'eek blah blah'
@@ -432,19 +432,19 @@
extending an interface, the extending interface should be compatible
[#compat]_ with the extended interfaces.
-We can ask whether one interface extends another:
+We can ask whether one interface extends another::
>>> IBaz.extends(IFoo)
True
>>> IBlat.extends(IFoo)
False
-Note that interfaces don't extend themselves:
+Note that interfaces don't extend themselves::
>>> IBaz.extends(IBaz)
False
-Sometimes we wish they did, but we can, instead use `isOrExtends`:
+Sometimes we wish they did, but we can, instead use `isOrExtends`::
>>> IBaz.isOrExtends(IBaz)
True
@@ -456,7 +456,7 @@
When we iterate over an interface, we get all of the names it defines,
including names defined by base interfaces. Sometimes, we want *just*
the names defined by the interface directly. We bane use the `names`
-method for that:
+method for that::
>>> list(IBaz.names())
['eek']
@@ -467,7 +467,7 @@
Interfaces and attribute descriptions support an extension mechanism,
borrowed from UML, called "tagged values" that lets us store extra
-data:
+data::
>>> IFoo.setTaggedValue('date-modified', '2004-04-01')
>>> IFoo.setTaggedValue('author', 'Jim Fulton')
@@ -482,7 +482,7 @@
['author', 'date-modified']
Function attributes are converted to tagged values when method
-attribute definitions are created:
+attribute definitions are created::
>>> class IBazFactory(zope.interface.Interface):
... def __call__():
@@ -500,7 +500,7 @@
provide them. These conditions are expressed using one or more
invariants. Invariants are callable objects that will be called with
an object that provides an interface. An invariant raises an `Invalid`
-exception if the condition doesn't hold. Here's an example:
+exception if the condition doesn't hold. Here's an example::
>>> class RangeError(zope.interface.Invalid):
... """A range has invalid limits"""
@@ -511,7 +511,7 @@
... if ob.max < ob.min:
... raise RangeError(ob)
-Given this invariant, we can use it in an interface definition:
+Given this invariant, we can use it in an interface definition::
>>> class IRange(zope.interface.Interface):
... min = zope.interface.Attribute("Lower bound")
@@ -519,7 +519,7 @@
...
... zope.interface.invariant(range_invariant)
-Interfaces have a method for checking their invariants:
+Interfaces have a method for checking their invariants::
>>> class Range(object):
... zope.interface.implements(IRange)
@@ -540,7 +540,7 @@
If you have multiple invariants, you may not want to stop checking
after the first error. If you pass a list to `validateInvariants`,
then a single `Invalid` exception will be raised with the list of
-exceptions as it's argument:
+exceptions as it's argument::
>>> errors = []
>>> IRange.validateInvariants(Range(2,1), errors)
@@ -548,7 +548,7 @@
...
Invalid: [RangeError(Range(2, 1))]
-And the list will be filled with the individual exceptions:
+And the list will be filled with the individual exceptions::
>>> errors
[RangeError(Range(2, 1))]
Modified: Zope3/trunk/src/zope/interface/adapter.txt
===================================================================
--- Zope3/trunk/src/zope/interface/adapter.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/interface/adapter.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -94,7 +94,7 @@
>>> registry.lookup([IR1], IP1, 'bob')
"Bob's 12"
-You can leave the name off when doing a lookup:
+You can leave the name off when doing a lookup::
>>> registry.lookup([IR1], IP1)
12
@@ -118,8 +118,8 @@
lookup1
-------
-Lookup of single adapters is common enough that there is a
-specialized version of lookup that takes a single required interface:
+Lookup of single adapters is common enough that there is a specialized
+version of lookup that takes a single required interface::
>>> registry.lookup1(IR2, IP1, '')
21
@@ -133,7 +133,7 @@
object that implements an interface is adapted to another object that
supports a different interface. The adapter registry supports the
computation of adapters. In this case, we have to register adapter
-factories:
+factories::
>>> class IR(zope.interface.Interface):
... pass
@@ -149,7 +149,7 @@
>>> registry.register([IR], IP1, '', Y)
In this case, we registered a class as the factory. Now we can call
-`queryAdapter` to get the adapted object:
+`queryAdapter` to get the adapted object::
>>> x = X()
>>> y = registry.queryAdapter(x, IP1)
@@ -158,7 +158,7 @@
>>> y.context is x
True
-We can register and lookup by name too:
+We can register and lookup by name too::
>>> class Y2(Y):
... pass
@@ -170,8 +170,8 @@
>>> y.context is x
True
-An alternate method that provides the same function as `queryAdapter` is
-`adapter_hook`:
+An alternate method that provides the same function as `queryAdapter()` is
+`adapter_hook()`::
>>> y = registry.adapter_hook(IP1, x)
>>> y.__class__.__name__
@@ -184,7 +184,7 @@
>>> y.context is x
True
-The `adapter_hook` simply switches the order of the object and
+The `adapter_hook()` simply switches the order of the object and
interface arguments. It is used to hook into the interface call
mechanism.
@@ -223,7 +223,7 @@
Unregistering
-------------
-You can unregister by registering None, rather than an object:;
+You can unregister by registering None, rather than an object::
>>> registry.register([zope.interface.implementedBy(C2)], IP1, '', None)
>>> registry.lookup([zope.interface.implementedBy(C2)], IP1, '')
@@ -261,12 +261,12 @@
Multi-adaptation
----------------
-You can adapt multiple objects:
+You can adapt multiple objects::
>>> class Q:
... zope.interface.implements(IQ)
-As with single adapters, we register a factory, which is often a class:
+As with single adapters, we register a factory, which is often a class::
>>> class IM(zope.interface.Interface):
... pass
@@ -276,7 +276,7 @@
... self.x, self.q = x, q
>>> registry.register([IR, IQ], IM, '', M)
-And then we can call `queryMultiAdapter` to compute an adapter:
+And then we can call `queryMultiAdapter` to compute an adapter::
>>> q = Q()
>>> m = registry.queryMultiAdapter((x, q), IM)
@@ -285,7 +285,7 @@
>>> m.x is x and m.q is q
True
-and, of course, we can use names:
+and, of course, we can use names::
>>> class M2(M):
... pass
@@ -300,7 +300,7 @@
----------------
As with single adapters, you can define default adapters by specifying
-None for the *first* specification:
+None for the *first* specification::
>>> registry.register([None, IQ], IP2, '', 'q2')
>>> registry.lookup([IS, IQ], IP2, '')
@@ -309,7 +309,7 @@
Null Adapters
=============
-You can also adapt no specification:
+You can also adapt no specification::
>>> registry.register([], IP2, '', 2)
>>> registry.lookup([], IP2, '')
@@ -321,14 +321,14 @@
----------------------
Adapters are named. Sometimes, it's useful to get all of the named
-adapters for given interfaces.
+adapters for given interfaces::
>>> adapters = list(registry.lookupAll([IR1], IP1))
>>> adapters.sort()
>>> adapters
[(u'', 11), (u'bob', "Bob's 12")]
-This works for multi-adapters too:
+This works for multi-adapters too::
>>> registry.register([IR1, IQ2], IP2, 'bob', '1q2 for bob')
>>> adapters = list(registry.lookupAll([IR2, IQ2], IP1))
@@ -336,7 +336,7 @@
>>> adapters
[(u'', '1q22'), (u'bob', '1q2 for bob')]
-And even null adapters:
+And even null adapters::
>>> registry.register([], IP2, 'bob', 3)
>>> adapters = list(registry.lookupAll([], IP1))
@@ -437,7 +437,7 @@
We normally register adapter factories, which then allow us to compute
adapters, but with subscriptions, we get multiple adapters. Here's an
-example of multiple-object subscribers:
+example of multiple-object subscribers::
>>> registry.subscribe([IR, IQ], IM, M)
>>> registry.subscribe([IR, IQ], IM, M2)
@@ -460,7 +460,7 @@
output. It returns None. A handler is unlike adapters in that it does
all of it's work when the factory is called.
-To register a handler, simply provide None as the provided interface:
+To register a handler, simply provide None as the provided interface::
>>> def handler(event):
... print 'handler', event
Modified: Zope3/trunk/src/zope/interface/tests/foodforthought.txt
===================================================================
--- Zope3/trunk/src/zope/interface/tests/foodforthought.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/interface/tests/foodforthought.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -3,7 +3,7 @@
================================
-This file gives more subscription examples using a cooking-based examples
+This file gives more subscription examples using a cooking-based example::
>>> from zope.interface.adapter import AdapterRegistry
>>> registry = AdapterRegistry()
@@ -19,7 +19,7 @@
... pass
Adapting to some other interface for which there is no
-subscription adapter returns an empty sequence:
+subscription adapter returns an empty sequence::
>>> class IRecipe(zope.interface.Interface):
... pass
@@ -30,32 +30,32 @@
>>> class IKFC(IRecipe):
... pass
->>> list(registry.subscriptions([IPoultry], IRecipe))
-[]
+ >>> list(registry.subscriptions([IPoultry], IRecipe))
+ []
unless we define a subscription::
->>> registry.subscribe([IAnimal], ISausages, 'sausages')
->>> list(registry.subscriptions([IPoultry], ISausages))
-['sausages']
+ >>> registry.subscribe([IAnimal], ISausages, 'sausages')
+ >>> list(registry.subscriptions([IPoultry], ISausages))
+ ['sausages']
-And define another subscription adapter:
+And define another subscription adapter::
->>> registry.subscribe([IPoultry], INoodles, 'noodles')
->>> meals = list(registry.subscriptions([IPoultry], IRecipe))
->>> meals.sort()
->>> meals
-['noodles', 'sausages']
+ >>> registry.subscribe([IPoultry], INoodles, 'noodles')
+ >>> meals = list(registry.subscriptions([IPoultry], IRecipe))
+ >>> meals.sort()
+ >>> meals
+ ['noodles', 'sausages']
->>> registry.subscribe([IChicken], IKFC, 'kfc')
->>> meals = list(registry.subscriptions([IChicken], IRecipe))
->>> meals.sort()
->>> meals
-['kfc', 'noodles', 'sausages']
+ >>> registry.subscribe([IChicken], IKFC, 'kfc')
+ >>> meals = list(registry.subscriptions([IChicken], IRecipe))
+ >>> meals.sort()
+ >>> meals
+ ['kfc', 'noodles', 'sausages']
-And the answer for poultry hasn't changed:
+And the answer for poultry hasn't changed::
->>> meals = list(registry.subscriptions([IPoultry], IRecipe))
->>> meals.sort()
->>> meals
-['noodles', 'sausages']
+ >>> meals = list(registry.subscriptions([IPoultry], IRecipe))
+ >>> meals.sort()
+ >>> meals
+ ['noodles', 'sausages']
Modified: Zope3/trunk/src/zope/schema/fields.txt
===================================================================
--- Zope3/trunk/src/zope/schema/fields.txt 2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/schema/fields.txt 2004-07-16 21:14:43 UTC (rev 26600)
@@ -152,4 +152,4 @@
on the basis of uniqueness and other constraints.
This level of indirection may be unnecessary for some applications, and can be
-disabled with simple zcml changes within zope.app.
+disabled with simple ZCML changes within `zope.app`.
More information about the Zope3-Checkins
mailing list