# gnome/pygobject architecture

> Architecture diagram of the GitHub repository gnome/pygobject, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gnome/pygobject
- Repository: https://github.com/gnome/pygobject

## Overview

PyGObject exposes Python bindings for GObject-based libraries. The main workflow is: Python imports a namespace, the dynamic importer loads its introspection module, and runtime wrappers expose library types and functions while the native extension handles calls and values. Overrides adapt APIs such as GLib, GObject, and GTK; event-loop helpers and GObject signal/property support are additional capabilities. The source index documents key module references, but several runtime implementations were not sampled, so some internal links are omitted rather than inferred.

Main entry points: [`gi/overrides/__init__.py`](https://github.com/gnome/pygobject/blob/main/gi/overrides/__init__.py) (Override framework), [`gi/gimodule.c`](https://github.com/gnome/pygobject/blob/main/gi/gimodule.c) (Native extension), [`gi/module.py`](https://github.com/gnome/pygobject/blob/main/gi/module.py) (Introspection module), [`gi/pygobject-object.c`](https://github.com/gnome/pygobject/blob/main/gi/pygobject-object.c) (GObject instances)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_loading["Namespace loading"]
  node_gi_api["GI public API<br/>[__init__.py]"]
  node_repository_import["Namespace importer<br/>[__init__.py]"]
  node_dynamic_importer["Dynamic importer<br/>[importer.py]"]
  node_dynamic_module["Introspection module<br/>[module.py]"]
end

subgraph group_native["Native binding runtime"]
  node_repository_native["GI repository<br/>[pygi-repository.c]"]
  node_extension["Native extension<br/>[gimodule.c]"]
  node_metadata["GI metadata wrappers<br/>[pygi-info.c]"]
  node_invocation["Call marshalling<br/>[pygi-invoke.c]"]
  node_type_runtime["Type wrappers<br/>[pygi-type.c]"]
  node_object_runtime["GObject instances<br/>[pygobject-object.c]"]
  node_value_runtime["Value conversion<br/>[pygi-value.c]"]
end

subgraph group_adaptation["API adaptations"]
  node_override_framework["Override framework<br/>[__init__.py]"]
  node_glib_override["GLib overrides<br/>[GLib.py]"]
  node_gobject_override["GObject overrides<br/>[GObject.py]"]
  node_gtk_override["GTK overrides<br/>[Gtk.py]"]
end

subgraph group_events["Events and callbacks"]
  node_event_loop["Event loop helpers<br/>[events.py]"]
  node_signal_helper["Signal helpers<br/>[_signalhelper.py]"]
  node_signal_support["Signal closures"]
  node_async_support["Async marshalling<br/>[pygi-async.c]"]
end

node_python_user(("Python application"))

node_python_user -->|"uses bindings"| node_gi_api
node_gi_api -->|"selects versions"| node_repository_native
node_repository_import -->|"registers importer"| node_dynamic_importer
node_dynamic_importer -.->|"loads namespace"| node_dynamic_module
node_dynamic_module -->|"requires and looks up"| node_repository_native
node_extension -->|"registers types"| node_repository_native
node_extension -->|"registers types"| node_metadata
node_metadata -->|"uses call metadata"| node_invocation
node_dynamic_module -->|"creates wrappers"| node_type_runtime
node_type_runtime -->|"uses object wrappers"| node_object_runtime
node_object_runtime -->|"converts properties"| node_value_runtime
node_invocation -.->|"marshals values"| node_value_runtime
node_override_framework -->|"imports registry"| node_dynamic_importer
node_glib_override -->|"registers adaptations"| node_override_framework
node_gobject_override -->|"registers adaptations"| node_override_framework
node_gtk_override -->|"registers adaptations"| node_override_framework
node_glib_override -->|"runs event loop"| node_event_loop
node_event_loop -->|"uses signal helpers"| node_gi_api
node_gobject_override -->|"uses helpers"| node_signal_helper
node_object_runtime -->|"uses closures"| node_signal_support
node_extension -->|"registers types"| node_async_support

click node_gi_api "https://github.com/gnome/pygobject/blob/main/gi/__init__.py"
click node_repository_import "https://github.com/gnome/pygobject/blob/main/gi/repository/__init__.py"
click node_dynamic_importer "https://github.com/gnome/pygobject/blob/main/gi/importer.py"
click node_dynamic_module "https://github.com/gnome/pygobject/blob/main/gi/module.py"
click node_repository_native "https://github.com/gnome/pygobject/blob/main/gi/pygi-repository.c"
click node_extension "https://github.com/gnome/pygobject/blob/main/gi/gimodule.c"
click node_metadata "https://github.com/gnome/pygobject/blob/main/gi/pygi-info.c"
click node_invocation "https://github.com/gnome/pygobject/blob/main/gi/pygi-invoke.c"
click node_type_runtime "https://github.com/gnome/pygobject/blob/main/gi/pygi-type.c"
click node_object_runtime "https://github.com/gnome/pygobject/blob/main/gi/pygobject-object.c"
click node_value_runtime "https://github.com/gnome/pygobject/blob/main/gi/pygi-value.c"
click node_override_framework "https://github.com/gnome/pygobject/blob/main/gi/overrides/__init__.py"
click node_glib_override "https://github.com/gnome/pygobject/blob/main/gi/overrides/GLib.py"
click node_gobject_override "https://github.com/gnome/pygobject/blob/main/gi/overrides/GObject.py"
click node_gtk_override "https://github.com/gnome/pygobject/blob/main/gi/overrides/Gtk.py"
click node_event_loop "https://github.com/gnome/pygobject/blob/main/gi/events.py"
click node_signal_helper "https://github.com/gnome/pygobject/blob/main/gi/_signalhelper.py"
click node_signal_support "https://github.com/gnome/pygobject/blob/main/gi/pygi-signal-closure.c"
click node_async_support "https://github.com/gnome/pygobject/blob/main/gi/pygi-async.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gi_api,node_repository_import,node_dynamic_importer,node_dynamic_module toneBlue
class node_repository_native,node_extension,node_metadata,node_invocation,node_type_runtime,node_object_runtime,node_value_runtime toneAmber
class node_override_framework,node_glib_override,node_gobject_override,node_gtk_override toneMint
class node_event_loop,node_signal_helper,node_signal_support,node_async_support toneRose
class node_python_user toneIndigo
```

## Components

### Namespace loading

- [GI public API](https://github.com/gnome/pygobject/blob/main/gi/__init__.py): `gi/__init__.py`
- [Namespace importer](https://github.com/gnome/pygobject/blob/main/gi/repository/__init__.py): `gi/repository/__init__.py`
- [Dynamic importer](https://github.com/gnome/pygobject/blob/main/gi/importer.py): `gi/importer.py`
- [Introspection module](https://github.com/gnome/pygobject/blob/main/gi/module.py): `gi/module.py`

### Native binding runtime

- [GI repository](https://github.com/gnome/pygobject/blob/main/gi/pygi-repository.c): `gi/pygi-repository.c`
- [Native extension](https://github.com/gnome/pygobject/blob/main/gi/gimodule.c): `gi/gimodule.c`
- [GI metadata wrappers](https://github.com/gnome/pygobject/blob/main/gi/pygi-info.c): `gi/pygi-info.c`
- [Call marshalling](https://github.com/gnome/pygobject/blob/main/gi/pygi-invoke.c): `gi/pygi-invoke.c`
- [Type wrappers](https://github.com/gnome/pygobject/blob/main/gi/pygi-type.c): `gi/pygi-type.c`
- [GObject instances](https://github.com/gnome/pygobject/blob/main/gi/pygobject-object.c): `gi/pygobject-object.c`
- [Value conversion](https://github.com/gnome/pygobject/blob/main/gi/pygi-value.c): `gi/pygi-value.c`

### API adaptations

- [Override framework](https://github.com/gnome/pygobject/blob/main/gi/overrides/__init__.py): `gi/overrides/__init__.py`
- [GLib overrides](https://github.com/gnome/pygobject/blob/main/gi/overrides/GLib.py): `gi/overrides/GLib.py`
- [GObject overrides](https://github.com/gnome/pygobject/blob/main/gi/overrides/GObject.py): `gi/overrides/GObject.py`
- [GTK overrides](https://github.com/gnome/pygobject/blob/main/gi/overrides/Gtk.py): `gi/overrides/Gtk.py`

### Events and callbacks

- [Event loop helpers](https://github.com/gnome/pygobject/blob/main/gi/events.py): `gi/events.py`
- [Signal helpers](https://github.com/gnome/pygobject/blob/main/gi/_signalhelper.py): `gi/_signalhelper.py`
- [Signal closures](https://github.com/gnome/pygobject/blob/main/gi/pygi-signal-closure.c): `gi/pygi-signal-closure.c`
- [Async marshalling](https://github.com/gnome/pygobject/blob/main/gi/pygi-async.c): `gi/pygi-async.c`

### Other components

- **Python application**

## Connections

- Python application → GI public API: uses bindings
- GI public API → GI repository: selects versions (evidence: `gi/__init__.py`)
- Namespace importer → Dynamic importer: registers importer (evidence: `gi/repository/__init__.py`)
- Dynamic importer → Introspection module: loads namespace
- Introspection module → GI repository: requires and looks up (evidence: `gi/module.py`)
- Native extension → GI repository: registers types (evidence: `gi/gimodule.c`)
- Native extension → GI metadata wrappers: registers types (evidence: `gi/gimodule.c`)
- GI metadata wrappers → Call marshalling: uses call metadata (evidence: `gi/pygi-info.c`)
- Introspection module → Type wrappers: creates wrappers (evidence: `gi/module.py`)
- Type wrappers → GObject instances: uses object wrappers (evidence: `gi/pygi-type.c`)
- GObject instances → Value conversion: converts properties (evidence: `gi/pygobject-object.c`)
- Call marshalling → Value conversion: marshals values
- Override framework → Dynamic importer: imports registry (evidence: `gi/overrides/__init__.py`)
- GLib overrides → Override framework: registers adaptations (evidence: `gi/overrides/GLib.py`)
- GObject overrides → Override framework: registers adaptations (evidence: `gi/overrides/GObject.py`)
- GTK overrides → Override framework: registers adaptations (evidence: `gi/overrides/Gtk.py`)
- GLib overrides → Event loop helpers: runs event loop (evidence: `gi/overrides/GLib.py`)
- Event loop helpers → GI public API: uses signal helpers (evidence: `gi/_ossighelper.py`)
- GObject overrides → Signal helpers: uses helpers (evidence: `gi/overrides/GObject.py`)
- GObject instances → Signal closures: uses closures (evidence: `gi/pygobject-object.c`)
- Native extension → Async marshalling: registers types (evidence: `gi/gimodule.c`)
