[Checkins] SVN: zope.introspector/trunk/src/zope/introspector/ Update tests.

[Uli Fouquet]

Log message for revision 89709:
  Update tests.

Changed:
  U   zope.introspector/trunk/src/zope/introspector/code.txt
  U   zope.introspector/trunk/src/zope/introspector/util.txt

-=-
Modified: zope.introspector/trunk/src/zope/introspector/code.txt
===================================================================
--- zope.introspector/trunk/src/zope/introspector/code.txt	2008-08-12 11:25:39 UTC (rev 89708)
+++ zope.introspector/trunk/src/zope/introspector/code.txt	2008-08-12 11:26:06 UTC (rev 89709)
@@ -250,7 +250,7 @@
 
   >>> func_names = [x.dotted_name.split('.')[-1] for x in func_list]
   >>> sorted(func_names)
-  ['get_namespace_package_items', ..., 'resolve']
+  ['get_function_signature', ..., 'resolve']
 
 
 Files

Modified: zope.introspector/trunk/src/zope/introspector/util.txt
===================================================================
--- zope.introspector/trunk/src/zope/introspector/util.txt	2008-08-12 11:25:39 UTC (rev 89708)
+++ zope.introspector/trunk/src/zope/introspector/util.txt	2008-08-12 11:26:06 UTC (rev 89709)
@@ -47,3 +47,111 @@
 The function ignores directories that are not Python packages and
 hidden files and directories, i.e. such starting with a dot in their
 name.
+
+
+getFunctionSignature(func)
+==========================
+
+This helper function was taken from ``zope.app.apidoc``.
+
+Return the signature of a function or method. The `func` argument *must* be a
+generic function or a method of a class.
+
+First, we get the signature of a function that has a specific positional and
+keyword argument:
+
+  >>> from zope.introspector.util import get_function_signature
+  >>> def func(attr, attr2=None):
+  ...     pass
+  >>> get_function_signature(func)
+  '(attr, attr2=None)'
+
+Here is a function that has an unspecified amount of keyword arguments:
+
+  >>> def func(attr, **kw):
+  ...     pass
+  >>> get_function_signature(func)
+  '(attr, **kw)'
+
+And here we mix specified and unspecified keyword arguments:
+
+  >>> def func(attr, attr2=None, **kw):
+  ...     pass
+  >>> get_function_signature(func)
+  '(attr, attr2=None, **kw)'
+
+In the next example we have unspecified positional and keyword arguments:
+
+  >>> def func(*args, **kw):
+  ...     pass
+  >>> get_function_signature(func)
+  '(*args, **kw)'
+
+And finally an example, where we have on unspecified keyword arguments without
+any positional arguments:
+
+  >>> def func(**kw):
+  ...     pass
+  >>> get_function_signature(func)
+  '(**kw)'
+
+Next we test whether the signature is correctly determined for class
+methods. Note that the `self` argument is removed from the signature, since it
+is not essential for documentation.
+
+We start out with a simple positional argument:
+
+  >>> class Klass(object):
+  ...     def func(self, attr):
+  ...         pass
+  >>> get_function_signature(Klass.func)
+  '(attr)'
+
+Next we have specific and unspecified positional arguments as well as
+unspecified keyword arguments:
+
+  >>> class Klass(object):
+  ...     def func(self, attr, *args, **kw):
+  ...         pass
+  >>> get_function_signature(Klass.func)
+  '(attr, *args, **kw)'
+
+If you do not pass a function or method to the function, it will fail:
+
+  >>> get_function_signature('func')
+  Traceback (most recent call last):
+  ...
+  TypeError: func must be a function or method
+
+A very uncommon, but perfectly valid, case is that tuple arguments are
+unpacked inside the argument list of the function. Here is an example:
+
+  >>> def func((arg1, arg2)):
+  ...     pass
+  >>> get_function_signature(func)
+  '((arg1, arg2))'
+
+Even default assignment is allowed:
+
+  >>> def func((arg1, arg2)=(1, 2)):
+  ...     pass
+  >>> get_function_signature(func)
+  '((arg1, arg2)=(1, 2))'
+
+However, lists of this type are not allowed inside the argument list:
+
+  >>> def func([arg1, arg2]):
+  ...     pass
+  Traceback (most recent call last):
+  ...
+  SyntaxError: invalid syntax
+
+Internal assignment is also not legal:
+
+  >>> def func((arg1, arg2=1)):
+  ...     pass
+  Traceback (most recent call last):
+  ...
+  SyntaxError: invalid syntax
+
+