[Zope3-checkins] SVN: Zope3/trunk/src/zope/component/README.txt prompt was missing

Egon Frerich e.frerich at nord-com.net
Tue Feb 22 17:14:00 EST 2005


Log message for revision 29249:
  prompt was missing

Changed:
  U   Zope3/trunk/src/zope/component/README.txt

-=-
Modified: Zope3/trunk/src/zope/component/README.txt
===================================================================
--- Zope3/trunk/src/zope/component/README.txt	2005-02-22 14:35:24 UTC (rev 29248)
+++ Zope3/trunk/src/zope/component/README.txt	2005-02-22 22:13:59 UTC (rev 29249)
@@ -1,242 +1,242 @@
-Zope Component Architecture
-===========================
-
-This package, together with `zope.interface`, provides facilities for
-defining, registering and looking up components.  There are two basic
-kinds of components: adapters and utilities.
-
-Utilities
----------
-
-Utilities are just components that provide an interface and that are
-looked up by an interface and a name.  Let's look at a trivial utility
-definition:
-
-    >>> import zope.interface
-
-    >>> class IGreeter(zope.interface.Interface):
-    ...     def greet():
-    ...         "say hello"
-
-    >>> class Greeter:
-    ...     zope.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]_:
-
-    >>> import zope.component
-    >>> greet = Greeter('bob')
-    >>> zope.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`:
-
-    >>> zope.component.queryUtility(IGreeter, 'robert').greet()
-    Hello bob
-
-    >>> zope.component.getUtility(IGreeter, 'robert').greet()
-    Hello bob
-
-`queryUtility` and `getUtility` differ in how failed lookups are handled:
-
-    >>> zope.component.queryUtility(IGreeter, 'ted')
-    >>> zope.component.queryUtility(IGreeter, 'ted', 42)
-    42
-    >>> zope.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')
-    >>> zope.component.provideUtility(ted, name='ted')
-    >>> zope.component.queryUtility(IGreeter, 'ted').greet()
-    Hello ted
-
-The name defaults to an empty string:
-
-    >>> world = Greeter()
-    >>> zope.component.provideUtility(world)
-    >>> zope.component.queryUtility(IGreeter).greet()
-    Hello world
-
-Adapters
---------
-
-Adapters are components that are computed from other components to
-adapt them to some interface.  Because they are computed from other
-objects, they are provided as factories, usually classes.  Here, we'll
-create a greeter for persons, so we can provide personalized greetings
-for different people:
-
-    >>> class IPerson(zope.interface.Interface):
-    ...     name = zope.interface.Attribute("Name")
-
-    >>> class PersonGreeter:
-    ...
-    ...     zope.component.adapts(IPerson)
-    ...     zope.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 `zope.component.adapts` to declare what we adapt.  We can find
-out if an object declares that it adapts anything using adaptedBy:
-
-    >>> list(zope.component.adaptedBy(PersonGreeter)) == [IPerson]
-    True
-
-If an object makes no declaration, then None is returned:
-
-    >>> zope.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]_:
-
-    >>> zope.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:
-    ...     zope.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
-
-    >>> zope.component.provideAdapter(
-    ...                        BobPersonGreeter, [IPerson], IGreeter, 'bob')
-
-The arguments can also be provided as keyword arguments:
-
-    >>> class TedPersonGreeter(BobPersonGreeter):
-    ...     name = "Ted"
-
-    >>> zope.component.provideAdapter(
-    ...     factory=TedPersonGreeter, adapts=[IPerson],
-    ...     provides=IGreeter, name='ted')
-
-For named adapters, use `queryAdapter`, or `getAdapter`:
-
-    >>> zope.component.queryAdapter(Person("Sally"), IGreeter, 'bob').greet()
-    Hello Sally my name is Bob
-
-    >>> zope.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:
-
-    >>> zope.component.queryAdapter(Person("Sally"), IGreeter, 'frank')
-    >>> zope.component.queryAdapter(Person("Sally"), IGreeter, 'frank', 42)
-    42
-    >>> zope.component.getAdapter(Person("Sally"), IGreeter, 'frank')
-    ... # doctest: +ELLIPSIS
-    Traceback (most recent call last):
-    ...
-    ComponentLookupError: (...Person...>, <...IGreeter>, 'frank')
-
-Adapters can adapt multiple objects:
-
-    >>> class TwoPersonGreeter:
-    ...
-    ...     zope.component.adapts(IPerson, IPerson)
-    ...     zope.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
-
-    >>> zope.component.provideAdapter(TwoPersonGreeter)
-
-To look up a multi-adapter, use either `queryMultiAdapter` or
-`getMultiAdapter`:
-
-    >>> zope.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):
-
-    >>> class IJob(zope.interface.Interface):
-    ...     "A job"
-
-    >>> class Job:
-    ...     zope.interface.implements(IJob)
-
-    >>> def personJob(person):
-    ...     return getattr(person, 'job', None)
-    >>> personJob = zope.interface.implementer(IJob)(personJob)
-    >>> personJob = zope.component.adapter(IPerson)(personJob)
-
-(In Python 2.4, the example can be written:
-
-    @zope.interface.implementer(IJob)
-    @zope.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:
-
-    >>> zope.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
- 
-
-.. [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
-       activity.
+Zope Component Architecture
+===========================
+
+This package, together with `zope.interface`, provides facilities for
+defining, registering and looking up components.  There are two basic
+kinds of components: adapters and utilities.
+
+Utilities
+---------
+
+Utilities are just components that provide an interface and that are
+looked up by an interface and a name.  Let's look at a trivial utility
+definition:
+
+    >>> import zope.interface
+
+    >>> class IGreeter(zope.interface.Interface):
+    ...     def greet():
+    ...         "say hello"
+
+    >>> class Greeter:
+    ...     zope.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]_:
+
+    >>> import zope.component
+    >>> greet = Greeter('bob')
+    >>> zope.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`:
+
+    >>> zope.component.queryUtility(IGreeter, 'robert').greet()
+    Hello bob
+
+    >>> zope.component.getUtility(IGreeter, 'robert').greet()
+    Hello bob
+
+`queryUtility` and `getUtility` differ in how failed lookups are handled:
+
+    >>> zope.component.queryUtility(IGreeter, 'ted')
+    >>> zope.component.queryUtility(IGreeter, 'ted', 42)
+    42
+    >>> zope.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')
+    >>> zope.component.provideUtility(ted, name='ted')
+    >>> zope.component.queryUtility(IGreeter, 'ted').greet()
+    Hello ted
+
+The name defaults to an empty string:
+
+    >>> world = Greeter()
+    >>> zope.component.provideUtility(world)
+    >>> zope.component.queryUtility(IGreeter).greet()
+    Hello world
+
+Adapters
+--------
+
+Adapters are components that are computed from other components to
+adapt them to some interface.  Because they are computed from other
+objects, they are provided as factories, usually classes.  Here, we'll
+create a greeter for persons, so we can provide personalized greetings
+for different people:
+
+    >>> class IPerson(zope.interface.Interface):
+    ...     name = zope.interface.Attribute("Name")
+
+    >>> class PersonGreeter:
+    ...
+    ...     zope.component.adapts(IPerson)
+    ...     zope.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 `zope.component.adapts` to declare what we adapt.  We can find
+out if an object declares that it adapts anything using adaptedBy:
+
+    >>> list(zope.component.adaptedBy(PersonGreeter)) == [IPerson]
+    True
+
+If an object makes no declaration, then None is returned:
+
+    >>> zope.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]_:
+
+    >>> zope.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:
+    ...     zope.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
+
+    >>> zope.component.provideAdapter(
+    ...                        BobPersonGreeter, [IPerson], IGreeter, 'bob')
+
+The arguments can also be provided as keyword arguments:
+
+    >>> class TedPersonGreeter(BobPersonGreeter):
+    ...     name = "Ted"
+
+    >>> zope.component.provideAdapter(
+    ...     factory=TedPersonGreeter, adapts=[IPerson],
+    ...     provides=IGreeter, name='ted')
+
+For named adapters, use `queryAdapter`, or `getAdapter`:
+
+    >>> zope.component.queryAdapter(Person("Sally"), IGreeter, 'bob').greet()
+    Hello Sally my name is Bob
+
+    >>> zope.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:
+
+    >>> zope.component.queryAdapter(Person("Sally"), IGreeter, 'frank')
+    >>> zope.component.queryAdapter(Person("Sally"), IGreeter, 'frank', 42)
+    42
+    >>> zope.component.getAdapter(Person("Sally"), IGreeter, 'frank')
+    ... # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    ComponentLookupError: (...Person...>, <...IGreeter>, 'frank')
+
+Adapters can adapt multiple objects:
+
+    >>> class TwoPersonGreeter:
+    ...
+    ...     zope.component.adapts(IPerson, IPerson)
+    ...     zope.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
+
+    >>> zope.component.provideAdapter(TwoPersonGreeter)
+
+To look up a multi-adapter, use either `queryMultiAdapter` or
+`getMultiAdapter`:
+
+    >>> zope.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):
+
+    >>> class IJob(zope.interface.Interface):
+    ...     "A job"
+
+    >>> class Job:
+    ...     zope.interface.implements(IJob)
+
+    >>> def personJob(person):
+    ...     return getattr(person, 'job', None)
+    >>> personJob = zope.interface.implementer(IJob)(personJob)
+    >>> personJob = zope.component.adapter(IPerson)(personJob)
+
+(In Python 2.4, the example can be written:
+
+    >>> @zope.interface.implementer(IJob)
+    @zope.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:
+
+    >>> zope.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
+ 
+
+.. [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
+       activity.



More information about the Zope3-Checkins mailing list