GNOME Bugzilla – Bug 679804
help(gi.repository.*) does not show module contents
Last modified: 2012-07-16 16:11:43 UTC
How does one find the python classes, methods etc in a gi module? Some are OK, like Gtk, because they're adequately documented and have logical and consistent names and layouts. But the cairo module, for example, is unusable. I can't find anything in it which maps logically to the C API or the old python API and help(cairo) and cairo.__dir__ tell me hardly anything useful, nor can I find any documentation for it. Normal python modules can be introspected, so it's ironic, as well as highly frustrating, that this system, with "introspection" in its name, disables introspection! Surely there must be some way that useful information about a gi module's python API can be provided.
FYI: A temporal workaround for "introspect" at least attributes, constants or functions it is use the ipython interpeter. It enables the autocompletition pressing tab key (like bash). A example: $ ipython Python 2.7.3 (default, Apr 20 2012, 22:44:07) Type "copyright", "credits" or "license" for more information. IPython 0.13 -- An enhanced Interactive Python. ? -> Introduction and overview of IPython's features. %quickref -> Quick reference. help -> Python's own help system. object? -> Details about 'object', use 'object??' for extra details. In [1]: import cairo In [2]: cairo. Display all 105 possibilities? (y or n) cairo.ANTIALIAS_DEFAULT cairo.FILTER_FAST cairo.HAS_GLITZ_SURFACE cairo.HINT_STYLE_NONE cairo.OPERATOR_DEST_OVER cairo.SUBPIXEL_ORDER_DEFAULT cairo.ANTIALIAS_GRAY cairo.FILTER_GAUSSIAN cairo.HAS_IMAGE_SURFACE cairo.HINT_STYLE_SLIGHT cairo.OPERATOR_IN cairo.SUBPIXEL_ORDER_RGB cairo.ANTIALIAS_NONE cairo.FILTER_GOOD cairo.HAS_PDF_SURFACE cairo.ImageSurface cairo.OPERATOR_OUT cairo.SUBPIXEL_ORDER_VBGR cairo.ANTIALIAS_SUBPIXEL cairo.FILTER_NEAREST cairo.HAS_PNG_FUNCTIONS cairo.LINE_CAP_BUTT cairo.OPERATOR_OVER cairo.SUBPIXEL_ORDER_VRGB cairo.CAPI cairo.FONT_SLANT_ITALIC cairo.HAS_PS_SURFACE cairo.LINE_CAP_ROUND cairo.OPERATOR_SATURATE cairo.SVGSurface cairo.CONTENT_ALPHA cairo.FONT_SLANT_NORMAL cairo.HAS_QUARTZ_SURFACE cairo.LINE_CAP_SQUARE cairo.OPERATOR_SOURCE cairo.ScaledFont cairo.CONTENT_COLOR cairo.FONT_SLANT_OBLIQUE cairo.HAS_SVG_SURFACE cairo.LINE_JOIN_BEVEL cairo.OPERATOR_XOR cairo.SolidPattern cairo.CONTENT_COLOR_ALPHA cairo.FONT_WEIGHT_BOLD cairo.HAS_USER_FONT cairo.LINE_JOIN_MITER cairo.PATH_CLOSE_PATH cairo.Surface cairo.Context cairo.FONT_WEIGHT_NORMAL cairo.HAS_WIN32_FONT cairo.LINE_JOIN_ROUND cairo.PATH_CURVE_TO cairo.SurfacePattern cairo.EXTEND_NONE cairo.FORMAT_A1 cairo.HAS_WIN32_SURFACE cairo.LinearGradient cairo.PATH_LINE_TO cairo.ToyFontFace cairo.EXTEND_PAD cairo.FORMAT_A8 cairo.HAS_XCB_SURFACE cairo.Matrix cairo.PATH_MOVE_TO cairo.XlibSurface cairo.EXTEND_REFLECT cairo.FORMAT_ARGB32 cairo.HAS_XLIB_SURFACE cairo.OPERATOR_ADD cairo.PDFSurface cairo.cairo_version cairo.EXTEND_REPEAT cairo.FORMAT_RGB24 cairo.HINT_METRICS_DEFAULT cairo.OPERATOR_ATOP cairo.PSSurface cairo.cairo_version_string cairo.Error cairo.FontFace cairo.HINT_METRICS_OFF cairo.OPERATOR_CLEAR cairo.PS_LEVEL_2 cairo.version cairo.FILL_RULE_EVEN_ODD cairo.FontOptions cairo.HINT_METRICS_ON cairo.OPERATOR_DEST cairo.PS_LEVEL_3 cairo.version_info cairo.FILL_RULE_WINDING cairo.Gradient cairo.HINT_STYLE_DEFAULT cairo.OPERATOR_DEST_ATOP cairo.Pattern cairo.FILTER_BEST cairo.HAS_ATSUI_FONT cairo.HINT_STYLE_FULL cairo.OPERATOR_DEST_IN cairo.RadialGradient cairo.FILTER_BILINEAR cairo.HAS_FT_FONT cairo.HINT_STYLE_MEDIUM cairo.OPERATOR_DEST_OUT cairo.SUBPIXEL_ORDER_BGR In [3]: from gi.repository import Pango In [4]: Pango. Display all 118 possibilities? (y or n) Pango.ANALYSIS_FLAG_CENTERED_BASELINE Pango.Direction Pango.Language Pango.Weight Pango.parse_stretch Pango.ATTR_INDEX_FROM_TEXT_BEGINNING Pango.ENGINE_TYPE_LANG Pango.Layout Pango.WrapMode Pango.parse_style Pango.Alignment Pango.ENGINE_TYPE_SHAPE Pango.LayoutClass Pango.attr_type_get_name Pango.parse_variant Pango.Analysis Pango.EllipsizeMode Pango.LayoutIter Pango.attr_type_register Pango.parse_weight Pango.AttrClass Pango.EngineLang Pango.LayoutLine Pango.bidi_type_for_unichar Pango.quantize_line_geometry Pango.AttrColor Pango.EngineShape Pango.LogAttr Pango.break_ Pango.read_line Pango.AttrFilterFunc Pango.Font Pango.Matrix Pango.extents_to_pixels Pango.reorder_items Pango.AttrFloat Pango.FontDescription Pango.RENDER_TYPE_NONE Pango.find_base_dir Pango.scan_int Pango.AttrFontDesc Pango.FontFace Pango.Rectangle Pango.find_paragraph_boundary Pango.scan_string Pango.AttrInt Pango.FontFamily Pango.RenderPart Pango.font_description_from_string Pango.scan_word Pango.AttrIterator Pango.FontMap Pango.Renderer Pango.get_log_attrs Pango.script_for_unichar Pango.AttrLanguage Pango.FontMask Pango.RendererClass Pango.get_mirror_char Pango.script_get_sample_language Pango.AttrList Pango.FontMetrics Pango.RendererPrivate Pango.gravity_get_for_matrix Pango.shape Pango.AttrShape Pango.Fontset Pango.SCALE Pango.gravity_get_for_script Pango.skip_space Pango.AttrSize Pango.FontsetForeachFunc Pango.Script Pango.gravity_get_for_script_and_width Pango.split_file_list Pango.AttrString Pango.GlyphGeometry Pango.ScriptIter Pango.gravity_to_rotation Pango.trim_string Pango.AttrType Pango.GlyphInfo Pango.Stretch Pango.is_zero_width Pango.unichar_direction Pango.Attribute Pango.GlyphItem Pango.Style Pango.itemize Pango.units_from_double Pango.BidiType Pango.GlyphItemIter Pango.TabAlign Pango.itemize_with_base_dir Pango.units_to_double Pango.Color Pango.GlyphString Pango.TabArray Pango.language_from_string Pango.version Pango.Context Pango.GlyphVisAttr Pango.UNKNOWN_GLYPH_HEIGHT Pango.language_get_default Pango.version_check Pango.ContextClass Pango.Gravity Pango.UNKNOWN_GLYPH_WIDTH Pango.log2vis_get_embedding_levels Pango.version_string Pango.Coverage Pango.GravityHint Pango.Underline Pango.parse_enum Pango.CoverageLevel Pango.Item Pango.Variant Pango.parse_markup
Thanks, but you imported the old cairo bindings instead of the gi ones. If I try that with gi cairo it does print some information, but much less. I still can't find the FORMAT_ constants so I can't use create_image_surface().
I'm not quite sure what you mean by "introspection". In your context I usually expect that dir() works, and it does: >>> from gi.repository import Gtk, cairo >>> dir(Gtk) ['AboutDialog', 'AboutDialogClass', ... 'tree_set_row_drag_data', 'true'] >>> dir(Gtk.Window) ['__bool__', '__class__', ... 'activate', 'activate_default', 'activate_focus', 'activate_key', 'add', ... 'unstick', 'weak_ref', 'widget'] >>> dir(cairo) >>> dir(cairo) ['Content', 'Context', ... '_version', 'image_surface_create'] >>> dir(cairo.Content) ['ALPHA', 'COLOR', help(Gtk.Window) works up to the point that the class hierarchy and methods are shown, just not the docstrings. The latter is certainly something which should be added. I do confirm that help(cairo) is rather useless. So I take it that you mean this part.
Yes, seeing as the gi bindings are derived from documentation which describes the API, making that documentation available in python's help would be really sensible, I'm surprised it was overlooked. I'm beginning to think the problem with cairo is that its gi bindings are very incomplete/broken still.
It actually applies to any help() call on a gi.repository module, updating title again.
After doing some preparatory fixes (http://git.gnome.org/browse/pygobject/commit/?id=f6cc039e and http://git.gnome.org/browse/pygobject/commit/?id=3235f1a3) I committed http://git.gnome.org/browse/pygobject/commit/?id=c0607d970 which fixes help() for modules. So you can now call help(Gtk) or help(cairo) and get the module contents description. It does not look very pretty for sure, but it's at least much more useful that the by and large empty one that we had before.
Thanks. I've applied those patches to the debian package and it's made a big improvement.