This file is indexed.

/usr/share/pyshared/zope/component/socketexample.txt is in python-zope.component 3.10.0-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
The Zope 3 Component Architecture (Socket Example)
==================================================

The component architecture provides an application framework that provides its
functionality through loosely-connected components. A *component* can be any
Python object and has a particular purpose associated with it. Thus, in a
component-based applications you have many small component in contrast to
classical object-oriented development, where you have a few big objects. 

Components communicate via specific APIs, which are formally defined by
interfaces, which are provided by the `zope.interface` package. *Interfaces*
describe the methods and properties that a component is expected to
provide. They are also used as a primary mean to provide developer-level
documentation for the components. For more details about interfaces see
`zope/interface/README.txt`.

The two main types of components are *adapters* and *utilities*. They will be
discussed in detail later in this document. Both component types are managed
by the *site manager*, with which you can register and access these
components. However, most of the site manager's functionality is hidden behind
the component architecture's public API, which is documented in
`IComponentArchitecture`.


Adapters
--------

Adapters are a well-established pattern. An *adapter* uses an object providing
one interface to produce an object that provides another interface. Here an
example: Imagine that you purchased an electric shaver in the US, and thus
you require the US socket type. You are now traveling in Germany, where another
socket style is used. You will need a device, an adapter, that converts from
the German to the US socket style.

The functionality of adapters is actually natively provided by the
`zope.interface` package and is thus well documented there. The `human.txt`
file provides a gentle introduction to adapters, whereby `adapter.txt` is
aimed at providing a comprehensive insight into adapters, but is too abstract
for many as an initial read. Thus, we will only explain adapters in the context
of the component architecture's API.

So let's say that we have a German socket

  >>> from zope.interface import Interface, implements

  >>> class IGermanSocket(Interface):
  ...     pass

  >>> class Socket(object):
  ...     def __repr__(self):
  ...         return '<instance of %s>' %self.__class__.__name__

  >>> class GermanSocket(Socket):
  ...     """German wall socket."""
  ...     implements(IGermanSocket)

and we want to convert it to an US socket

  >>> class IUSSocket(Interface):
  ...     pass

so that our shaver can be used in Germany. So we go to a German electronics
store to look for an adapter that we can plug in the wall:

  >>> class GermanToUSSocketAdapter(Socket):
  ...     implements(IUSSocket)
  ...     __used_for__ = IGermanSocket
  ...     
  ...     def __init__(self, socket):
  ...         self.context = socket

Note that I could have called the passed in socket any way I like, but
`context` is the standard name accepted.


Single Adapters
~~~~~~~~~~~~~~~

Before we can use the adapter, we have to buy it and make it part of our
inventory. In the component architecture we do this by registering the adapter
with the framework, more specifically with the global site manager:

  >>> import zope.component
  >>> gsm = zope.component.getGlobalSiteManager()
  >>> gsm.registerAdapter(GermanToUSSocketAdapter, (IGermanSocket,), IUSSocket)

`zope.component` is the component architecture API that is being
presented by this file. You registered an adapter from `IGermanSocket`
to `IUSSocket` having no name (thus the empty string).

Anyways, you finally get back to your hotel room and shave, since you have not
been able to shave in the plane. In the bathroom you discover a socket:

  >>> bathroomDE = GermanSocket()
  >>> IGermanSocket.providedBy(bathroomDE)
  True

You now insert the adapter in the German socket

  >>> bathroomUS = zope.component.getAdapter(bathroomDE, IUSSocket, '')

so that the socket now provides the US version:

  >>> IUSSocket.providedBy(bathroomUS)
  True

Now you can insert your shaver and get on with your day. 

After a week you travel for a couple of days to the Prague and you notice that
the Czech have yet another socket type:

  >>> class ICzechSocket(Interface):
  ...     pass

  >>> class CzechSocket(Socket):
  ...     implements(ICzechSocket)

  >>> czech = CzechSocket()

