[Checkins] SVN: zope.component/tseaver-test_cleanup/ Explicit doctest sections.
Tres Seaver
cvs-admin at zope.org
Sun Jun 17 18:32:22 UTC 2012
Log message for revision 126897:
Explicit doctest sections.
Also, remove some Python 2.3 compatibility cruft.
Changed:
_U zope.component/tseaver-test_cleanup/
U zope.component/tseaver-test_cleanup/docs/narr.rst
-=-
Modified: zope.component/tseaver-test_cleanup/docs/narr.rst
===================================================================
--- zope.component/tseaver-test_cleanup/docs/narr.rst 2012-06-17 18:32:14 UTC (rev 126896)
+++ zope.component/tseaver-test_cleanup/docs/narr.rst 2012-06-17 18:32:18 UTC (rev 126897)
@@ -12,63 +12,75 @@
looked up by an interface and a name. Let's look at a trivial utility
definition:
- >>> from zope import interface
+.. doctest::
- >>> class IGreeter(interface.Interface):
- ... def greet():
- ... "say hello"
+ >>> from zope import interface
- >>> class Greeter:
- ... interface.implements(IGreeter)
- ...
- ... def __init__(self, other="world"):
- ... self.other = other
- ...
- ... def greet(self):
- ... print "Hello", self.other
+ >>> class IGreeter(interface.Interface):
+ ... def greet():
+ ... "say hello"
+ >>> class Greeter:
+ ... interface.implements(IGreeter)
+ ...
+ ... def __init__(self, other="world"):
+ ... self.other = other
+ ...
+ ... def greet(self):
+ ... print "Hello", self.other
+
We can register an instance this class using `provideUtility` [1]_:
- >>> from zope import component
- >>> greet = Greeter('bob')
- >>> component.provideUtility(greet, IGreeter, 'robert')
+.. doctest::
+ >>> from zope import component
+ >>> greet = Greeter('bob')
+ >>> component.provideUtility(greet, IGreeter, 'robert')
+
In this example we registered the utility as providing the `IGreeter`
interface with a name of 'bob'. We can look the interface up with
either `queryUtility` or `getUtility`:
- >>> component.queryUtility(IGreeter, 'robert').greet()
- Hello bob
+.. doctest::
- >>> component.getUtility(IGreeter, 'robert').greet()
- Hello bob
+ >>> component.queryUtility(IGreeter, 'robert').greet()
+ Hello bob
+ >>> component.getUtility(IGreeter, 'robert').greet()
+ Hello bob
+
`queryUtility` and `getUtility` differ in how failed lookups are handled:
- >>> component.queryUtility(IGreeter, 'ted')
- >>> component.queryUtility(IGreeter, 'ted', 42)
- 42
- >>> component.getUtility(IGreeter, 'ted')
- ... # doctest: +ELLIPSIS
- Traceback (most recent call last):
- ...
- ComponentLookupError: (<InterfaceClass ...IGreeter>, 'ted')
+.. doctest::
+ >>> component.queryUtility(IGreeter, 'ted')
+ >>> component.queryUtility(IGreeter, 'ted', 42)
+ 42
+ >>> component.getUtility(IGreeter, 'ted')
+ ... # doctest: +ELLIPSIS
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (<InterfaceClass ...IGreeter>, 'ted')
+
If a component provides only one interface, as in the example above,
then we can omit the provided interface from the call to `provideUtility`:
- >>> ted = Greeter('ted')
- >>> component.provideUtility(ted, name='ted')
- >>> component.queryUtility(IGreeter, 'ted').greet()
- Hello ted
+.. doctest::
+ >>> ted = Greeter('ted')
+ >>> component.provideUtility(ted, name='ted')
+ >>> component.queryUtility(IGreeter, 'ted').greet()
+ Hello ted
+
The name defaults to an empty string:
- >>> world = Greeter()
- >>> component.provideUtility(world)
- >>> component.queryUtility(IGreeter).greet()
- Hello world
+.. doctest::
+ >>> world = Greeter()
+ >>> component.provideUtility(world)
+ >>> component.queryUtility(IGreeter).greet()
+ Hello world
+
Adapters
--------
@@ -78,111 +90,131 @@
create a greeter for persons, so we can provide personalized greetings
for different people:
- >>> class IPerson(interface.Interface):
- ... name = interface.Attribute("Name")
+.. doctest::
- >>> class PersonGreeter:
- ...
- ... component.adapts(IPerson)
- ... interface.implements(IGreeter)
- ...
- ... def __init__(self, person):
- ... self.person = person
- ...
- ... def greet(self):
- ... print "Hello", self.person.name
+ >>> class IPerson(interface.Interface):
+ ... name = interface.Attribute("Name")
+ >>> class PersonGreeter:
+ ...
+ ... component.adapts(IPerson)
+ ... interface.implements(IGreeter)
+ ...
+ ... def __init__(self, person):
+ ... self.person = person
+ ...
+ ... def greet(self):
+ ... print "Hello", self.person.name
+
The class defines a constructor that takes an argument for every
object adapted.
We used `component.adapts` to declare what we adapt. We can find
out if an object declares that it adapts anything using adaptedBy:
- >>> list(component.adaptedBy(PersonGreeter)) == [IPerson]
- True
+.. doctest::
+ >>> list(component.adaptedBy(PersonGreeter)) == [IPerson]
+ True
+
If an object makes no declaration, then None is returned:
- >>> component.adaptedBy(Greeter()) is None
- True
+.. doctest::
+ >>> component.adaptedBy(Greeter()) is None
+ True
+
If we declare the interfaces adapted and if we provide only one
interface, as in the example above, then we can provide the adapter
very simply [1]_:
- >>> component.provideAdapter(PersonGreeter)
+.. doctest::
+ >>> component.provideAdapter(PersonGreeter)
+
For adapters that adapt a single interface to a single interface
without a name, we can get the adapter by simply calling the
interface:
- >>> class Person:
- ... interface.implements(IPerson)
- ...
- ... def __init__(self, name):
- ... self.name = name
+.. doctest::
- >>> IGreeter(Person("Sally")).greet()
- Hello Sally
+ >>> class Person:
+ ... interface.implements(IPerson)
+ ...
+ ... def __init__(self, name):
+ ... self.name = name
+ >>> IGreeter(Person("Sally")).greet()
+ Hello Sally
+
We can also provide arguments to be very specific about what
how to register the adapter.
- >>> class BobPersonGreeter(PersonGreeter):
- ... name = 'Bob'
- ... def greet(self):
- ... print "Hello", self.person.name, "my name is", self.name
+.. doctest::
- >>> component.provideAdapter(
- ... BobPersonGreeter, [IPerson], IGreeter, 'bob')
+ >>> class BobPersonGreeter(PersonGreeter):
+ ... name = 'Bob'
+ ... def greet(self):
+ ... print "Hello", self.person.name, "my name is", self.name
+ >>> component.provideAdapter(
+ ... BobPersonGreeter, [IPerson], IGreeter, 'bob')
+
The arguments can also be provided as keyword arguments:
- >>> class TedPersonGreeter(BobPersonGreeter):
- ... name = "Ted"
+.. doctest::
- >>> component.provideAdapter(
- ... factory=TedPersonGreeter, adapts=[IPerson],
- ... provides=IGreeter, name='ted')
+ >>> class TedPersonGreeter(BobPersonGreeter):
+ ... name = "Ted"
+ >>> component.provideAdapter(
+ ... factory=TedPersonGreeter, adapts=[IPerson],
+ ... provides=IGreeter, name='ted')
+
For named adapters, use `queryAdapter`, or `getAdapter`:
- >>> component.queryAdapter(Person("Sally"), IGreeter, 'bob').greet()
- Hello Sally my name is Bob
+.. doctest::
- >>> component.getAdapter(Person("Sally"), IGreeter, 'ted').greet()
- Hello Sally my name is Ted
+ >>> component.queryAdapter(Person("Sally"), IGreeter, 'bob').greet()
+ Hello Sally my name is Bob
+ >>> component.getAdapter(Person("Sally"), IGreeter, 'ted').greet()
+ Hello Sally my name is Ted
+
If an adapter can't be found, `queryAdapter` returns a default value
and `getAdapter` raises an error:
- >>> component.queryAdapter(Person("Sally"), IGreeter, 'frank')
- >>> component.queryAdapter(Person("Sally"), IGreeter, 'frank', 42)
- 42
- >>> component.getAdapter(Person("Sally"), IGreeter, 'frank')
- ... # doctest: +ELLIPSIS
- Traceback (most recent call last):
- ...
- ComponentLookupError: (...Person...>, <...IGreeter>, 'frank')
+.. doctest::
+ >>> component.queryAdapter(Person("Sally"), IGreeter, 'frank')
+ >>> component.queryAdapter(Person("Sally"), IGreeter, 'frank', 42)
+ 42
+ >>> component.getAdapter(Person("Sally"), IGreeter, 'frank')
+ ... # doctest: +ELLIPSIS
+ Traceback (most recent call last):
+ ...
+ ComponentLookupError: (...Person...>, <...IGreeter>, 'frank')
+
Adapters can adapt multiple objects:
- >>> class TwoPersonGreeter:
- ...
- ... component.adapts(IPerson, IPerson)
- ... interface.implements(IGreeter)
- ...
- ... def __init__(self, person, greeter):
- ... self.person = person
- ... self.greeter = greeter
- ...
- ... def greet(self):
- ... print "Hello", self.person.name
- ... print "my name is", self.greeter.name
+.. doctest::
- >>> component.provideAdapter(TwoPersonGreeter)
+ >>> class TwoPersonGreeter:
+ ...
+ ... component.adapts(IPerson, IPerson)
+ ... interface.implements(IGreeter)
+ ...
+ ... def __init__(self, person, greeter):
+ ... self.person = person
+ ... self.greeter = greeter
+ ...
+ ... def greet(self):
+ ... print "Hello", self.person.name
+ ... print "my name is", self.greeter.name
+ >>> component.provideAdapter(TwoPersonGreeter)
+
Note that the declaration-order of the Interfaces beeing adapted to is
important for adapter look up. It must be the the same as the order of
parameters given to the adapter and used to query the adapter. This is
@@ -192,55 +224,55 @@
To look up a multi-adapter, use either `queryMultiAdapter` or
`getMultiAdapter`:
- >>> component.queryMultiAdapter((Person("Sally"), Person("Bob")),
- ... IGreeter).greet()
- Hello Sally
- my name is Bob
+.. doctest::
+ >>> component.queryMultiAdapter((Person("Sally"), Person("Bob")),
+ ... IGreeter).greet()
+ Hello Sally
+ my name is Bob
+
Adapters need not be classes. Any callable will do. We use the
-adapter decorator (in the Python 2.4 decorator sense) to declare that
-a callable object adapts some interfaces (or classes):
+adapter decorator to declare that a callable object adapts some interfaces
+(or classes):
- >>> class IJob(interface.Interface):
- ... "A job"
+.. doctest::
- >>> class Job:
- ... interface.implements(IJob)
+ >>> class IJob(interface.Interface):
+ ... "A job"
- >>> def personJob(person):
- ... return getattr(person, 'job', None)
- >>> personJob = interface.implementer(IJob)(personJob)
- >>> personJob = component.adapter(IPerson)(personJob)
+ >>> @interface.implementer(IJob)
+ ... class Job:
+ ... pass
+ >>> @interface.implementer(IJob)
+ ... @component.adapter(IPerson)
+ ... def personJob(person):
+ ... return getattr(person, 'job', None)
-In Python 2.4, the example can be written:
- >>> @interface.implementer(IJob)
- ... @component.adapter(IPerson)
- ... def personJob(person):
- ... return getattr(person, 'job', None)
-
-which looks a bit nicer.
-
In this example, the personJob function simply returns the person's
`job` attribute if present, or None if it's not present. An adapter
factory can return None to indicate that adaptation wasn't possible.
Let's register this adapter and try it out:
- >>> component.provideAdapter(personJob)
- >>> sally = Person("Sally")
- >>> IJob(sally) # doctest: +ELLIPSIS
- Traceback (most recent call last):
- ...
- TypeError: ('Could not adapt', ...
+.. doctest::
+ >>> component.provideAdapter(personJob)
+ >>> sally = Person("Sally")
+ >>> IJob(sally) # doctest: +ELLIPSIS
+ Traceback (most recent call last):
+ ...
+ TypeError: ('Could not adapt', ...
+
The adaptation failed because sally didn't have a job. Let's give her
one:
- >>> job = Job()
- >>> sally.job = job
- >>> IJob(sally) is job
- True
+.. doctest::
+ >>> job = Job()
+ >>> sally.job = job
+ >>> IJob(sally) is job
+ True
+
Subscription Adapters
---------------------
@@ -251,83 +283,95 @@
whether they meet some sort of standards. We define a validation
interface:
- >>> class IValidate(interface.Interface):
- ... def validate(ob):
- ... """Determine whether the object is valid
- ...
- ... Return a string describing a validation problem.
- ... An empty string is returned to indicate that the
- ... object is valid.
- ... """
+.. doctest::
+ >>> class IValidate(interface.Interface):
+ ... def validate(ob):
+ ... """Determine whether the object is valid
+ ...
+ ... Return a string describing a validation problem.
+ ... An empty string is returned to indicate that the
+ ... object is valid.
+ ... """
+
Perhaps we have documents:
- >>> class IDocument(interface.Interface):
- ... summary = interface.Attribute("Document summary")
- ... body = interface.Attribute("Document text")
+.. doctest::
- >>> class Document:
- ... interface.implements(IDocument)
- ... def __init__(self, summary, body):
- ... self.summary, self.body = summary, body
+ >>> class IDocument(interface.Interface):
+ ... summary = interface.Attribute("Document summary")
+ ... body = interface.Attribute("Document text")
+ >>> class Document:
+ ... interface.implements(IDocument)
+ ... def __init__(self, summary, body):
+ ... self.summary, self.body = summary, body
+
Now, we may want to specify various validation rules for
documents. For example, we might require that the summary be a single
line:
- >>> class SingleLineSummary:
- ... component.adapts(IDocument)
- ... interface.implements(IValidate)
- ...
- ... def __init__(self, doc):
- ... self.doc = doc
- ...
- ... def validate(self):
- ... if '\n' in self.doc.summary:
- ... return 'Summary should only have one line'
- ... else:
- ... return ''
+.. doctest::
+ >>> class SingleLineSummary:
+ ... component.adapts(IDocument)
+ ... interface.implements(IValidate)
+ ...
+ ... def __init__(self, doc):
+ ... self.doc = doc
+ ...
+ ... def validate(self):
+ ... if '\n' in self.doc.summary:
+ ... return 'Summary should only have one line'
+ ... else:
+ ... return ''
+
Or we might require the body to be at least 1000 characters in length:
- >>> class AdequateLength:
- ... component.adapts(IDocument)
- ... interface.implements(IValidate)
- ...
- ... def __init__(self, doc):
- ... self.doc = doc
- ...
- ... def validate(self):
- ... if len(self.doc.body) < 1000:
- ... return 'too short'
- ... else:
- ... return ''
+.. doctest::
+ >>> class AdequateLength:
+ ... component.adapts(IDocument)
+ ... interface.implements(IValidate)
+ ...
+ ... def __init__(self, doc):
+ ... self.doc = doc
+ ...
+ ... def validate(self):
+ ... if len(self.doc.body) < 1000:
+ ... return 'too short'
+ ... else:
+ ... return ''
+
We can register these as subscription adapters [1]_:
- >>> component.provideSubscriptionAdapter(SingleLineSummary)
- >>> component.provideSubscriptionAdapter(AdequateLength)
+.. doctest::
+ >>> component.provideSubscriptionAdapter(SingleLineSummary)
+ >>> component.provideSubscriptionAdapter(AdequateLength)
+
We can then use the subscribers to validate objects:
- >>> doc = Document("A\nDocument", "blah")
- >>> [adapter.validate()
- ... for adapter in component.subscribers([doc], IValidate)
- ... if adapter.validate()]
- ['Summary should only have one line', 'too short']
+.. doctest::
- >>> doc = Document("A\nDocument", "blah" * 1000)
- >>> [adapter.validate()
- ... for adapter in component.subscribers([doc], IValidate)
- ... if adapter.validate()]
- ['Summary should only have one line']
+ >>> doc = Document("A\nDocument", "blah")
+ >>> [adapter.validate()
+ ... for adapter in component.subscribers([doc], IValidate)
+ ... if adapter.validate()]
+ ['Summary should only have one line', 'too short']
- >>> doc = Document("A Document", "blah")
- >>> [adapter.validate()
- ... for adapter in component.subscribers([doc], IValidate)
- ... if adapter.validate()]
- ['too short']
+ >>> doc = Document("A\nDocument", "blah" * 1000)
+ >>> [adapter.validate()
+ ... for adapter in component.subscribers([doc], IValidate)
+ ... if adapter.validate()]
+ ['Summary should only have one line']
+ >>> doc = Document("A Document", "blah")
+ >>> [adapter.validate()
+ ... for adapter in component.subscribers([doc], IValidate)
+ ... if adapter.validate()]
+ ['too short']
+
Handlers
--------
@@ -344,11 +388,13 @@
document-management system, we might want to record creation times for
documents:
- >>> import datetime
+.. doctest::
- >>> def documentCreated(event):
- ... event.doc.created = datetime.datetime.utcnow()
+ >>> import datetime
+ >>> def documentCreated(event):
+ ... event.doc.created = datetime.datetime.utcnow()
+
In this example, we have a function that takes an event and performs
some processing. It doesn't actually return anything. This is a
special case of a subscription adapter that adapts an event to
@@ -359,43 +405,44 @@
To register the subscriber above, we define a document-created event:
- >>> class IDocumentCreated(interface.Interface):
- ... doc = interface.Attribute("The document that was created")
+.. doctest::
- >>> class DocumentCreated:
- ... interface.implements(IDocumentCreated)
- ...
- ... def __init__(self, doc):
- ... self.doc = doc
+ >>> class IDocumentCreated(interface.Interface):
+ ... doc = interface.Attribute("The document that was created")
+ >>> class DocumentCreated:
+ ... interface.implements(IDocumentCreated)
+ ...
+ ... def __init__(self, doc):
+ ... self.doc = doc
+
We'll also change our handler definition to:
- >>> def documentCreated(event):
- ... event.doc.created = datetime.datetime.utcnow()
+.. doctest::
- >>> documentCreated = component.adapter(IDocumentCreated)(documentCreated)
+ >>> @component.adapter(IDocumentCreated)
+ ... def documentCreated(event):
+ ... event.doc.created = datetime.datetime.utcnow()
-Note that in Python 2.4, this can be written:
-
- >>> @component.adapter(IDocumentCreated)
- ... def documentCreated(event):
- ... event.doc.created = datetime.datetime.utcnow()
-
This marks the handler as an adapter of `IDocumentCreated` events.
Now we'll register the handler [1]_:
- >>> component.provideHandler(documentCreated)
+.. doctest::
+ >>> component.provideHandler(documentCreated)
+
Now, if we can create an event and use the `handle` function to call
handlers registered for the event:
- >>> component.handle(DocumentCreated(doc))
- >>> doc.created.__class__.__name__
- 'datetime'
+.. doctest::
+ >>> component.handle(DocumentCreated(doc))
+ >>> doc.created.__class__.__name__
+ 'datetime'
+
.. [1] CAUTION: This API should only be used from test or
application-setup code. This API shouldn't be used by regular
library modules, as component registration is a configuration
More information about the checkins
mailing list