PyGObject GTK+ 3 - 文档？

Posted 2023-04-14

【中文标题】PyGObject GTK+ 3 - 文档？

【英文标题】：PyGObject GTK+ 3 - Documentation?

【发布时间】：2012-07-20 03:30:27

【问题描述】：

PyGObject 似乎没有真正的文档。 This tutorial 非常接近。我整个早上都在苦苦挣扎，只是想找到Gtk.Window 构造函数接受的参数的描述。看来我不能在 Python 中做太多反射，因为 PyGObject 中的所有内容都是动态生成的。

我只想知道我可以传递给这个构造函数的参数！在 GTK+ 3 文档中似乎没有此对象的等效项，并且阅读源代码以找出绑定已被证明是一项极其艰巨的任务。有什么想法吗？？

【参考方案1】：

我同意这是当前状态下 PyGObject 的一个巨大缺点。对于我们这些已经使用 GTK+ 一段时间的人来说，这没问题，但对于新用户来说，这可能会让人感到困惑。

人们正在开发一个系统来自动生成除 C 之外的其他语言的文档，即 GObject Introspection Doctools。由于这还没有完全准备好，最好使用C API documentation 并了解它如何转换为 Python。这并不像听起来那么难。

请记住，Python 调用是动态包装到底层 C 库的。您需要做的就是了解一些东西通常是如何翻译成 Python 的，并了解 GTK+“属性”是如何工作的。它基本上是 C 中的命名约定，并且模式很容易学习。 PyGObject/Introspection Porting 页面是一个好的开始。

Python 中的构造函数通常包装在 C 中的 *_new() 函数中。PyGObject 还允许您将属于该小部件的 任何 GTK+ 属性作为构造函数中的关键字参数传递。因此，在 Python 中构建小部件时，您有很多选择。

你提到了GtkWindow。如果您查看GtkWindow Documentation，gtk_window_new() 函数将窗口类型作为 C 中的参数。这将是 Python 中构造函数的位置参数。 PyGObject “覆盖”构造函数，因此 type 是可选的，并且默认为***窗口。有一堆GtkWindow properties 也可以作为关键字参数传递给构造函数。

以下是在 Python 中构造 Gtk.Window 的 3 个示例，它们在功能上是等效的：

# 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")

Python 交互式控制台是试验小部件和属性的好方法。

【讨论】：

谢谢，对 PyGObject 明显的巫术非常有帮助的洞察力。也许有解决这种疯狂的方法。哈哈

【参考方案2】：

文档位于此处： https://lazka.github.io/pgi-docs/Gtk-3.0/index.html

这里的 Gtk.Window 参数（正是您所要求的）： https://lazka.github.io/pgi-docs/Gtk-3.0/classes/Window.html

上面存在一些交互式控制台解决方案，但我更喜欢自动完成的解决方案： How do I add tab completion to the Python shell?

【参考方案3】：

稍微扩展一下已接受的答案； GObject Introspection Doctools 页面有一节介绍如何创建自己的文档。

在 Ubuntu 12.04.2 LTS 上，您可以发出以下命令：

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

【讨论】：

在 Linux Mint 14（基于 Ubuntu 12.10）上测试，您必须创建 output_dir。 yelp 查看器对我不起作用，但 yelp build 命令可以（警告：输出文件放在当前目录中）。这是一个快速的 shell 单行代码，用于在 /usr/share/gir-1.0 中构建所有 gir 的 HTML 文档（将 -P 9 替换为所需的并行作业数，〜您机器中的内核数）：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'

这是获取文档的正确方法。确保您拥有所需的所有.girs。根据 fakegir 的说法，您可以使用 apt-file search ".gir" | grep -i unity 来检查 .gir

【参考方案4】：

您可以使用 this 检索对象的所有属性

dir(YouObjectInstance.props)

YourObjectInstance 当然是你创建的任何实例。

简单的方法可能是打开一个终端：

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']
>>> 

现在您可以即时记录对象的属性。

如果你需要这些方法？

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

如果你想反思，你可以去这个链接：reflection api 这将为您节省大量时间。它也可以被修改为接受任何对象或被继承。

您还可以使用： 帮助（SomeClassModuleOrFunction）

虽然来自 help() 的打印文本可能会受到限制，但使用 instance.props 并在实例上循环也可能有缺点，具体取决于代码的文档记录程度。

使用上述任何一种方法至少可以获得一些文档。如果一个不适合您需要的，请尝试另一个。

【讨论】：

试试help(SomeClassModuleOrFunction)。

杰拉尔多。 help() 已添加到答案中。这似乎是显而易见的选择，但输出的质量取决于模块。虽然 help() 确实有它的用处。

【参考方案5】：

使用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)

更多详情

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