You try to find an adapter for your shaver in your bag, but you fail, since
you do not have one:

  >>> zope.component.getAdapter(czech, IUSSocket, '') \
  ... #doctest: +NORMALIZE_WHITESPACE
  Traceback (most recent call last):
  ...
  ComponentLookupError: (<instance of CzechSocket>, 
                         <InterfaceClass __builtin__.IUSSocket>,
                         '')

or the more graceful way:

  >>> marker = object()
  >>> socket = zope.component.queryAdapter(czech, IUSSocket, '', marker)
  >>> socket is marker
  True

In the component architecture API any `get*` method will fail with a specific
exception, if a query failed, whereby methods starting with `query*` will
always return a `default` value after a failure.


Named Adapters
~~~~~~~~~~~~~~

You are finally back in Germany. You also brought your DVD player and a couple
DVDs with you, which you would like to watch. Your shaver was able to convert
automatically from 110 volts to 240 volts, but your DVD player cannot. So you
have to buy another adapter that also handles converting the voltage and the
frequency of the AC current:

  >>> class GermanToUSSocketAdapterAndTransformer(object):
  ...     implements(IUSSocket)
  ...     __used_for__ = IGermanSocket
  ...     
  ...     def __init__(self, socket):
  ...         self.context = socket

Now, we need a way to keep the two adapters apart. Thus we register them with
a name:

  >>> gsm.registerAdapter(GermanToUSSocketAdapter,
  ...                     (IGermanSocket,), IUSSocket, 'shaver',)
  >>> gsm.registerAdapter(GermanToUSSocketAdapterAndTransformer,
  ...                     (IGermanSocket,), IUSSocket, 'dvd')

Now we simply look up the adapters using their labels (called *name*):

  >>> socket = zope.component.getAdapter(bathroomDE, IUSSocket, 'shaver')
  >>> socket.__class__ is GermanToUSSocketAdapter
  True

  >>> socket = zope.component.getAdapter(bathroomDE, IUSSocket, 'dvd')
  >>> socket.__class__ is GermanToUSSocketAdapterAndTransformer
  True

Clearly, we do not have an adapter for the MP3 player

  >>> zope.component.getAdapter(bathroomDE, IUSSocket, 'mp3') \
  ... #doctest: +NORMALIZE_WHITESPACE
  Traceback (most recent call last):
  ...
  ComponentLookupError: (<instance of GermanSocket>, 
                         <InterfaceClass __builtin__.IUSSocket>,
                         'mp3')

but you could use the 'dvd' adapter in this case of course. ;)

Sometimes you want to know all adapters that are available. Let's say you want
to know about all the adapters that convert a German to a US socket type:

  >>> sockets = list(zope.component.getAdapters((bathroomDE,), IUSSocket))
  >>> len(sockets)
  3
  >>> names = [name for name, socket in sockets]
  >>> names.sort()
  >>> names
  [u'', u'dvd', u'shaver']

`zope.component.getAdapters()` returns a list of tuples. The first
entry of the tuple is the name of the adapter and the second is the
adapter itself.


Multi-Adapters
~~~~~~~~~~~~~~

After watching all the DVDs you brought at least twice, you get tired of them
and you want to listen to some music using your MP3 player. But darn, the MP3
player plug has a ground pin and all the adapters you have do not support
that:

  >>> class IUSGroundedSocket(IUSSocket):
  ...     pass

So you go out another time to buy an adapter. This time, however, you do not
buy yet another adapter, but a piece that provides the grounding plug:

  >>> class IGrounder(Interface):
  ...     pass

  >>> class Grounder(object):
  ...     implements(IGrounder)
  ...     def __repr__(self):
  ...         return '<instance of Grounder>'


Then together they will provided a grounded us socket:

  >>> class GroundedGermanToUSSocketAdapter(object):
  ...     implements(IUSGroundedSocket)
  ...     __used_for__ = (IGermanSocket, IGrounder)
  ...     def __init__(self, socket, grounder):
  ...         self.socket, self.grounder = socket, grounder

