[Checkins] SVN: zope.introspector/trunk/src/zope/introspector/util.txt Add tests for new helper funcs.
Uli Fouquet
uli at gnufix.de
Thu Aug 14 21:34:24 EDT 2008
Log message for revision 89852:
Add tests for new helper funcs.
Changed:
U zope.introspector/trunk/src/zope/introspector/util.txt
-=-
Modified: zope.introspector/trunk/src/zope/introspector/util.txt
===================================================================
--- zope.introspector/trunk/src/zope/introspector/util.txt 2008-08-15 01:32:42 UTC (rev 89851)
+++ zope.introspector/trunk/src/zope/introspector/util.txt 2008-08-15 01:34:23 UTC (rev 89852)
@@ -155,3 +155,143 @@
SyntaxError: invalid syntax
+get_attributes(obj, public_only=True)
+======================================
+
+Return a list of attribute names.
+
+If `public_only` is set to `False` also attribute names that start
+with an underscore ('_') are returned::
+
+ >>> from zope.introspector.util import get_attributes
+ >>> from zope.introspector.code import Package
+ >>> get_attributes(Package)
+ ['getModuleInfo', 'getPath']
+
+ >>> get_attributes(Package, public_only=False)
+ ['__class__', '__delattr__', ..., 'getPath']
+
+
+get_python_path(obj)
+====================
+
+Return the path of the object in standard Python dot-notation.
+
+This function makes only sense for objects that provide a name, since we
+cannot determine the path otherwise. Instances, for example, do not have a
+`__name__` attribute, so we would expect them to fail.
+
+For interfaces we simply get::
+
+ >>> from zope.introspector.util import get_python_path
+ >>> from zope.introspector.interfaces import IInfo
+ >>> get_python_path(IInfo)
+ 'zope.introspector.interfaces.IInfo'
+
+and for classes::
+
+ >>> from zope.introspector.code import PackageInfo
+ >>> get_python_path(PackageInfo)
+ 'zope.introspector.code.PackageInfo'
+
+One can also pass functions::
+
+ >>> get_python_path(get_python_path)
+ 'zope.introspector.util.get_python_path'
+
+and even methods. If a method is passed in, its class path is returned::
+
+ >>> get_python_path(PackageInfo.getPath)
+ 'zope.introspector.code.PackageInfo'
+
+Modules are another kind of objects that can return a python path::
+
+ >>> from zope.introspector import util
+ >>> get_python_path(util)
+ 'zope.introspector.util'
+
+Passing in `None` returns `None`::
+
+ >>> util.get_python_path(None)
+
+Clearly, instance lookups should fail::
+
+ >>> get_python_path(PackageInfo(None))
+ Traceback (most recent call last):
+ ...
+ AttributeError: 'PackageInfo' object has no attribute '__name__'
+
+
+get_interface_for_attribute(name, interfaces=_marker, klass=_marker, as_path=True)
+----------------------------------------------------------------------------------
+
+Determine the interface in which an attribute is defined. This
+function is nice, if you have an attribute name which you retrieved
+from a class and want to know which interface requires it to be there.
+
+Either the `interfaces` or `klass` argument must be specified. If
+`interfaces` is not specified, the `klass` is used to retrieve a list
+of interfaces. `interfaces` must be iterable.
+
+`as_path` specifies whether the dotted name of the interface or the
+interface object is returned.
+
+First, we need to create some interfaces and a class that implements
+them::
+
+ >>> from zope.interface import Interface, Attribute, implements
+ >>> class I1(Interface):
+ ... attr = Attribute('attr')
+
+ >>> class I2(I1):
+ ... def getAttr():
+ ... '''get attr'''
+
+ >>> class Sample(object):
+ ... implements(I2)
+
+First we check whether an aatribute can be found in a list of
+interfaces::
+
+ >>> from zope.introspector.util import get_interface_for_attribute
+ >>> get_interface_for_attribute('attr', (I1, I2), as_path=False)
+ <InterfaceClass __builtin__.I1>
+ >>> get_interface_for_attribute('getAttr', (I1, I2), as_path=False)
+ <InterfaceClass __builtin__.I2>
+
+Now we are repeating the same lookup, but using the class, instead of
+a list of interfaces::
+
+ >>> get_interface_for_attribute('attr', klass=Sample, as_path=False)
+ <InterfaceClass __builtin__.I1>
+ >>> get_interface_for_attribute('getAttr', klass=Sample, as_path=False)
+ <InterfaceClass __builtin__.I2>
+
+By default, `as_path` is `True`, which means the path of the interface
+is returned::
+
+ >>> get_interface_for_attribute('attr', (I1, I2))
+ '__builtin__.I1'
+
+If no match is found, ``None`` is returned::
+
+ >>> get_interface_for_attribute('attr2', (I1, I2)) is None
+ True
+ >>> get_interface_for_attribute('attr2', klass=Sample) is None
+ True
+
+If both, the `interfaces` and `klass` argument are missing, raise an
+error::
+
+ >>> get_interface_for_attribute('getAttr')
+ Traceback (most recent call last):
+ ...
+ ValueError: need to specify interfaces or klass
+
+Similarly, it does not make sense if both are specified::
+
+ >>> get_interface_for_attribute('getAttr', interfaces=(I1,I2),
+ ... klass=Sample)
+ Traceback (most recent call last):
+ ...
+ ValueError: must specify only one of interfaces and klass
More information about the Checkins
mailing list