{"id":24335,"library":"pygobject-stubs","title":"PyGObject Stubs","description":"Typing stubs for PyGObject, providing type hints for GLib, GObject, Gtk, Gdk, Gio, and other GNOME libraries. Version 2.17.0 supports Python >=3.10. This package enables static type checking (mypy, pyright) for PyGObject code and is actively maintained alongside PyGObject releases. Release cadence is irregular, tied to GNOME releases and bug fixes.","status":"active","version":"2.17.0","language":"python","source_language":"en","source_url":"https://github.com/gnome-js/pygobject-stubs","tags":["type-hints","pygobject","gtk","gnome","stubs","mypy"],"install":[{"cmd":"pip install pygobject-stubs","lang":"bash","label":"Install latest stable"},{"cmd":"pip install 'pygobject-stubs>=2.17.0'","lang":"bash","label":"Install with version pin"}],"dependencies":[{"reason":"Stubs annotate PyGObject's C extensions; runtime typing not needed but required for correct usage.","package":"PyGObject","optional":true},{"reason":"Commonly used for type-checking with these stubs.","package":"mypy","optional":true}],"imports":[{"note":"The 'gi.repository' submodule is required for correct stubs resolution.","wrong":"from gi import Gtk; win = Gtk.Window()","symbol":"Gtk.Window","correct":"from gi.repository import Gtk; win = Gtk.Window()"},{"note":"GLib is part of the gi.repository namespace, not a top-level module.","wrong":"import GLib; loop = GLib.MainLoop()","symbol":"GLib.MainLoop","correct":"from gi.repository import GLib; loop = GLib.MainLoop()"}],"quickstart":{"code":"from gi.repository import Gtk, Gio\n\n# Attempt to get the default display (succeeds only if running under X11/Wayland)\ndisplay = Gdk.Display.get_default()\nif display is None:\n    raise RuntimeError('No display available: ensure DISPLAY or WAYLAND_DISPLAY is set')\n# Example: create a simple window (won't show without main loop; just for type-checking)\nwin = Gtk.Window.new(Gtk.WindowType.TOPLEVEL)\nwin.set_default_size(200, 200)\nwin.show_all()\n# Type-check with mypy: mypy --enable-incomplete-feature=GenericParenTypeHints script.py","lang":"python","description":"Quickstart example showing correct import pattern and basic usage for type-checking."},"warnings":[{"fix":"Run mypy with --strict only if you accept suppressing many errors, or use --warn-unused-ignores to track where stubs are missing.","message":"Stubs are NOT complete: many functions have missing or overly generic type hints. Use `Any` or `# type: ignore` for uncovered APIs.","severity":"gotcha","affected_versions":"all"},{"fix":"Install PyGObject first: pip install PyGObject && pip install pygobject-stubs","message":"Install order matters: pygobject-stubs must be installed AFTER PyGObject to ensure correct bytecode compilation. Otherwise, stubs may not be recognized.","severity":"gotcha","affected_versions":"all"},{"fix":"If targetting GTK4, install gtk4-stubs and use from gi.repository import Gtk4 (if available)","message":"Stubs for GTK3 vs GTK4 are separate; pygobject-stubs covers GTK3. For GTK4, use gtk4-stubs (not included).","severity":"deprecated","affected_versions":"all"},{"fix":"Upgrade mypy: pip install 'mypy>=1.0'","message":"mypy version incompatibility: old mypy (<0.990) may fail to find stubs. Ensure mypy >=1.0 for best results.","severity":"gotcha","affected_versions":"<=2.17.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install pygobject-stubs with pip, and ensure mypy sees it (automatic in virtualenv). For custom environments, set MYPYPATH to the site-packages of the venv.","cause":"pygobject-stubs not installed or not found by mypy because stubs are not in the MYPYPATH.","error":"Cannot find implementation or library stub for module 'gi.repository.Gtk'"},{"fix":"Install system packages: libgirepository1.0-dev (Ubuntu/Debian), glib2-devel (Fedora), or glib-devel (macOS via Homebrew). Then reinstall PyGObject.","cause":"PyGObject runtime library (libgobject-introspection) not installed or gi module not found.","error":"from gi.repository import Gtk; TypeError: 'gi.repository' is not a package"},{"fix":"Use Gtk.WindowType.TOPLEVEL instead of raw integer. If stub mismatch, cast: Gtk.Window.new(Gtk.WindowType(0))","cause":"Stubs define Gtk.Window.new with Gtk.WindowType enum, but often code passes an integer (e.g., 0). Enum is required for type checking.","error":"No overloads of 'Gtk.Window.new' match argument types (int)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}