You now register the combination, so that you know you can create a
`IUSGroundedSocket`:

  >>> gsm.registerAdapter(GroundedGermanToUSSocketAdapter,
  ...                 (IGermanSocket, IGrounder), IUSGroundedSocket, 'mp3')

Given the grounder

  >>> grounder = Grounder()

and a German socket

  >>> livingroom = GermanSocket()

we can now get a grounded US socket:

  >>> socket = zope.component.getMultiAdapter((livingroom, grounder), 
  ...                                         IUSGroundedSocket, 'mp3')

  >>> socket.__class__ is GroundedGermanToUSSocketAdapter
  True
  >>> socket.socket is livingroom
  True
  >>> socket.grounder is grounder
  True

Of course, you do not have a 'dvd' grounded US socket available:

  >>> zope.component.getMultiAdapter((livingroom, grounder),
  ...                                IUSGroundedSocket, 'dvd') \
  ... #doctest: +NORMALIZE_WHITESPACE
  Traceback (most recent call last):
  ...
  ComponentLookupError: ((<instance of GermanSocket>, 
                          <instance of Grounder>), 
                         <InterfaceClass __builtin__.IUSGroundedSocket>,
                         'dvd')


  >>> socket = zope.component.queryMultiAdapter(
  ...     (livingroom, grounder), IUSGroundedSocket, 'dvd', marker)
  >>> socket is marker
  True

Again, you might want to read `adapter.txt` in `zope.interface` for a more
comprehensive coverage of multi-adapters.

Subscribers
-----------

While subscribers are directly supported by the adapter registry and are
adapters for all theoretical purposes, practically it might be better to think
of them as separate components. Subscribers are particularly useful for
events.

Let's say one of our adapters overheated and caused a small fire:

  >>> class IFire(Interface):
  ...     pass

  >>> class Fire(object):
  ...     implements(IFire)

  >>> fire = Fire()

We want to use all available objects to put out the fire:

  >>> class IFireExtinguisher(Interface):
  ...     def extinguish():
  ...         pass

  >>> class FireExtinguisher(object):
  ...     def __init__(self, fire):
  ...         pass
  ...     def extinguish(self):
  ...         "Place extinguish code here."
  ...         print 'Used ' + self.__class__.__name__ + '.'

Here some specific methods to put out the fire:

  >>> class PowderExtinguisher(FireExtinguisher):
  ...     pass
  >>> gsm.registerSubscriptionAdapter(PowderExtinguisher, 
  ...                                 (IFire,), IFireExtinguisher)

  >>> class Blanket(FireExtinguisher):
  ...     pass
  >>> gsm.registerSubscriptionAdapter(Blanket, (IFire,), IFireExtinguisher)

  >>> class SprinklerSystem(FireExtinguisher):
  ...     pass
  >>> gsm.registerSubscriptionAdapter(SprinklerSystem,
  ...                                 (IFire,), IFireExtinguisher)

Now let use all these things to put out the fire:

  >>> extinguishers = zope.component.subscribers((fire,), IFireExtinguisher)
  >>> extinguishers.sort()
  >>> for extinguisher in extinguishers:
  ...     extinguisher.extinguish()
  Used Blanket.
  Used PowderExtinguisher.
  Used SprinklerSystem.

If no subscribers are found for a particular object, then an empty list is
returned: 

  >>> zope.component.subscribers((object(),), IFireExtinguisher)
  []


Utilities
---------

Utilities are the second type of component, the component architecture
implements. *Utilities* are simply components that provide an interface. When
you register an utility, you always register an instance (in contrast to a
factory for adapters) since the initialization and setup process of a utility
might be complex and is not well defined. In some ways a utility is much more
fundamental than an adapter, because an adapter cannot be used without another
component, but a utility is always self-contained. I like to think of
utilities as the foundation of your application and adapters as components
extending beyond this foundation.

