This module provides a variety of utility functions and classes used by the
protocols package. None of them are really specific to the
protocols package, and so may be useful to other libraries or
||callback [, depth=2])|
Set up callback to be called with the containing class, once it is
created. This function is designed to be called by an ``advising'' function
(such as protocols.advise()) executed in the body of a class suite.
The ``advising'' function supplies a callback that it wishes to have executed
when the containing class is created. The callback will be given one argument:
the newly created containing class. The return value of the callback will be
used in place of the class, so the callback should return the input if
it does not wish to replace the class.
The optional depth argument determines the number of frames between this
function and the targeted class suite. depth defaults to 2, since this
skips this function's frame and one calling function frame. If you use this
function from a function called directly in the class suite, the default will
be correct, otherwise you will need to determine the correct depth yourself.
This function works by installing a special class factory function in
place of the __metaclass__ of the containing class. Therefore, only
callbacks after the last __metaclass__ assignment in the
containing class will be executed. Be sure that classes using ``advising''
functions declare any __metaclass__ first, to ensure all
callbacks are run.
Returns truth if ob is a class advisor function. This is used to
determine if a __metaclass__ value is a ``magic'' metaclass installed
by addClassAdvisor(). If so, then ob will have a
previousMetaclass attribute pointing to the previous metaclass,
if any, and a callback attribute containing the callback that was
given to addClassAdvisor().
(kind,module,locals,globals) tuple for
the supplied frame object. The returned kind is a string: either
``exec'', ``module'', ``class'', ``function call'', or ``unknown''.
module is the module object the frame is/was executed in, or
None if the frame's globals could not be correlated with a module in
sys.modules. locals and globals are the frame's local
and global dictionaries, respectively. Note that they can be the same
dictionary, and that modifications to locals may not have any effect on the
execution of the frame.
This function is used by functions like addClassAdvisor() and
advise() to verify where they're being called from, and to work
their respective magics.
||ob [, extendedClassic=False])|
Return an iterable over the ``method resolution order'' of ob. If
ob is a ``new-style'' class or type, this returns its __mro__
attribute. If ob is a ``classic'' class, this returns
classicMRO(ob,extendedClassic). If ob is not a class
or type of any kind, a one-element sequence containing just ob is
||ob [, extendedClassic=False])|
Return an iterator over the ``method resolution order'' of classic class
ob, following the ``classic'' method resolution algorithm of recursively
traversing __bases__ from left to right. (Note that this may return
the same class more than once, for some inheritance graphs.) If
varextendedClassic is a true value, InstanceType and object
are added at the end of the iteration. This is used by Protocol
objects to allow generic adapters for InstanceType and object
to be used with ``classic'' class instances.
||bases [, explicit_mc=None])|
Determine the metaclass that would be used by Python, given a non-empty
sequence of base classes, and an optional explicitly supplied
__metaclass__. Returns ClassType if all bases are ``classic''
and there is no explicit_mc. Raises TypeError if the bases'
metaclasses are incompatible, just like Python would.
Return the shortest ordered subset of the input sequence classes that
still contains the ``most specific'' classes. That is, the result sequence
contains only classes that are not subclasses of each other. This function is
used by determineMetaclass() to narrow down its list of candidate
metaclasses, but is also useful for dynamically generating metaclasses.
If ob is weak-referenceable, returns
weakref.ref(ob,callable). Otherwise, returns a
StrongRef(ob), emulating the interface of
This is used by code that wants to use weak references, but may be given
objects that are not weak-referenceable. Note that callable, if
supplied, will not be called if ob is not weak-referenceable.
An object that emulates the interface of weakref.ref(). When called,
an instance of StrongRef will return the ob it was created for.
Also, it will hash the same as ob and compare equal to it. Thus, it
can be used as a dictionary key, as long as the underlying object can. Of
course, since it is not really a weak reference, it does not contribute to the
garbage collection of the underlying object, and may in fact hinder it, since
it holds a live reference to the object.