[Zope3-checkins] SVN: Zope3/trunk/src/ minor editing
Egon Frerich
e.frerich at nord-com.net
Thu Feb 24 17:36:00 EST 2005
Log message for revision 29290:
minor editing
Changed:
U Zope3/trunk/src/ZODB/tests/dbopen.txt
U Zope3/trunk/src/zope/app/component/site.txt
U Zope3/trunk/src/zope/app/form/browser/README.txt
U Zope3/trunk/src/zope/app/form/browser/source.txt
U Zope3/trunk/src/zope/app/testing/dochttp.txt
U Zope3/trunk/src/zope/configuration/README.txt
U Zope3/trunk/src/zope/event/README.txt
U Zope3/trunk/src/zope/pagetemplate/architecture.txt
U Zope3/trunk/src/zope/pagetemplate/readme.txt
U Zope3/trunk/src/zope/schema/README.txt
U Zope3/trunk/src/zope/schema/fields.txt
U Zope3/trunk/src/zope/testing/formparser.txt
U Zope3/trunk/src/zope/wfmc/README.txt
-=-
Modified: Zope3/trunk/src/ZODB/tests/dbopen.txt
===================================================================
--- Zope3/trunk/src/ZODB/tests/dbopen.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/ZODB/tests/dbopen.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -1,186 +1,177 @@
-##############################################################################
-#
-# Copyright (c) 2004 Zope Corporation and Contributors.
-# All Rights Reserved.
-#
-# This software is subject to the provisions of the Zope Public License,
-# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
-# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
-# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
-# FOR A PARTICULAR PURPOSE
-#
-##############################################################################
+=====================
+Connection Management
+=====================
+
Here we exercise the connection management done by the DB class.
->>> from ZODB import DB
->>> from ZODB.MappingStorage import MappingStorage as Storage
+ >>> from ZODB import DB
+ >>> from ZODB.MappingStorage import MappingStorage as Storage
Capturing log messages from DB is important for some of the examples:
->>> from zope.testing.loggingsupport import InstalledHandler
->>> handler = InstalledHandler('ZODB.DB')
+ >>> from zope.testing.loggingsupport import InstalledHandler
+ >>> handler = InstalledHandler('ZODB.DB')
Create a storage, and wrap it in a DB wrapper:
->>> st = Storage()
->>> db = DB(st)
+ >>> st = Storage()
+ >>> db = DB(st)
By default, we can open 7 connections without any log messages:
->>> conns = [db.open() for dummy in range(7)]
->>> handler.records
-[]
+ >>> conns = [db.open() for dummy in range(7)]
+ >>> handler.records
+ []
Open one more, and we get a warning:
->>> conns.append(db.open())
->>> len(handler.records)
-1
->>> msg = handler.records[0]
->>> print msg.name, msg.levelname, msg.getMessage()
-ZODB.DB WARNING DB.open() has 8 open connections with a pool_size of 7
+ >>> conns.append(db.open())
+ >>> len(handler.records)
+ 1
+ >>> msg = handler.records[0]
+ >>> print msg.name, msg.levelname, msg.getMessage()
+ ZODB.DB WARNING DB.open() has 8 open connections with a pool_size of 7
Open 6 more, and we get 6 more warnings:
->>> conns.extend([db.open() for dummy in range(6)])
->>> len(conns)
-14
->>> len(handler.records)
-7
->>> msg = handler.records[-1]
->>> print msg.name, msg.levelname, msg.getMessage()
-ZODB.DB WARNING DB.open() has 14 open connections with a pool_size of 7
+ >>> conns.extend([db.open() for dummy in range(6)])
+ >>> len(conns)
+ 14
+ >>> len(handler.records)
+ 7
+ >>> msg = handler.records[-1]
+ >>> print msg.name, msg.levelname, msg.getMessage()
+ ZODB.DB WARNING DB.open() has 14 open connections with a pool_size of 7
Add another, so that it's more than twice the default, and the level
rises to critical:
->>> conns.append(db.open())
->>> len(conns)
-15
->>> len(handler.records)
-8
->>> msg = handler.records[-1]
->>> print msg.name, msg.levelname, msg.getMessage()
-ZODB.DB CRITICAL DB.open() has 15 open connections with a pool_size of 7
+ >>> conns.append(db.open())
+ >>> len(conns)
+ 15
+ >>> len(handler.records)
+ 8
+ >>> msg = handler.records[-1]
+ >>> print msg.name, msg.levelname, msg.getMessage()
+ ZODB.DB CRITICAL DB.open() has 15 open connections with a pool_size of 7
While it's boring, it's important to verify that the same relationships
hold if the default pool size is overridden.
->>> handler.clear()
->>> st.close()
->>> st = Storage()
->>> PS = 2 # smaller pool size
->>> db = DB(st, pool_size=PS)
->>> conns = [db.open() for dummy in range(PS)]
->>> handler.records
-[]
+ >>> handler.clear()
+ >>> st.close()
+ >>> st = Storage()
+ >>> PS = 2 # smaller pool size
+ >>> db = DB(st, pool_size=PS)
+ >>> conns = [db.open() for dummy in range(PS)]
+ >>> handler.records
+ []
A warning for opening one more:
->>> conns.append(db.open())
->>> len(handler.records)
-1
->>> msg = handler.records[0]
->>> print msg.name, msg.levelname, msg.getMessage()
-ZODB.DB WARNING DB.open() has 3 open connections with a pool_size of 2
+ >>> conns.append(db.open())
+ >>> len(handler.records)
+ 1
+ >>> msg = handler.records[0]
+ >>> print msg.name, msg.levelname, msg.getMessage()
+ ZODB.DB WARNING DB.open() has 3 open connections with a pool_size of 2
More warnings through 4 connections:
->>> conns.extend([db.open() for dummy in range(PS-1)])
->>> len(conns)
-4
->>> len(handler.records)
-2
->>> msg = handler.records[-1]
->>> print msg.name, msg.levelname, msg.getMessage()
-ZODB.DB WARNING DB.open() has 4 open connections with a pool_size of 2
+ >>> conns.extend([db.open() for dummy in range(PS-1)])
+ >>> len(conns)
+ 4
+ >>> len(handler.records)
+ 2
+ >>> msg = handler.records[-1]
+ >>> print msg.name, msg.levelname, msg.getMessage()
+ ZODB.DB WARNING DB.open() has 4 open connections with a pool_size of 2
And critical for going beyond that:
->>> conns.append(db.open())
->>> len(conns)
-5
->>> len(handler.records)
-3
->>> msg = handler.records[-1]
->>> print msg.name, msg.levelname, msg.getMessage()
-ZODB.DB CRITICAL DB.open() has 5 open connections with a pool_size of 2
+ >>> conns.append(db.open())
+ >>> len(conns)
+ 5
+ >>> len(handler.records)
+ 3
+ >>> msg = handler.records[-1]
+ >>> print msg.name, msg.levelname, msg.getMessage()
+ ZODB.DB CRITICAL DB.open() has 5 open connections with a pool_size of 2
We can change the pool size on the fly:
->>> handler.clear()
->>> db.setPoolSize(6)
->>> conns.append(db.open())
->>> handler.records # no log msg -- the pool is bigger now
-[]
->>> conns.append(db.open()) # but one more and there's a warning again
->>> len(handler.records)
-1
->>> msg = handler.records[0]
->>> print msg.name, msg.levelname, msg.getMessage()
-ZODB.DB WARNING DB.open() has 7 open connections with a pool_size of 6
+ >>> handler.clear()
+ >>> db.setPoolSize(6)
+ >>> conns.append(db.open())
+ >>> handler.records # no log msg -- the pool is bigger now
+ []
+ >>> conns.append(db.open()) # but one more and there's a warning again
+ >>> len(handler.records)
+ 1
+ >>> msg = handler.records[0]
+ >>> print msg.name, msg.levelname, msg.getMessage()
+ ZODB.DB WARNING DB.open() has 7 open connections with a pool_size of 6
Enough of that.
->>> handler.clear()
->>> st.close()
+ >>> handler.clear()
+ >>> st.close()
More interesting is the stack-like nature of connection reuse. So long as
we keep opening new connections, and keep them alive, all connections
returned are distinct:
->>> st = Storage()
->>> db = DB(st)
->>> c1 = db.open()
->>> c2 = db.open()
->>> c3 = db.open()
->>> c1 is c2 or c1 is c3 or c2 is c3
-False
+ >>> st = Storage()
+ >>> db = DB(st)
+ >>> c1 = db.open()
+ >>> c2 = db.open()
+ >>> c3 = db.open()
+ >>> c1 is c2 or c1 is c3 or c2 is c3
+ False
Let's put some markers on the connections, so we can identify these
specific objects later:
->>> c1.MARKER = 'c1'
->>> c2.MARKER = 'c2'
->>> c3.MARKER = 'c3'
+ >>> c1.MARKER = 'c1'
+ >>> c2.MARKER = 'c2'
+ >>> c3.MARKER = 'c3'
Now explicitly close c1 and c2:
->>> c1.close()
->>> c2.close()
+ >>> c1.close()
+ >>> c2.close()
Reaching into the internals, we can see that db's connection pool now has
two connections available for reuse, and knows about three connections in
all:
->>> pool = db._pools['']
->>> len(pool.available)
-2
->>> len(pool.all)
-3
+ >>> pool = db._pools['']
+ >>> len(pool.available)
+ 2
+ >>> len(pool.all)
+ 3
Since we closed c2 last, it's at the top of the available stack, so will
be reused by the next open():
->>> c1 = db.open()
->>> c1.MARKER
-'c2'
->>> len(pool.available), len(pool.all)
-(1, 3)
+ >>> c1 = db.open()
+ >>> c1.MARKER
+ 'c2'
+ >>> len(pool.available), len(pool.all)
+ (1, 3)
->>> c3.close() # now the stack has c3 on top, then c1
->>> c2 = db.open()
->>> c2.MARKER
-'c3'
->>> len(pool.available), len(pool.all)
-(1, 3)
->>> c3 = db.open()
->>> c3.MARKER
-'c1'
->>> len(pool.available), len(pool.all)
-(0, 3)
+ >>> c3.close() # now the stack has c3 on top, then c1
+ >>> c2 = db.open()
+ >>> c2.MARKER
+ 'c3'
+ >>> len(pool.available), len(pool.all)
+ (1, 3)
+ >>> c3 = db.open()
+ >>> c3.MARKER
+ 'c1'
+ >>> len(pool.available), len(pool.all)
+ (0, 3)
What about the 3 in pool.all? We've seen that closing connections doesn't
reduce pool.all, and it would be bad if DB kept connections alive forever.
@@ -191,97 +182,97 @@
that are still alive.
->>> len(db.cacheDetailSize()) # one result for each connection's cache
-3
+ >>> len(db.cacheDetailSize()) # one result for each connection's cache
+ 3
If a connection object is abandoned (it becomes unreachable), then it
will vanish from pool.all automatically. However, connections are
involved in cycles, so exactly when a connection vanishes from pool.all
isn't predictable. It can be forced by running gc.collect():
->>> import gc
->>> dummy = gc.collect()
->>> len(pool.all)
-3
->>> c3 = None
->>> dummy = gc.collect() # removes c3 from pool.all
->>> len(pool.all)
-2
+ >>> import gc
+ >>> dummy = gc.collect()
+ >>> len(pool.all)
+ 3
+ >>> c3 = None
+ >>> dummy = gc.collect() # removes c3 from pool.all
+ >>> len(pool.all)
+ 2
Note that c3 is really gone; in particular it didn't get added back to
the stack of available connections by magic:
->>> len(pool.available)
-0
+ >>> len(pool.available)
+ 0
Nothing in that last block should have logged any msgs:
->>> handler.records
-[]
+ >>> handler.records
+ []
If "too many" connections are open, then closing one may kick an older
closed one out of the available connection stack.
->>> st.close()
->>> st = Storage()
->>> db = DB(st, pool_size=3)
->>> conns = [db.open() for dummy in range(6)]
->>> len(handler.records) # 3 warnings for the "excess" connections
-3
->>> pool = db._pools['']
->>> len(pool.available), len(pool.all)
-(0, 6)
+ >>> st.close()
+ >>> st = Storage()
+ >>> db = DB(st, pool_size=3)
+ >>> conns = [db.open() for dummy in range(6)]
+ >>> len(handler.records) # 3 warnings for the "excess" connections
+ 3
+ >>> pool = db._pools['']
+ >>> len(pool.available), len(pool.all)
+ (0, 6)
Let's mark them:
->>> for i, c in enumerate(conns):
-... c.MARKER = i
+ >>> for i, c in enumerate(conns):
+ ... c.MARKER = i
Closing connections adds them to the stack:
->>> for i in range(3):
-... conns[i].close()
->>> len(pool.available), len(pool.all)
-(3, 6)
->>> del conns[:3] # leave the ones with MARKERs 3, 4 and 5
+ >>> for i in range(3):
+ ... conns[i].close()
+ >>> len(pool.available), len(pool.all)
+ (3, 6)
+ >>> del conns[:3] # leave the ones with MARKERs 3, 4 and 5
Closing another one will purge the one with MARKER 0 from the stack
(since it was the first added to the stack):
->>> [c.MARKER for c in pool.available]
-[0, 1, 2]
->>> conns[0].close() # MARKER 3
->>> len(pool.available), len(pool.all)
-(3, 5)
->>> [c.MARKER for c in pool.available]
-[1, 2, 3]
+ >>> [c.MARKER for c in pool.available]
+ [0, 1, 2]
+ >>> conns[0].close() # MARKER 3
+ >>> len(pool.available), len(pool.all)
+ (3, 5)
+ >>> [c.MARKER for c in pool.available]
+ [1, 2, 3]
Similarly for the other two:
->>> conns[1].close(); conns[2].close()
->>> len(pool.available), len(pool.all)
-(3, 3)
->>> [c.MARKER for c in pool.available]
-[3, 4, 5]
+ >>> conns[1].close(); conns[2].close()
+ >>> len(pool.available), len(pool.all)
+ (3, 3)
+ >>> [c.MARKER for c in pool.available]
+ [3, 4, 5]
Reducing the pool size may also purge the oldest closed connections:
->>> db.setPoolSize(2) # gets rid of MARKER 3
->>> len(pool.available), len(pool.all)
-(2, 2)
->>> [c.MARKER for c in pool.available]
-[4, 5]
+ >>> db.setPoolSize(2) # gets rid of MARKER 3
+ >>> len(pool.available), len(pool.all)
+ (2, 2)
+ >>> [c.MARKER for c in pool.available]
+ [4, 5]
Since MARKER 5 is still the last one added to the stack, it will be the
first popped:
->>> c1 = db.open(); c2 = db.open()
->>> c1.MARKER, c2.MARKER
-(5, 4)
->>> len(pool.available), len(pool.all)
-(0, 2)
+ >>> c1 = db.open(); c2 = db.open()
+ >>> c1.MARKER, c2.MARKER
+ (5, 4)
+ >>> len(pool.available), len(pool.all)
+ (0, 2)
Clean up.
->>> st.close()
->>> handler.uninstall()
+ >>> st.close()
+ >>> handler.uninstall()
Modified: Zope3/trunk/src/zope/app/component/site.txt
===================================================================
--- Zope3/trunk/src/zope/app/component/site.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/app/component/site.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -342,6 +342,7 @@
`myfolder`:
# Make sure that our interfaces and classes are pickable.
+
>>> sys.modules['zope.app.component.tests'].IMyUtility = IMyUtility
>>> IMyUtility.__module__ = 'zope.app.component.tests'
>>> sys.modules['zope.app.component.tests'].MyUtility = MyUtility
Modified: Zope3/trunk/src/zope/app/form/browser/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/README.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/app/form/browser/README.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -2,6 +2,8 @@
Browser Widgets
===============
+.. contents::
+
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
@@ -22,7 +24,7 @@
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
===================================================
@@ -48,19 +50,19 @@
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
+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`.
Default Collection Field Widget Registration and Lookup
=======================================================
-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
+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
-widgets that differ on the basis of the members--a widget for entering a list
+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.
Modified: Zope3/trunk/src/zope/app/form/browser/source.txt
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/source.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/app/form/browser/source.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -24,7 +24,7 @@
obtained, then the source itself is assumed to be queriable.
- For each queriable found, a
- `zope.app.form.browser.interfaces.ISourceQueryView' view is looked
+ `zope.app.form.browser.interfaces.ISourceQueryView` view is looked
up. This view is used to obtain the HTML for displaying a query
form. The view is also used to obtain search results.
Modified: Zope3/trunk/src/zope/app/testing/dochttp.txt
===================================================================
--- Zope3/trunk/src/zope/app/testing/dochttp.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/app/testing/dochttp.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -1,31 +1,37 @@
+=================
+FDocTest (How-To)
+=================
+
Steps to get started:
-0. Use a clean/missing Data.fs
+1. Use a clean/missing Data.fs
-1. Create a manager with the name "mgr", password "mgrpw", and grant
+2. Create a manager with the name "mgr", password "mgrpw", and grant
the zope.Manager role.
-2. Install tcpwatch.
+3. Install tcpwatch.
-3. Create a temporary directory to record tcpwatch output.
+4. Create a temporary directory to record tcpwatch output.
-4. Run tcpwatch using:
+5. Run tcpwatch using:
tcpwatch.py -L 8081:8080 -s -r tmpdir
(the ports are the listening port and forwarded-to port; the
second need to match the Zope configuration)
-5. In a browser, connect to the listening port and do whatever needs
+6. In a browser, connect to the listening port and do whatever needs
to be recorded.
-6. Shut down tcpwatch.
+7. Shut down tcpwatch.
-7. Run the script src/zope/app/testing/dochttp.py:
+8. Run the script src/zope/app/testing/dochttp.py:
python2.3 src/zope/app/testing/dochttp.py tmpdir > somefile.txt
-8. Edit the generated text file to add explanations and elide
+9. Edit the generated text file to add explanations and elide
uninteresting portions of the output.
-9. In a functional test module (usually ftests.py), import
- FunctionalDocFileSuite from zope.app.testing.functional and
- instantiate it, passing the name of the text file containing the
- test.
+10. In a functional test module (usually ftests.py), import
+ FunctionalDocFileSuite from zope.app.testing.functional and
+ instantiate it, passing the name of the text file containing
+ the test.
+
+
Modified: Zope3/trunk/src/zope/configuration/README.txt
===================================================================
--- Zope3/trunk/src/zope/configuration/README.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/configuration/README.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -41,7 +41,7 @@
are typically functions that take a context and zero or more
keyword arguments and return a sequence of configuration actions.
- To learn how to create simple directives, see tests/test_simple.py.
+ To learn how to create simple directives, see `tests/test_simple.py`.
- Grouping directives collect information to be used by nested
@@ -55,7 +55,7 @@
Other directives can be nested in grouping directives.
To learn how to implement nested directives, look at the
- documentation in tests/test_nested.py.
+ documentation in `tests/test_nested.py`.
- Complex directives are directives that have subdirectives.
Subdirectives have handlers that are simply methods of complex
Modified: Zope3/trunk/src/zope/event/README.txt
===================================================================
--- Zope3/trunk/src/zope/event/README.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/event/README.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -16,14 +16,12 @@
save the current contents away and empty the list. We'll restore the
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
@@ -32,18 +30,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)
@@ -59,7 +57,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)
@@ -70,6 +68,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/pagetemplate/architecture.txt
===================================================================
--- Zope3/trunk/src/zope/pagetemplate/architecture.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/pagetemplate/architecture.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -1,5 +1,6 @@
-ZPT Architecture
-================
+=====================================
+ZPT (Zope Page-Template) Architecture
+=====================================
There are a number of major components that make up the page-template
architecture:
Modified: Zope3/trunk/src/zope/pagetemplate/readme.txt
===================================================================
--- Zope3/trunk/src/zope/pagetemplate/readme.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/pagetemplate/readme.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -4,6 +4,9 @@
:Author: Kapil Thangavelu <hazmat at objectrealms.net>
+.. contents::
+
+
Introduction
------------
@@ -61,4 +64,4 @@
pt.write(template)
pt(das_object=foo())
-See interfaces.py.
+See `interfaces.py`.
Modified: Zope3/trunk/src/zope/schema/README.txt
===================================================================
--- Zope3/trunk/src/zope/schema/README.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/schema/README.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -2,7 +2,9 @@
Zope 3 Schemas
==============
+.. contents::
+
Introduction
------------
@@ -34,9 +36,9 @@
Simple Usage
------------
-::
- $ python
+
+
>>> class Bookmark:
... def __init__(self, url):
... self.url = url
@@ -68,7 +70,7 @@
A Schema starts out like an interface but defines certain Fields to
which an object's attributes must conform. Let's look at a stripped
-down example from the programmer's tutorial (chapter two)::
+down example from the programmer's tutorial::
from zope.interface import Interface
from zope.schema import Text, TextLine
@@ -204,47 +206,7 @@
value.
-Issues to be solved
--------------------
-
-These issues were written up at the `Rotterdam Sprint`_ (12/4/2002).
-
-.. _Rotterdam Sprint: http://dev.zope.org/Zope3/InfraeSprintathon
-
-I18n
-****
-
-How i18n interferes with Schemas is not thought out. In a non-English
-context we probably want to have titles and descriptions easily
-translatable. The best idea so far is to use an attribute name
-together with its surrounding namespace (Interface-name etc.) as the
-message id used for looking up translations.
-
-Example::
-
- class book(Interface):
- author = ITextLine()
-
-To get to the And in view, while the widget or widget's messages are
-constructed::
-
- TranslatorService.getMessage('book.author.title', 'DE_DE')
-
-Integration with Interfaces
-***************************
-
-How closely are Interfaces and Schema related? Should they be
-refactored into one package? Are Schemas Zope-specific?
-
-Clarify and clean up use cases
-******************************
-
-Some use cases are not easy to understand. A lot of them look like
-features rather than use cases. The list of schema use cases needs to
-be cleaned up and be (sometimes) more detailed.
-
-
References
----------
Modified: Zope3/trunk/src/zope/schema/fields.txt
===================================================================
--- Zope3/trunk/src/zope/schema/fields.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/schema/fields.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -2,6 +2,9 @@
Fields
======
+.. contents::
+
+
This document highlights unusual and subtle aspects of various fields and
field classes, and is not intended to be a general introduction to schema
fields. Please see README.txt for a more general introduction.
@@ -16,13 +19,13 @@
Collections
===========
-Normal fields typically describe the API of the attribute--does it behave as a
-Python Int, or a Float, or a Bool--and various constraints to the model, such
+Normal fields typically describe the API of the attribute -- does it behave as a
+Python Int, or a Float, or a Bool -- and various constraints to the model, such
as a maximum or minimum value. Collection fields have additional requirements
because they contain other types, which may also be described and constrained.
For instance, imagine a list that contains non-negative floats and enforces
-uniqueness, In a schema, this might be written as follows::
+uniqueness, In a schema, this might be written as follows:
>>> from zope.interface import Interface
>>> from zope.schema import List, Float
@@ -44,7 +47,7 @@
would be message ids.
This declaration creates a field that implements a number of interfaces, among
-them these::
+them these:
>>> from zope.schema.interfaces import IList, ISequence, ICollection
>>> IList.providedBy(IInventoryItem['pricePoints'])
@@ -71,7 +74,7 @@
providing a dynamically generated vocabulary, the choices available to a
choice field can be contextually calculated.
-Simple choices do not have to explicitly use vocabularies::
+Simple choices do not have to explicitly use vocabularies:
>>> from zope.schema import Choice
>>> f = Choice((640, 1028, 1600))
@@ -104,7 +107,7 @@
A start to a vocabulary implementation that may do all you need for many simple
tasks may be found in zope.schema.vocabulary.SimpleVocabulary. Because
registered vocabularies are simply callables passed a context, many
-registered vocabularies can simply be functions that rely on SimpleVocabulary::
+registered vocabularies can simply be functions that rely on SimpleVocabulary:
>>> from zope.schema.vocabulary import SimpleVocabulary
>>> def myDynamicVocabulary(context):
@@ -116,7 +119,7 @@
not too difficult itself.
Choices and Collections
------------------------
+=======================
Choices are a field type and can be used as a value_type for collections. Just
as a collection of an "Int" value_type constrains members to integers, so a
@@ -129,8 +132,8 @@
============================================================
While fields support several use cases, including code documentation and data
-decription and even casting, a significant use case influencing their design is
-to support form generation--generating widgets for a field. Choice and
+description and even casting, a significant use case influencing their design is
+to support form generation -- generating widgets for a field. Choice and
collection fields are expected to be used within widget frameworks. The
zope.app approach typically (but configurably) uses multiple dispatches to
find widgets on the basis of various aspects of the fields.
@@ -138,7 +141,7 @@
Widgets for all fields are found by looking up a browser view of the field
providing an input or display widget view. Typically there is only a single
"widget" registered for Choice fields. When it is looked up, it performs
-another dispatch--another lookup--for a widget registered for both the field
+another dispatch -- another lookup -- for a widget registered for both the field
and the vocabulary. This widget typically has enough information to render
without a third dispatch.
Modified: Zope3/trunk/src/zope/testing/formparser.txt
===================================================================
--- Zope3/trunk/src/zope/testing/formparser.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/testing/formparser.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -8,7 +8,7 @@
The scanner is implemented using the `FormParser` class. The
constructor arguments are the page data containing the form and
-(optionally) the URL from which the page was retrieved::
+(optionally) the URL from which the page was retrieved:
>>> import zope.testing.formparser
@@ -49,7 +49,7 @@
>>> forms.form1 is forms[1]
False
-More often, the `parse()` convenience function is all that's needed::
+More often, the `parse()` convenience function is all that's needed:
>>> forms = zope.testing.formparser.parse(
... page_text, "http://cgi.example.com/somewhere/form.html")
@@ -62,7 +62,7 @@
False
Once we have the form we're interested in, we can check form
-attributes and individual field values::
+attributes and individual field values:
>>> form = forms.form1
>>> form.enctype
@@ -99,7 +99,7 @@
>>> forms[1]["action"].src
'http://www.example.com/base/else.png'
-The ``<textarea>`` element provides some additional attributes::
+The ``<textarea>`` element provides some additional attributes:
>>> ta = forms[1]["sometext"]
>>> print ta.rows
@@ -109,7 +109,7 @@
>>> ta.value
'Some text.'
-The ``<select>`` element provides access to the options as well::
+The ``<select>`` element provides access to the options as well:
>>> select = form["pick-two"]
>>> select.multiple
Modified: Zope3/trunk/src/zope/wfmc/README.txt
===================================================================
--- Zope3/trunk/src/zope/wfmc/README.txt 2005-02-24 22:09:59 UTC (rev 29289)
+++ Zope3/trunk/src/zope/wfmc/README.txt 2005-02-24 22:36:00 UTC (rev 29290)
@@ -711,8 +711,8 @@
Transition(Activity('Publication.prepare'), Activity('Publication.tech2'))
ActivityStarted(Activity('Publication.tech2'))
-Notice that we transitioned to *two* activities, `tech1' and
-`tech2'. This is because the prepare activity has an "and" split.
+Notice that we transitioned to *two* activities, `tech1` and
+`tech2`. This is because the prepare activity has an "and" split.
Now we'll do a tech review. Let's see what tech1 has:
>>> item = tech1.work_list.pop()
More information about the Zope3-Checkins
mailing list