Back to our story...

After your vacation is over you fly back home to Tampa, Florida. But it is
August now, the middle of the Hurricane season. And, believe it or not, you are
worried that you will not be able to shave when the power goes out for several
days. (You just hate wet shavers.)

So you decide to go to your favorite hardware store and by a Diesel-powered
electric generator. The generator provides of course a US-style socket:

  >>> class Generator(object):
  ...     implements(IUSSocket)
  ...     def __repr__(self):
  ...         return '<instance of Generator>'

  >>> generator = Generator()

Like for adapters, we now have to add the newly-acquired generator to our
inventory by registering it as a utility:

  >>> gsm.registerUtility(generator, IUSSocket)

We can now get the utility using

  >>> utility = zope.component.getUtility(IUSSocket)
  >>> utility is generator
  True

As you can see, it is very simple to register and retrieve utilities. If a
utility does not exist for a particular interface, such as the German socket,
then the lookup fails

  >>> zope.component.getUtility(IGermanSocket)
  Traceback (most recent call last):
  ...
  ComponentLookupError: (<InterfaceClass __builtin__.IGermanSocket>, '')

or more gracefully when specifying a default value:

  >>> default = object()
  >>> utility = zope.component.queryUtility(IGermanSocket, default=default)
  >>> utility is default
  True

Note: The only difference between `getUtility()` and `queryUtility()` is the
fact that you can specify a default value for the latter function, so that it
will never cause a `ComponentLookupError`.


Named Utilities
~~~~~~~~~~~~~~~

It is often desirable to have several utilities providing the same interface
per site. This way you can implement any sort of registry using utilities. For
this reason, utilities -- like adapters -- can be named.

In the context of our story, we might want to do the following: You really do
not trust gas stations either. What if the roads are blocked after a hurricane
and the gas stations run out of oil. So you look for another renewable power
source. Then you think about solar panels! After a storm there is usually very
nice weather, so why not? Via the Web you order a set of 110V/120W solar
panels that provide a regular US-style socket as output:

  >>> class SolarPanel(object):
  ...     implements(IUSSocket)
  ...     def __repr__(self):
  ...         return '<instance of Solar Panel>'

  >>> panel = SolarPanel()

Once it arrives, we add it to our inventory:

  >>> gsm.registerUtility(panel, IUSSocket, 'Solar Panel')

You can now access the solar panel using

  >>> utility = zope.component.getUtility(IUSSocket, 'Solar Panel')
  >>> utility is panel
  True

Of course, if a utility is not available, then the lookup will simply fail

  >>> zope.component.getUtility(IUSSocket, 'Wind Mill')
  Traceback (most recent call last):
  ...
  ComponentLookupError: (<InterfaceClass __builtin__.IUSSocket>, 'Wind Mill')

or more gracefully when specifying a default value:

  >>> default = object()
  >>> utility = zope.component.queryUtility(IUSSocket, 'Wind Mill',
  ...                                       default=default)
  >>> utility is default
  True

Now you want to look at all the utilities you have for a particular kind. The
following API function will return a list of name/utility pairs:

  >>> utils = list(zope.component.getUtilitiesFor(IUSSocket))
  >>> utils.sort()
  >>> utils #doctest: +NORMALIZE_WHITESPACE
  [(u'', <instance of Generator>), 
   (u'Solar Panel', <instance of Solar Panel>)]

Another method of looking up all utilities is by using
`getAllUtilitiesRegisteredFor(iface)`. This function will return an iterable
of utilities (without names); however, it will also return overridden
utilities. If you are not using multiple site managers, you will not actually
need this method.

  >>> utils = list(zope.component.getAllUtilitiesRegisteredFor(IUSSocket))
  >>> utils.sort()
  >>> utils
  [<instance of Generator>, <instance of Solar Panel>]


Factories
~~~~~~~~~

