Introspection on pygtk3 possible?

Question

One of the great things of python is the ability to have introspection on methods and functions. As an example, to get the function signature of math.log you can (in ipython) run this:

In [1]: math.log?
Type:       builtin_function_or_method
Base Class: <type 'builtin_function_or_method'>
String Form:    <built-in function log>
Namespace:  Interactive
Docstring:
    log(x[, base])

    Return the logarithm of x to the given base.
    If the base not specified, returns the natural logarithm (base e) of x.

And see that x and optionally base are the parameters of this function.

With the new gtk3 and the automaticall generated pygobject bindings, I can in all examples I tried only ever get (*args, **kwargs) as the parameters of every gtk method.

Example: Label.set_text which requires a string:

In [1]: from gi.repository import Gtk
In [2]: mylabel = Gtk.Label("hello")
In [3]: mylabel.set_text?
Type:       instancemethod
Base Class: <type 'instancemethod'>
String Form:    <bound method Label.set_text of <Label object at 0x275b230 (GtkLabel at 0x28cd040)>>
Namespace:  Interactive
File:       /usr/lib/python2.7/dist-packages/gi/types.py
Definition: L.set_text(*args, **kwargs)
Docstring:
    <no docstring>

NOW THE QUESTION: is this (the loss of method introspection for python bindings) something that will change once more (documentation) effort has gone into pygobjects or is this something that is here to stay due to the way pygobjects works?

Answer 1

Right now, I think this isn't yet ready. However, you can still do manual introspection looking at Gtk-3.0.gir file (in my system located in /usr/share/gir-1.0/Gtk-3.0.gir).

The gir file is just an xml file that is supposed to be used exactly to explore the exposed interface regardless of the programming language that you are using. For example, the Label class can be found looking for <class name="Label". Inside the class tag there's a doc tag with extensive information about what this widget is supposed to do. Also there are many method tags and one of them is the one you're interested in in you example: <method name="set_text". Inside this method tag there's not only a doc tag that describes the method, but also a parameters tag that, in turn, contains some parameter tag that are used to describe each parameter in terms of name, description and type:

<parameters>
  <parameter name="str" transfer-ownership="none">
    <doc xml:whitespace="preserve">The text you want to set</doc>
    <type name="utf8" c:type="gchar*"/>
  </parameter>
</parameters>

So all the information is already there.

Answer 2

I believe this would be the way the C API for creating python modules does it. For example:

>>> import inspect
>>> inspect.getargspec(math.log)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Python27\lib\inspect.py", line 813, in getargspec
    raise TypeError('{!r} is not a Python function'.format(func))
TypeError: <built-in function log> is not a Python function

The only way (that I know of) is to look at method parameters for built-in functions is to look at the doc string.

>>> help(math.log)
Help on built-in function log in module math:

log(...)
    log(x[, base])

    Return the logarithm of x to the given base.
    If the base not specified, returns the natural logarithm (base e) of x.

I've written my own C python module, and have looked for ways to "fix" the (...) and the workaround is to place it in the doc string which I consider error prone as I'd have to update the doc string every time I change the function.

Answer 3

You can use another built-in functions like dir(), vars(), etc.

http://docs.python.org/library/functions.html

Another useful tools is pydoc:

pydoc gi.repository.Gtk