Mercurial > public > mercurial-scm > hg

comparison mercurial/thirdparty/zope/interface/interfaces.py @ 37176:943d77fc07a3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
thirdparty: vendor zope.interface 4.4.3 I've been trying to formalize interfaces for various components of Mercurial. So far, we've been using the "abc" package. This package is "good enough" for a lot of tasks. But it quickly falls over. For example, if you declare an @abc.abstractproperty, you must implement that attribute with a @property or the class compile time checking performed by abc will complain. This often forces you to implement dumb @property wrappers to return a _ prefixed attribute of the sane name. That's ugly. I've also wanted to implement automated checking that classes conform to various interfaces and don't expose other "public" attributes. After doing a bit of research and asking around, the general consensus seems to be that zope.interface is the best package for doing interface-based programming in Python. It has built-in support for verifying classes and objects conform to interfaces. It allows an interface's properties to be defined during __init__. There's even an "adapter registry" that allow you to register interfaces and look up which classes implement them. That could potentially be useful for places where our custom registry.py modules currently facilitates central registrations, but at a type level. Imagine extensions providing alternate implementations of things like the local repository interface to allow opening repositories with custom requirements. Anyway, this commit vendors zope.interface 4.4.3. The contents of the source tarball have been copied into mercurial/thirdparty/zope/ without modifications. Test modules have been removed because they are not interesting to us. The LICENSE.txt file has been copied so it lives next to the source. The Python modules don't use relative imports. zope/__init__.py defines a namespace package. So we'll need to modify the source code before this package is usable inside Mercurial. This will be done in subsequent commits. # no-check-commit for various style failures Differential Revision: https://phab.mercurial-scm.org/D2928
author Gregory Szorc <gregory.szorc@gmail.com>
date Wed, 21 Mar 2018 19:48:50 -0700
parents
children 68ee61822182
comparison
equal deleted inserted replaced
37175:fbe34945220d 37176:943d77fc07a3
1 ##############################################################################
2 #
3 # Copyright (c) 2002 Zope Foundation and Contributors.
4 # All Rights Reserved.
5 #
6 # This software is subject to the provisions of the Zope Public License,
7 # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
8 # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
9 # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
10 # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
11 # FOR A PARTICULAR PURPOSE.
12 #
13 ##############################################################################
14 """Interface Package Interfaces
15 """
16 __docformat__ = 'restructuredtext'
17
18 from zope.interface.interface import Attribute
19 from zope.interface.interface import Interface
20 from zope.interface.declarations import implementer
21
22
23 _BLANK = u''
24
25 class IElement(Interface):
26 """Objects that have basic documentation and tagged values.
27 """
28
29 __name__ = Attribute('__name__', 'The object name')
30 __doc__ = Attribute('__doc__', 'The object doc string')
31
32 def getTaggedValue(tag):
33 """Returns the value associated with `tag`.
34
35 Raise a `KeyError` of the tag isn't set.
36 """
37
38 def queryTaggedValue(tag, default=None):
39 """Returns the value associated with `tag`.
40
41 Return the default value of the tag isn't set.
42 """
43
44 def getTaggedValueTags():
45 """Returns a list of all tags."""
46
47 def setTaggedValue(tag, value):
48 """Associates `value` with `key`."""
49
50
51 class IAttribute(IElement):
52 """Attribute descriptors"""
53
54 interface = Attribute('interface',
55 'Stores the interface instance in which the '
56 'attribute is located.')
57
58
59 class IMethod(IAttribute):
60 """Method attributes"""
61
62 def getSignatureInfo():
63 """Returns the signature information.
64
65 This method returns a dictionary with the following keys:
66
67 o `positional` - All positional arguments.
68
69 o `required` - A list of all required arguments.
70
71 o `optional` - A list of all optional arguments.
72
73 o `varargs` - The name of the varargs argument.
74
75 o `kwargs` - The name of the kwargs argument.
76 """
77
78 def getSignatureString():
79 """Return a signature string suitable for inclusion in documentation.
80
81 This method returns the function signature string. For example, if you
82 have `func(a, b, c=1, d='f')`, then the signature string is `(a, b,
83 c=1, d='f')`.
84 """
85
86 class ISpecification(Interface):
87 """Object Behavioral specifications"""
88
89 def providedBy(object):
90 """Test whether the interface is implemented by the object
91
92 Return true of the object asserts that it implements the
93 interface, including asserting that it implements an extended
94 interface.
95 """
96
97 def implementedBy(class_):
98 """Test whether the interface is implemented by instances of the class
99
100 Return true of the class asserts that its instances implement the
101 interface, including asserting that they implement an extended
102 interface.
103 """
104
105 def isOrExtends(other):
106 """Test whether the specification is or extends another
107 """
108
109 def extends(other, strict=True):
110 """Test whether a specification extends another
111
112 The specification extends other if it has other as a base
113 interface or if one of it's bases extends other.
114
115 If strict is false, then the specification extends itself.
116 """
117
118 def weakref(callback=None):
119 """Return a weakref to the specification
120
121 This method is, regrettably, needed to allow weakrefs to be
122 computed to security-proxied specifications. While the
123 zope.interface package does not require zope.security or
124 zope.proxy, it has to be able to coexist with it.
125
126 """
127
128 __bases__ = Attribute("""Base specifications
129
130 A tuple if specifications from which this specification is
131 directly derived.
132
133 """)
134
135 __sro__ = Attribute("""Specification-resolution order
136
137 A tuple of the specification and all of it's ancestor
138 specifications from most specific to least specific.
139
140 (This is similar to the method-resolution order for new-style classes.)
141 """)
142
143 __iro__ = Attribute("""Interface-resolution order
144
145 A tuple of the of the specification's ancestor interfaces from
146 most specific to least specific. The specification itself is
147 included if it is an interface.
148
149 (This is similar to the method-resolution order for new-style classes.)
150 """)
151
152 def get(name, default=None):
153 """Look up the description for a name
154
155 If the named attribute is not defined, the default is
156 returned.
157 """
158
159
160 class IInterface(ISpecification, IElement):
161 """Interface objects
162
163 Interface objects describe the behavior of an object by containing
164 useful information about the object. This information includes:
165
166 o Prose documentation about the object. In Python terms, this
167 is called the "doc string" of the interface. In this element,
168 you describe how the object works in prose language and any
169 other useful information about the object.
170
171 o Descriptions of attributes. Attribute descriptions include
172 the name of the attribute and prose documentation describing
173 the attributes usage.
174
175 o Descriptions of methods. Method descriptions can include:
176
177 - Prose "doc string" documentation about the method and its
178 usage.
179
180 - A description of the methods arguments; how many arguments
181 are expected, optional arguments and their default values,
182 the position or arguments in the signature, whether the
183 method accepts arbitrary arguments and whether the method
184 accepts arbitrary keyword arguments.
185
186 o Optional tagged data. Interface objects (and their attributes and
187 methods) can have optional, application specific tagged data
188 associated with them. Examples uses for this are examples,
189 security assertions, pre/post conditions, and other possible
190 information you may want to associate with an Interface or its
191 attributes.
192
193 Not all of this information is mandatory. For example, you may
194 only want the methods of your interface to have prose
195 documentation and not describe the arguments of the method in
196 exact detail. Interface objects are flexible and let you give or
197 take any of these components.
198
199 Interfaces are created with the Python class statement using
200 either Interface.Interface or another interface, as in::
201
202 from zope.interface import Interface
203
204 class IMyInterface(Interface):
205 '''Interface documentation'''
206
207 def meth(arg1, arg2):
208 '''Documentation for meth'''
209
210 # Note that there is no self argument
211
212 class IMySubInterface(IMyInterface):
213 '''Interface documentation'''
214
215 def meth2():
216 '''Documentation for meth2'''
217
218 You use interfaces in two ways:
219
220 o You assert that your object implement the interfaces.
221
222 There are several ways that you can assert that an object
223 implements an interface:
224
225 1. Call zope.interface.implements in your class definition.
226
227 2. Call zope.interfaces.directlyProvides on your object.
228
229 3. Call 'zope.interface.classImplements' to assert that instances
230 of a class implement an interface.
231
232 For example::
233
234 from zope.interface import classImplements
235
236 classImplements(some_class, some_interface)
237
238 This approach is useful when it is not an option to modify
239 the class source. Note that this doesn't affect what the
240 class itself implements, but only what its instances
241 implement.
242
243 o You query interface meta-data. See the IInterface methods and
244 attributes for details.
245
246 """
247
248 def names(all=False):
249 """Get the interface attribute names
250
251 Return a sequence of the names of the attributes, including
252 methods, included in the interface definition.
253
254 Normally, only directly defined attributes are included. If
255 a true positional or keyword argument is given, then
256 attributes defined by base classes will be included.
257 """
258
259 def namesAndDescriptions(all=False):
260 """Get the interface attribute names and descriptions
261
262 Return a sequence of the names and descriptions of the
263 attributes, including methods, as name-value pairs, included
264 in the interface definition.
265
266 Normally, only directly defined attributes are included. If
267 a true positional or keyword argument is given, then
268 attributes defined by base classes will be included.
269 """
270
271 def __getitem__(name):
272 """Get the description for a name
273
274 If the named attribute is not defined, a KeyError is raised.
275 """
276
277 def direct(name):
278 """Get the description for the name if it was defined by the interface
279
280 If the interface doesn't define the name, returns None.
281 """
282
283 def validateInvariants(obj, errors=None):
284 """Validate invariants
285
286 Validate object to defined invariants. If errors is None,
287 raises first Invalid error; if errors is a list, appends all errors
288 to list, then raises Invalid with the errors as the first element
289 of the "args" tuple."""
290
291 def __contains__(name):
292 """Test whether the name is defined by the interface"""
293
294 def __iter__():
295 """Return an iterator over the names defined by the interface
296
297 The names iterated include all of the names defined by the
298 interface directly and indirectly by base interfaces.
299 """
300
301 __module__ = Attribute("""The name of the module defining the interface""")
302
303 class IDeclaration(ISpecification):
304 """Interface declaration
305
306 Declarations are used to express the interfaces implemented by
307 classes or provided by objects.
308 """
309
310 def __contains__(interface):
311 """Test whether an interface is in the specification
312
313 Return true if the given interface is one of the interfaces in
314 the specification and false otherwise.
315 """
316
317 def __iter__():
318 """Return an iterator for the interfaces in the specification
319 """
320
321 def flattened():
322 """Return an iterator of all included and extended interfaces
323
324 An iterator is returned for all interfaces either included in
325 or extended by interfaces included in the specifications
326 without duplicates. The interfaces are in "interface
327 resolution order". The interface resolution order is such that
328 base interfaces are listed after interfaces that extend them
329 and, otherwise, interfaces are included in the order that they
330 were defined in the specification.
331 """
332
333 def __sub__(interfaces):
334 """Create an interface specification with some interfaces excluded
335
336 The argument can be an interface or an interface
337 specifications. The interface or interfaces given in a
338 specification are subtracted from the interface specification.
339
340 Removing an interface that is not in the specification does
341 not raise an error. Doing so has no effect.
342
343 Removing an interface also removes sub-interfaces of the interface.
344
345 """
346
347 def __add__(interfaces):
348 """Create an interface specification with some interfaces added
349
350 The argument can be an interface or an interface
351 specifications. The interface or interfaces given in a
352 specification are added to the interface specification.
353
354 Adding an interface that is already in the specification does
355 not raise an error. Doing so has no effect.
356 """
357
358 def __nonzero__():
359 """Return a true value of the interface specification is non-empty
360 """
361
362 class IInterfaceDeclaration(Interface):
363 """Declare and check the interfaces of objects
364
365 The functions defined in this interface are used to declare the
366 interfaces that objects provide and to query the interfaces that have
367 been declared.
368
369 Interfaces can be declared for objects in two ways:
370
371 - Interfaces are declared for instances of the object's class
372
373 - Interfaces are declared for the object directly.
374
375 The interfaces declared for an object are, therefore, the union of
376 interfaces declared for the object directly and the interfaces
377 declared for instances of the object's class.
378
379 Note that we say that a class implements the interfaces provided
380 by it's instances. An instance can also provide interfaces
381 directly. The interfaces provided by an object are the union of
382 the interfaces provided directly and the interfaces implemented by
383 the class.
384 """
385
386 def providedBy(ob):
387 """Return the interfaces provided by an object
388
389 This is the union of the interfaces directly provided by an
390 object and interfaces implemented by it's class.
391
392 The value returned is an IDeclaration.
393 """
394
395 def implementedBy(class_):
396 """Return the interfaces implemented for a class' instances
397
398 The value returned is an IDeclaration.
399 """
400
401 def classImplements(class_, *interfaces):
402 """Declare additional interfaces implemented for instances of a class
403
404 The arguments after the class are one or more interfaces or
405 interface specifications (IDeclaration objects).
406
407 The interfaces given (including the interfaces in the
408 specifications) are added to any interfaces previously
409 declared.
410
411 Consider the following example::
412
413 class C(A, B):
414 ...
415
416 classImplements(C, I1, I2)
417
418
419 Instances of ``C`` provide ``I1``, ``I2``, and whatever interfaces
420 instances of ``A`` and ``B`` provide.
421 """
422
423 def implementer(*interfaces):
424 """Create a decorator for declaring interfaces implemented by a facory
425
426 A callable is returned that makes an implements declaration on
427 objects passed to it.
428 """
429
430 def classImplementsOnly(class_, *interfaces):
431 """Declare the only interfaces implemented by instances of a class
432
433 The arguments after the class are one or more interfaces or
434 interface specifications (IDeclaration objects).
435
436 The interfaces given (including the interfaces in the
437 specifications) replace any previous declarations.
438
439 Consider the following example::
440
441 class C(A, B):
442 ...
443
444 classImplements(C, IA, IB. IC)
445 classImplementsOnly(C. I1, I2)
446
447 Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
448 whatever interfaces instances of ``A`` and ``B`` implement.
449 """
450
451 def implementer_only(*interfaces):
452 """Create a decorator for declaring the only interfaces implemented
453
454 A callable is returned that makes an implements declaration on
455 objects passed to it.
456 """
457
458 def directlyProvidedBy(object):
459 """Return the interfaces directly provided by the given object
460
461 The value returned is an IDeclaration.
462 """
463
464 def directlyProvides(object, *interfaces):
465 """Declare interfaces declared directly for an object
466
467 The arguments after the object are one or more interfaces or
468 interface specifications (IDeclaration objects).
469
470 The interfaces given (including the interfaces in the
471 specifications) replace interfaces previously
472 declared for the object.
473
474 Consider the following example::
475
476 class C(A, B):
477 ...
478
479 ob = C()
480 directlyProvides(ob, I1, I2)
481
482 The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
483 instances have been declared for instances of ``C``.
484
485 To remove directly provided interfaces, use ``directlyProvidedBy`` and
486 subtract the unwanted interfaces. For example::
487
488 directlyProvides(ob, directlyProvidedBy(ob)-I2)
489
490 removes I2 from the interfaces directly provided by
491 ``ob``. The object, ``ob`` no longer directly provides ``I2``,
492 although it might still provide ``I2`` if it's class
493 implements ``I2``.
494
495 To add directly provided interfaces, use ``directlyProvidedBy`` and
496 include additional interfaces. For example::
497
498 directlyProvides(ob, directlyProvidedBy(ob), I2)
499
500 adds I2 to the interfaces directly provided by ob.
501 """
502
503 def alsoProvides(object, *interfaces):
504 """Declare additional interfaces directly for an object::
505
506 alsoProvides(ob, I1)
507
508 is equivalent to::
509
510 directlyProvides(ob, directlyProvidedBy(ob), I1)
511 """
512
513 def noLongerProvides(object, interface):
514 """Remove an interface from the list of an object's directly
515 provided interfaces::
516
517 noLongerProvides(ob, I1)
518
519 is equivalent to::
520
521 directlyProvides(ob, directlyProvidedBy(ob)-I1)
522
523 with the exception that if ``I1`` is an interface that is
524 provided by ``ob`` through the class's implementation,
525 ValueError is raised.
526 """
527
528 def implements(*interfaces):
529 """Declare interfaces implemented by instances of a class
530
531 This function is called in a class definition (Python 2.x only).
532
533 The arguments are one or more interfaces or interface
534 specifications (IDeclaration objects).
535
536 The interfaces given (including the interfaces in the
537 specifications) are added to any interfaces previously
538 declared.
539
540 Previous declarations include declarations for base classes
541 unless implementsOnly was used.
542
543 This function is provided for convenience. It provides a more
544 convenient way to call classImplements. For example::
545
546 implements(I1)
547
548 is equivalent to calling::
549
550 classImplements(C, I1)
551
552 after the class has been created.
553
554 Consider the following example (Python 2.x only)::
555
556 class C(A, B):
557 implements(I1, I2)
558
559
560 Instances of ``C`` implement ``I1``, ``I2``, and whatever interfaces
561 instances of ``A`` and ``B`` implement.
562 """
563
564 def implementsOnly(*interfaces):
565 """Declare the only interfaces implemented by instances of a class
566
567 This function is called in a class definition (Python 2.x only).
568
569 The arguments are one or more interfaces or interface
570 specifications (IDeclaration objects).
571
572 Previous declarations including declarations for base classes
573 are overridden.
574
575 This function is provided for convenience. It provides a more
576 convenient way to call classImplementsOnly. For example::
577
578 implementsOnly(I1)
579
580 is equivalent to calling::
581
582 classImplementsOnly(I1)
583
584 after the class has been created.
585
586 Consider the following example (Python 2.x only)::
587
588 class C(A, B):
589 implementsOnly(I1, I2)
590
591
592 Instances of ``C`` implement ``I1``, ``I2``, regardless of what
593 instances of ``A`` and ``B`` implement.
594 """
595
596 def classProvides(*interfaces):
597 """Declare interfaces provided directly by a class
598
599 This function is called in a class definition.
600
601 The arguments are one or more interfaces or interface
602 specifications (IDeclaration objects).
603
604 The given interfaces (including the interfaces in the
605 specifications) are used to create the class's direct-object
606 interface specification. An error will be raised if the module
607 class has an direct interface specification. In other words, it is
608 an error to call this function more than once in a class
609 definition.
610
611 Note that the given interfaces have nothing to do with the
612 interfaces implemented by instances of the class.
613
614 This function is provided for convenience. It provides a more
615 convenient way to call directlyProvides for a class. For example::
616
617 classProvides(I1)
618
619 is equivalent to calling::
620
621 directlyProvides(theclass, I1)
622
623 after the class has been created.
624 """
625 def provider(*interfaces):
626 """A class decorator version of classProvides"""
627
628 def moduleProvides(*interfaces):
629 """Declare interfaces provided by a module
630
631 This function is used in a module definition.
632
633 The arguments are one or more interfaces or interface
634 specifications (IDeclaration objects).
635
636 The given interfaces (including the interfaces in the
637 specifications) are used to create the module's direct-object
638 interface specification. An error will be raised if the module
639 already has an interface specification. In other words, it is
640 an error to call this function more than once in a module
641 definition.
642
643 This function is provided for convenience. It provides a more
644 convenient way to call directlyProvides for a module. For example::
645
646 moduleImplements(I1)
647
648 is equivalent to::
649
650 directlyProvides(sys.modules[__name__], I1)
651 """
652
653 def Declaration(*interfaces):
654 """Create an interface specification
655
656 The arguments are one or more interfaces or interface
657 specifications (IDeclaration objects).
658
659 A new interface specification (IDeclaration) with
660 the given interfaces is returned.
661 """
662
663 class IAdapterRegistry(Interface):
664 """Provide an interface-based registry for adapters
665
666 This registry registers objects that are in some sense "from" a
667 sequence of specification to an interface and a name.
668
669 No specific semantics are assumed for the registered objects,
670 however, the most common application will be to register factories
671 that adapt objects providing required specifications to a provided
672 interface.
673 """
674
675 def register(required, provided, name, value):
676 """Register a value
677
678 A value is registered for a *sequence* of required specifications, a
679 provided interface, and a name, which must be text.
680 """
681
682 def registered(required, provided, name=_BLANK):
683 """Return the component registered for the given interfaces and name
684
685 name must be text.
686
687 Unlike the lookup method, this methods won't retrieve
688 components registered for more specific required interfaces or
689 less specific provided interfaces.
690
691 If no component was registered exactly for the given
692 interfaces and name, then None is returned.
693
694 """
695
696 def lookup(required, provided, name='', default=None):
697 """Lookup a value
698
699 A value is looked up based on a *sequence* of required
700 specifications, a provided interface, and a name, which must be
701 text.
702 """
703
704 def queryMultiAdapter(objects, provided, name=_BLANK, default=None):
705 """Adapt a sequence of objects to a named, provided, interface
706 """
707
708 def lookup1(required, provided, name=_BLANK, default=None):
709 """Lookup a value using a single required interface
710
711 A value is looked up based on a single required
712 specifications, a provided interface, and a name, which must be
713 text.
714 """
715
716 def queryAdapter(object, provided, name=_BLANK, default=None):
717 """Adapt an object using a registered adapter factory.
718 """
719
720 def adapter_hook(provided, object, name=_BLANK, default=None):
721 """Adapt an object using a registered adapter factory.
722
723 name must be text.
724 """
725
726 def lookupAll(required, provided):
727 """Find all adapters from the required to the provided interfaces
728
729 An iterable object is returned that provides name-value two-tuples.
730 """
731
732 def names(required, provided):
733 """Return the names for which there are registered objects
734 """
735
736 def subscribe(required, provided, subscriber, name=_BLANK):
737 """Register a subscriber
738
739 A subscriber is registered for a *sequence* of required
740 specifications, a provided interface, and a name.
741
742 Multiple subscribers may be registered for the same (or
743 equivalent) interfaces.
744 """
745
746 def subscriptions(required, provided, name=_BLANK):
747 """Get a sequence of subscribers
748
749 Subscribers for a *sequence* of required interfaces, and a provided
750 interface are returned.
751 """
752
753 def subscribers(objects, provided, name=_BLANK):
754 """Get a sequence of subscription adapters
755 """
756
757 # begin formerly in zope.component
758
759 class ComponentLookupError(LookupError):
760 """A component could not be found."""
761
762 class Invalid(Exception):
763 """A component doesn't satisfy a promise."""
764
765 class IObjectEvent(Interface):
766 """An event related to an object.
767
768 The object that generated this event is not necessarily the object
769 refered to by location.
770 """
771
772 object = Attribute("The subject of the event.")
773
774
775 @implementer(IObjectEvent)
776 class ObjectEvent(object):
777
778 def __init__(self, object):
779 self.object = object
780
781 class IComponentLookup(Interface):
782 """Component Manager for a Site
783
784 This object manages the components registered at a particular site. The
785 definition of a site is intentionally vague.
786 """
787
788 adapters = Attribute(
789 "Adapter Registry to manage all registered adapters.")
790
791 utilities = Attribute(
792 "Adapter Registry to manage all registered utilities.")
793
794 def queryAdapter(object, interface, name=_BLANK, default=None):
795 """Look for a named adapter to an interface for an object
796
797 If a matching adapter cannot be found, returns the default.
798 """
799
800 def getAdapter(object, interface, name=_BLANK):
801 """Look for a named adapter to an interface for an object
802
803 If a matching adapter cannot be found, a ComponentLookupError
804 is raised.
805 """
806
807 def queryMultiAdapter(objects, interface, name=_BLANK, default=None):
808 """Look for a multi-adapter to an interface for multiple objects
809
810 If a matching adapter cannot be found, returns the default.
811 """
812
813 def getMultiAdapter(objects, interface, name=_BLANK):
814 """Look for a multi-adapter to an interface for multiple objects
815
816 If a matching adapter cannot be found, a ComponentLookupError
817 is raised.
818 """
819
820 def getAdapters(objects, provided):
821 """Look for all matching adapters to a provided interface for objects
822
823 Return an iterable of name-adapter pairs for adapters that
824 provide the given interface.
825 """
826
827 def subscribers(objects, provided):
828 """Get subscribers
829
830 Subscribers are returned that provide the provided interface
831 and that depend on and are comuted from the sequence of
832 required objects.
833 """
834
835 def handle(*objects):
836 """Call handlers for the given objects
837
838 Handlers registered for the given objects are called.
839 """
840
841 def queryUtility(interface, name='', default=None):
842 """Look up a utility that provides an interface.
843
844 If one is not found, returns default.
845 """
846
847 def getUtilitiesFor(interface):
848 """Look up the registered utilities that provide an interface.
849
850 Returns an iterable of name-utility pairs.
851 """
852
853 def getAllUtilitiesRegisteredFor(interface):
854 """Return all registered utilities for an interface
855
856 This includes overridden utilities.
857
858 An iterable of utility instances is returned. No names are
859 returned.
860 """
861
862 class IRegistration(Interface):
863 """A registration-information object
864 """
865
866 registry = Attribute("The registry having the registration")
867
868 name = Attribute("The registration name")
869
870 info = Attribute("""Information about the registration
871
872 This is information deemed useful to people browsing the
873 configuration of a system. It could, for example, include
874 commentary or information about the source of the configuration.
875 """)
876
877 class IUtilityRegistration(IRegistration):
878 """Information about the registration of a utility
879 """
880
881 factory = Attribute("The factory used to create the utility. Optional.")
882 component = Attribute("The object registered")
883 provided = Attribute("The interface provided by the component")
884
885 class _IBaseAdapterRegistration(IRegistration):
886 """Information about the registration of an adapter
887 """
888
889 factory = Attribute("The factory used to create adapters")
890
891 required = Attribute("""The adapted interfaces
892
893 This is a sequence of interfaces adapters by the registered
894 factory. The factory will be caled with a sequence of objects, as
895 positional arguments, that provide these interfaces.
896 """)
897
898 provided = Attribute("""The interface provided by the adapters.
899
900 This interface is implemented by the factory
901 """)
902
903 class IAdapterRegistration(_IBaseAdapterRegistration):
904 """Information about the registration of an adapter
905 """
906
907 class ISubscriptionAdapterRegistration(_IBaseAdapterRegistration):
908 """Information about the registration of a subscription adapter
909 """
910
911 class IHandlerRegistration(IRegistration):
912
913 handler = Attribute("An object called used to handle an event")
914
915 required = Attribute("""The handled interfaces
916
917 This is a sequence of interfaces handled by the registered
918 handler. The handler will be caled with a sequence of objects, as
919 positional arguments, that provide these interfaces.
920 """)
921
922 class IRegistrationEvent(IObjectEvent):
923 """An event that involves a registration"""
924
925
926 @implementer(IRegistrationEvent)
927 class RegistrationEvent(ObjectEvent):
928 """There has been a change in a registration
929 """
930 def __repr__(self):
931 return "%s event:\n%r" % (self.__class__.__name__, self.object)
932
933 class IRegistered(IRegistrationEvent):
934 """A component or factory was registered
935 """
936
937 @implementer(IRegistered)
938 class Registered(RegistrationEvent):
939 pass
940
941 class IUnregistered(IRegistrationEvent):
942 """A component or factory was unregistered
943 """
944
945 @implementer(IUnregistered)
946 class Unregistered(RegistrationEvent):
947 """A component or factory was unregistered
948 """
949 pass
950
951 class IComponentRegistry(Interface):
952 """Register components
953 """
954
955 def registerUtility(component=None, provided=None, name=_BLANK,
956 info=_BLANK, factory=None):
957 """Register a utility
958
959 factory
960 Factory for the component to be registerd.
961
962 component
963 The registered component
964
965 provided
966 This is the interface provided by the utility. If the
967 component provides a single interface, then this
968 argument is optional and the component-implemented
969 interface will be used.
970
971 name
972 The utility name.
973
974 info
975 An object that can be converted to a string to provide
976 information about the registration.
977
978 Only one of component and factory can be used.
979 A Registered event is generated with an IUtilityRegistration.
980 """
981
982 def unregisterUtility(component=None, provided=None, name=_BLANK,
983 factory=None):
984 """Unregister a utility
985
986 A boolean is returned indicating whether the registry was
987 changed. If the given component is None and there is no
988 component registered, or if the given component is not
989 None and is not registered, then the function returns
990 False, otherwise it returns True.
991
992 factory
993 Factory for the component to be unregisterd.
994
995 component
996 The registered component The given component can be
997 None, in which case any component registered to provide
998 the given provided interface with the given name is
999 unregistered.
1000
1001 provided
1002 This is the interface provided by the utility. If the
1003 component is not None and provides a single interface,
1004 then this argument is optional and the
1005 component-implemented interface will be used.
1006
1007 name
1008 The utility name.
1009
1010 Only one of component and factory can be used.
1011 An UnRegistered event is generated with an IUtilityRegistration.
1012 """
1013
1014 def registeredUtilities():
1015 """Return an iterable of IUtilityRegistration instances.
1016
1017 These registrations describe the current utility registrations
1018 in the object.
1019 """
1020
1021 def registerAdapter(factory, required=None, provided=None, name=_BLANK,
1022 info=_BLANK):
1023 """Register an adapter factory
1024
1025 Parameters:
1026
1027 factory
1028 The object used to compute the adapter
1029
1030 required
1031 This is a sequence of specifications for objects to be
1032 adapted. If omitted, then the value of the factory's
1033 __component_adapts__ attribute will be used. The
1034 __component_adapts__ attribute is usually attribute is
1035 normally set in class definitions using adapts
1036 function, or for callables using the adapter
1037 decorator. If the factory doesn't have a
1038 __component_adapts__ adapts attribute, then this
1039 argument is required.
1040
1041 provided
1042 This is the interface provided by the adapter and
1043 implemented by the factory. If the factory
1044 implements a single interface, then this argument is
1045 optional and the factory-implemented interface will be
1046 used.
1047
1048 name
1049 The adapter name.
1050
1051 info
1052 An object that can be converted to a string to provide
1053 information about the registration.
1054
1055 A Registered event is generated with an IAdapterRegistration.
1056 """
1057
1058 def unregisterAdapter(factory=None, required=None,
1059 provided=None, name=_BLANK):
1060 """Unregister an adapter factory
1061
1062 A boolean is returned indicating whether the registry was
1063 changed. If the given component is None and there is no
1064 component registered, or if the given component is not
1065 None and is not registered, then the function returns
1066 False, otherwise it returns True.
1067
1068 Parameters:
1069
1070 factory
1071 This is the object used to compute the adapter. The
1072 factory can be None, in which case any factory
1073 registered to implement the given provided interface
1074 for the given required specifications with the given
1075 name is unregistered.
1076
1077 required
1078 This is a sequence of specifications for objects to be
1079 adapted. If the factory is not None and the required
1080 arguments is omitted, then the value of the factory's
1081 __component_adapts__ attribute will be used. The
1082 __component_adapts__ attribute attribute is normally
1083 set in class definitions using adapts function, or for
1084 callables using the adapter decorator. If the factory
1085 is None or doesn't have a __component_adapts__ adapts
1086 attribute, then this argument is required.
1087
1088 provided
1089 This is the interface provided by the adapter and
1090 implemented by the factory. If the factory is not
1091 None and implements a single interface, then this
1092 argument is optional and the factory-implemented
1093 interface will be used.
1094
1095 name
1096 The adapter name.
1097
1098 An Unregistered event is generated with an IAdapterRegistration.
1099 """
1100
1101 def registeredAdapters():
1102 """Return an iterable of IAdapterRegistration instances.
1103
1104 These registrations describe the current adapter registrations
1105 in the object.
1106 """
1107
1108 def registerSubscriptionAdapter(factory, required=None, provides=None,
1109 name=_BLANK, info=''):
1110 """Register a subscriber factory
1111
1112 Parameters:
1113
1114 factory
1115 The object used to compute the adapter
1116
1117 required
1118 This is a sequence of specifications for objects to be
1119 adapted. If omitted, then the value of the factory's
1120 __component_adapts__ attribute will be used. The
1121 __component_adapts__ attribute is usually attribute is
1122 normally set in class definitions using adapts
1123 function, or for callables using the adapter
1124 decorator. If the factory doesn't have a
1125 __component_adapts__ adapts attribute, then this
1126 argument is required.
1127
1128 provided
1129 This is the interface provided by the adapter and
1130 implemented by the factory. If the factory implements
1131 a single interface, then this argument is optional and
1132 the factory-implemented interface will be used.
1133
1134 name
1135 The adapter name.
1136
1137 Currently, only the empty string is accepted. Other
1138 strings will be accepted in the future when support for
1139 named subscribers is added.
1140
1141 info
1142 An object that can be converted to a string to provide
1143 information about the registration.
1144
1145 A Registered event is generated with an
1146 ISubscriptionAdapterRegistration.
1147 """
1148
1149 def unregisterSubscriptionAdapter(factory=None, required=None,
1150 provides=None, name=_BLANK):
1151 """Unregister a subscriber factory.
1152
1153 A boolean is returned indicating whether the registry was
1154 changed. If the given component is None and there is no
1155 component registered, or if the given component is not
1156 None and is not registered, then the function returns
1157 False, otherwise it returns True.
1158
1159 Parameters:
1160
1161 factory
1162 This is the object used to compute the adapter. The
1163 factory can be None, in which case any factories
1164 registered to implement the given provided interface
1165 for the given required specifications with the given
1166 name are unregistered.
1167
1168 required
1169 This is a sequence of specifications for objects to be
1170 adapted. If the factory is not None and the required
1171 arguments is omitted, then the value of the factory's
1172 __component_adapts__ attribute will be used. The
1173 __component_adapts__ attribute attribute is normally
1174 set in class definitions using adapts function, or for
1175 callables using the adapter decorator. If the factory
1176 is None or doesn't have a __component_adapts__ adapts
1177 attribute, then this argument is required.
1178
1179 provided
1180 This is the interface provided by the adapter and
1181 implemented by the factory. If the factory is not
1182 None implements a single interface, then this argument
1183 is optional and the factory-implemented interface will
1184 be used.
1185
1186 name
1187 The adapter name.
1188
1189 Currently, only the empty string is accepted. Other
1190 strings will be accepted in the future when support for
1191 named subscribers is added.
1192
1193 An Unregistered event is generated with an
1194 ISubscriptionAdapterRegistration.
1195 """
1196
1197 def registeredSubscriptionAdapters():
1198 """Return an iterable of ISubscriptionAdapterRegistration instances.
1199
1200 These registrations describe the current subscription adapter
1201 registrations in the object.
1202 """
1203
1204 def registerHandler(handler, required=None, name=_BLANK, info=''):
1205 """Register a handler.
1206
1207 A handler is a subscriber that doesn't compute an adapter
1208 but performs some function when called.
1209
1210 Parameters:
1211
1212 handler
1213 The object used to handle some event represented by
1214 the objects passed to it.
1215
1216 required
1217 This is a sequence of specifications for objects to be
1218 adapted. If omitted, then the value of the factory's
1219 __component_adapts__ attribute will be used. The
1220 __component_adapts__ attribute is usually attribute is
1221 normally set in class definitions using adapts
1222 function, or for callables using the adapter
1223 decorator. If the factory doesn't have a
1224 __component_adapts__ adapts attribute, then this
1225 argument is required.
1226
1227 name
1228 The handler name.
1229
1230 Currently, only the empty string is accepted. Other
1231 strings will be accepted in the future when support for
1232 named handlers is added.
1233
1234 info
1235 An object that can be converted to a string to provide
1236 information about the registration.
1237
1238
1239 A Registered event is generated with an IHandlerRegistration.
1240 """
1241
1242 def unregisterHandler(handler=None, required=None, name=_BLANK):
1243 """Unregister a handler.
1244
1245 A handler is a subscriber that doesn't compute an adapter
1246 but performs some function when called.
1247
1248 A boolean is returned indicating whether the registry was
1249 changed.
1250
1251 Parameters:
1252
1253 handler
1254 This is the object used to handle some event
1255 represented by the objects passed to it. The handler
1256 can be None, in which case any handlers registered for
1257 the given required specifications with the given are
1258 unregistered.
1259
1260 required
1261 This is a sequence of specifications for objects to be
1262 adapted. If omitted, then the value of the factory's
1263 __component_adapts__ attribute will be used. The
1264 __component_adapts__ attribute is usually attribute is
1265 normally set in class definitions using adapts
1266 function, or for callables using the adapter
1267 decorator. If the factory doesn't have a
1268 __component_adapts__ adapts attribute, then this
1269 argument is required.
1270
1271 name
1272 The handler name.
1273
1274 Currently, only the empty string is accepted. Other
1275 strings will be accepted in the future when support for
1276 named handlers is added.
1277
1278 An Unregistered event is generated with an IHandlerRegistration.
1279 """
1280
1281 def registeredHandlers():
1282 """Return an iterable of IHandlerRegistration instances.
1283
1284 These registrations describe the current handler registrations
1285 in the object.
1286 """
1287
1288
1289 class IComponents(IComponentLookup, IComponentRegistry):
1290 """Component registration and access
1291 """
1292
1293
1294 # end formerly in zope.component