A *factory* is a special kind of utility that exists to create other
components. A factory is always identified by a name. It also provides a title
and description and is able to tell the developer what interfaces the created
object will provide. The advantage of using a factory to create an object
instead of directly instantiating a class or executing any other callable is
that we can refer to the factory by name. As long as the name stays fixed, the
implementation of the callable can be renamed or moved without a breakage in
code.

Let's say that our solar panel comes in parts and they have to be
assembled. This assembly would be done by a factory, so let's create one for
the solar panel. To do this, we can use a standard implementation of the
`IFactory` interface:

  >>> from zope.component.factory import Factory
  >>> factory = Factory(SolarPanel, 
  ...                   'Solar Panel',
  ...                   'This factory creates a solar panel.')

Optionally, I could have also specified the interfaces that the created object
will provide, but the factory class is smart enough to determine the
implemented interface from the class. We now register the factory:

  >>> from zope.component.interfaces import IFactory
  >>> gsm.registerUtility(factory, IFactory, 'SolarPanel')

We can now get a list of interfaces the produced object will provide:

  >>> ifaces = zope.component.getFactoryInterfaces('SolarPanel')
  >>> IUSSocket in ifaces
  True

By the way, this is equivalent to

  >>> ifaces2 = factory.getInterfaces()
  >>> ifaces is ifaces2
  True

Of course you can also just create an object:

  >>> panel = zope.component.createObject('SolarPanel')
  >>> panel.__class__ is SolarPanel
  True

Note: Ignore the first argument (`None`) for now; it is the context of the
utility lookup, which is usually an optional argument, but cannot be in this
case, since all other arguments beside the `name` are passed in as arguments
to the specified callable.

Once you register several factories

  >>> gsm.registerUtility(Factory(Generator), IFactory, 'Generator')

you can also determine, which available factories will create objects
providing a certain interface:

  >>> factories = zope.component.getFactoriesFor(IUSSocket)
  >>> factories = [(name, factory.__class__) for name, factory in factories]
  >>> factories.sort()
  >>> factories #doctest: +NORMALIZE_WHITESPACE
  [(u'Generator', <class 'zope.component.factory.Factory'>), 
   (u'SolarPanel', <class 'zope.component.factory.Factory'>)]


Site Managers
-------------

Why do we need site managers? Why is the component architecture API not
sufficient? Some applications, including Zope 3, have a concept of
locations. It is often desirable to have different configurations for these
location; this can be done by overwriting existing or adding new component
registrations. Site managers in locations below the root location, should be
able to delegate requests to their parent locations. The root site manager is
commonly known as *global site manager*, since it is always available. You can
always get the global site manager using the API:

  >>> gsm = zope.component.getGlobalSiteManager()

  >>> from zope.component import globalSiteManager
  >>> gsm is globalSiteManager
  True
  >>> from zope.component.interfaces import IComponentLookup
  >>> IComponentLookup.providedBy(gsm)
  True
  >>> from zope.component.interfaces import IComponents
  >>> IComponents.providedBy(gsm)
  True

You can also lookup at site manager in a given context. The only requirement
is that the context can be adapted to a site manager. So let's create a
special site manager:

  >>> from zope.component.globalregistry import BaseGlobalComponents
  >>> sm = BaseGlobalComponents()

Now we create a context that adapts to the site manager via the `__conform__`
method as specified in PEP 246.

  >>> class Context(object):
  ...     def __init__(self, sm):
  ...         self.sm = sm
  ...     def __conform__(self, interface):
  ...         if interface.isOrExtends(IComponentLookup):
  ...             return self.sm

We now instantiate the `Context` with our special site manager:

  >>> context = Context(sm)
  >>> context.sm is sm
  True

We can now ask for the site manager of this context:

  >>> lsm = zope.component.getSiteManager(context)
  >>> lsm is sm
  True

The site manager instance `lsm` is formally known as a *local site manager* of
`context`.