PyGObject GTK+ 3 - Documentation?

Question

PyGObject appears to have no real documentation. This tutorial is as close as it gets. I've been struggling all morning simply trying to find a description of the arguments accepted by the Gtk.Window constructor. It seems I can't do much reflection in Python because everything in PyGObject is dynamically generated.

All I want is to know what arguments I can pass to this constructor! There doesn't appear to be an equivalent of this object in the GTK+ 3 documentation, and reading the source code to figure out the bindings has proven to be an extremely daunting task. Any ideas??

Agentival

Answer 1

I agree that this is a huge shortcoming of the PyGObject in it's current state. For those of us who have been using GTK+ for a while it's no problem, but, for new users it can be confusing.

Folks are working on a system to automatically generate the docs for languages other than C which is known as GObject Introspection Doctools. Since that's not quite ready yet, your best bet to use the C API documentation and learn how it translates to Python. It's not as hard as it sounds.

Remember, the Python calls are dynamically wrapped to the underlying C library. All you need to do is learn how a few things are typically translated to Python and understand how GTK+ "properties" work. It's basically a naming convention in C and the patterns are easy to learn. The PyGObject/Introspection Porting page is a good start.

A constructor in Python is generally wrapped to the *_new() function in C. PyGObject also allows you to pass in any GTK+ property belonging to that widget as keyword arguments in the constructor. Thus, you have a lot of options when constructing widgets in Python.

You had mentioned the GtkWindow. If you look at the GtkWindow Documentation, the gtk_window_new() function takes a window type as an argument in C. This would be a positional argument to the constructor in Python. PyGObject "overrides" the constructor so that the type is optional and defaults to a top-level window. There are a bunch of GtkWindow properties that could also be passed to the constructor as keyword arguments.

Here are 3 examples of constructing a Gtk.Window in Python which are functionally equivelent:

# this is very close to how it's done in C using get_*/set_* accessors.
window = Gtk.Window(Gtk.WindowType.TOPLEVEL)
window.set_title("Hello")

# setting properties as keyword arguments to the constructor
window = Gtk.Window(type=Gtk.WindowType.TOPLEVEL, title="Hello")

# set_properties() can be used to set properties after construction
window = Gtk.Window()
window.set_properties(title="Hello")

The Python interactive console can be a great way to experiment with widgets and properties.

Ratafia

Thanks, very helpful insight into the apparent voodoo of PyGObject. Perhaps there is a method to this madness. haha – Agentival

Answer 2

The docs are located here: https://lazka.github.io/pgi-docs/Gtk-3.0/index.html

The Gtk.Window arguments (exactly what you have asked for) here: https://lazka.github.io/pgi-docs/Gtk-3.0/classes/Window.html

Some interactive console solutions exist above, but I prefer the auto-complete one: How do I add tab completion to the Python shell?

Etherize

Answer 3

To expand a little to the accepted answer; the GObject Introspection Doctools page has a section on how to create your own documentation.

On Ubuntu 12.04.2 LTS you can issue the following commands:

$> g-ir-doc-tool --language Python -o ./output_dir /usr/share/gir-1.0/Gtk-3.0.gir
$> yelp ./output_dir/index.page

Athos

Testing on Linux Mint 14 (which is based on Ubuntu 12.10), you have to create the output_dir. The yelp viewer didn't work for me, but the yelp build command did (warning: output files placed in current directory). Here's a quick shell one-liner to build HTML docs of all gir's in /usr/share/gir-1.0 (replace -P 9 with number of desired parallel jobs, ~number of cores in your machine): ls /usr/share/gir-1.0 | grep '[.]gir$' | xargs -I I -n 1 -P 9 sh -c 'mkdir -p I/page && g-ir-doc-tool --language Python -o I/page /usr/share/gir-1.0/I && mkdir -p I/html && cd I/html && yelp-build html ../page' – Dusty

This is the right way of getting the docs. Make sure you have all the .girs required. According to fakegir, you can check .gir using apt-file search ".gir" | grep -i unity – Case

Answer 4

You can retrieve all the properties of an object with this

dir(YouObjectInstance.props)

YourObjectInstance is any instance you create of course.

The easy way might be to open a terminal:

you@yourcomputer ~/Desktop/python $ python
Python 2.7.2+ (default, Oct  4 2011, 20:03:08) 
[GCC 4.6.1] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from gi.repository import Gtk, GtkSource, GObject
>>> window_instance = Gtk.Window()
>>> dir(window_instance.props)
['__class__', '__delattr__', '__doc__', '__format__', '__getattribute__', '__hash__', '__init__', '__iter__', '__len__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'accept_focus', 'app_paintable', 'application', 'border_width', 'can_default', 'can_focus', 'child', 'composite_child', 'decorated', 'default_height', 'default_width', 'deletable', 'destroy_with_parent', 'double_buffered', 'events', 'expand', 'focus_on_map', 'focus_visible', 'gravity', 'halign', 'has_default', 'has_focus', 'has_resize_grip', 'has_tooltip', 'has_toplevel_focus', 'height_request', 'hexpand', 'hexpand_set', 'icon', 'icon_name', 'is_active', 'is_focus', 'margin', 'margin_bottom', 'margin_left', 'margin_right', 'margin_top', 'mnemonics_visible', 'modal', 'name', 'no_show_all', 'opacity', 'parent', 'receives_default', 'resizable', 'resize_grip_visible', 'resize_mode', 'role', 'screen', 'sensitive', 'skip_pager_hint', 'skip_taskbar_hint', 'startup_id', 'style', 'title', 'tooltip_markup', 'tooltip_text', 'transient_for', 'type', 'type_hint', 'ubuntu_no_proxy', 'urgency_hint', 'valign', 'vexpand', 'vexpand_set', 'visible', 'width_request', 'window', 'window_position']
>>> 

Now you have instant documentation of the properties of the object.

If you need the methods?

for names in dir(window_instance):
    attr = getattr(window_instance,names)
    if callable(attr):
        print names,':',attr.__doc__

If you want reflection you can go to this link: reflection api That will save you tons of time. It could also be modified to accept any object or be inherited.

You can also use: help(SomeClassModuleOrFunction)

The printed text that comes from help() can be limited though, but using instance.props and loop over the instance can also have short comings depending on how well documented the code was.

Use any of the above methods to at least get some documentation. When one doesn't fit what you need try another.

Sylviesylvite

Try help(SomeClassModuleOrFunction). – Doggy

Gerardo. help() has been added to the answer. It would seem like the obvious choice, but the quality of the output depends on the module. Though help() does have it's usefulness. – Sylviesylvite

Answer 5

use IPython

In [1]: from gi.repository import Gtk
In [2]: Gtk.Window()?
Type:       GObjectMeta
String Form:<class 'gi.overrides.Gtk.Window'>
File:       /usr/lib/python3/dist-packages/gi/overrides/Gtk.py
Docstring:  <no docstring>
Constructor information:
 Definition:Gtk.Window(self, type=<enum GTK_WINDOW_TOPLEVEL of type GtkWindowType>, **kwds)

for more details

In [3]: help(Gtk.Window())

Waxwing