# ctrondlp/python-libei architecture

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

- Interactive diagram: https://gitdiagram.com/ctrondlp/python-libei
- Repository: https://github.com/ctrondlp/python-libei

## Overview

python-libei provides Python ctypes bindings for Wayland EI/EIS input, plus two portal-based ways to obtain an EIS connection. The main injection flow is caller → permission/session negotiation → EI Sender → compositor EIS server, where queued input is sent by frame(). The package also supports receiving input and direct D-Bus InputCapture sessions. Low-level bindings, lazy native-library loading, and C-pointer lifetime management underpin the public APIs. Relationships involving unsampled implementation details are omitted unless documented in the README or shown by an excerpt.

Main entry points: [`src/libei/ei.py`](https://github.com/ctrondlp/python-libei/blob/main/src/libei/ei.py) (EI client), [`src/libei/eis.py`](https://github.com/ctrondlp/python-libei/blob/main/src/libei/eis.py) (EIS server), [`src/libei/oeffis.py`](https://github.com/ctrondlp/python-libei/blob/main/src/libei/oeffis.py) (Oeffis session), [`src/libei/_capi/loader.py`](https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/loader.py) (Lazy library loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Permission and access"]
  node_oeffis["Oeffis session<br/>[oeffis.py]"]
  node_portal_rd["RemoteDesktop session<br/>[portal.py]"]
  node_input_capture["InputCapture session<br/>[portal.py]"]
end

subgraph group_protocol["EI/EIS protocol"]
  node_sender["EI client<br/>[ei.py]"]
  node_eis_server["EIS server<br/>[eis.py]"]
end

subgraph group_native["Native bindings"]
  node_capi_ei["libei bindings<br/>[libei.py]"]
  node_capi_eis["libeis bindings<br/>[libeis.py]"]
  node_capi_oeffis["liboeffis bindings<br/>[liboeffis.py]"]
end

subgraph group_runtime["Runtime support"]
  node_loader["Lazy library loader<br/>[loader.py]"]
  node_cobject["C object wrappers<br/>[_cobject.py]"]
end

node_automation(("Automation caller"))
node_consent(("User consent"))
node_portal_service["Desktop portal"]
node_compositor["Wayland compositor"]

node_automation -->|"requests access"| node_oeffis
node_automation -->|"requests access"| node_portal_rd
node_consent -->|"approves session"| node_portal_service
node_oeffis -->|"negotiates session"| node_portal_service
node_portal_rd -->|"negotiates over D-Bus"| node_portal_service
node_input_capture -->|"negotiates capture"| node_portal_service
node_portal_service -->|"provides EIS fd"| node_sender
node_portal_service -->|"provides EIS fd"| node_eis_server
node_automation -->|"sends input"| node_sender
node_sender -->|"sends framed events"| node_eis_server
node_eis_server -->|"implements server side"| node_compositor
node_sender -->|"calls bindings"| node_capi_ei
node_eis_server -->|"calls bindings"| node_capi_eis
node_oeffis -->|"calls bindings"| node_capi_oeffis
node_capi_ei -->|"resolves functions"| node_loader
node_capi_eis -->|"resolves functions"| node_loader
node_capi_oeffis -->|"resolves functions"| node_loader
node_sender -->|"wraps C pointers"| node_cobject
node_eis_server -->|"wraps C pointers"| node_cobject

click node_oeffis "https://github.com/ctrondlp/python-libei/blob/main/src/libei/oeffis.py"
click node_portal_rd "https://github.com/ctrondlp/python-libei/blob/main/src/libei/portal.py"
click node_input_capture "https://github.com/ctrondlp/python-libei/blob/main/src/libei/portal.py"
click node_sender "https://github.com/ctrondlp/python-libei/blob/main/src/libei/ei.py"
click node_eis_server "https://github.com/ctrondlp/python-libei/blob/main/src/libei/eis.py"
click node_capi_ei "https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/libei.py"
click node_capi_eis "https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/libeis.py"
click node_capi_oeffis "https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/liboeffis.py"
click node_loader "https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/loader.py"
click node_cobject "https://github.com/ctrondlp/python-libei/blob/main/src/libei/_cobject.py"

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_oeffis,node_portal_rd,node_input_capture,node_consent toneBlue
class node_sender,node_eis_server toneAmber
class node_capi_ei,node_capi_eis,node_capi_oeffis toneMint
class node_loader,node_cobject toneRose
class node_automation,node_portal_service,node_compositor toneIndigo
```

## Components

### Permission and access

- [Oeffis session](https://github.com/ctrondlp/python-libei/blob/main/src/libei/oeffis.py): `src/libei/oeffis.py`
- [RemoteDesktop session](https://github.com/ctrondlp/python-libei/blob/main/src/libei/portal.py): `src/libei/portal.py`
- [InputCapture session](https://github.com/ctrondlp/python-libei/blob/main/src/libei/portal.py): `src/libei/portal.py`

### EI/EIS protocol

- [EI client](https://github.com/ctrondlp/python-libei/blob/main/src/libei/ei.py): `src/libei/ei.py`
- [EIS server](https://github.com/ctrondlp/python-libei/blob/main/src/libei/eis.py): `src/libei/eis.py`

### Native bindings

- [libei bindings](https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/libei.py): `src/libei/_capi/libei.py`
- [libeis bindings](https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/libeis.py): `src/libei/_capi/libeis.py`
- [liboeffis bindings](https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/liboeffis.py): `src/libei/_capi/liboeffis.py`

### Runtime support

- [Lazy library loader](https://github.com/ctrondlp/python-libei/blob/main/src/libei/_capi/loader.py): `src/libei/_capi/loader.py`
- [C object wrappers](https://github.com/ctrondlp/python-libei/blob/main/src/libei/_cobject.py): `src/libei/_cobject.py`

### Other components

- **Automation caller**
- **User consent**
- **Desktop portal**
- **Wayland compositor**

## Connections

- Automation caller → Oeffis session: requests access (evidence: `README.md`)
- Automation caller → RemoteDesktop session: requests access (evidence: `README.md`)
- User consent → Desktop portal: approves session (evidence: `README.md`)
- Oeffis session → Desktop portal: negotiates session (evidence: `src/libei/oeffis.py`)
- RemoteDesktop session → Desktop portal: negotiates over D-Bus (evidence: `src/libei/portal.py`)
- InputCapture session → Desktop portal: negotiates capture (evidence: `src/libei/portal.py`)
- Desktop portal → EI client: provides EIS fd
- Desktop portal → EIS server: provides EIS fd
- Automation caller → EI client: sends input (evidence: `README.md`)
- EI client → EIS server: sends framed events (evidence: `README.md`)
- EIS server → Wayland compositor: implements server side (evidence: `src/libei/eis.py`)
- EI client → libei bindings: calls bindings (evidence: `src/libei/ei.py`)
- EIS server → libeis bindings: calls bindings (evidence: `src/libei/eis.py`)
- Oeffis session → liboeffis bindings: calls bindings (evidence: `src/libei/oeffis.py`)
- libei bindings → Lazy library loader: resolves functions (evidence: `src/libei/_capi/libei.py`)
- libeis bindings → Lazy library loader: resolves functions (evidence: `src/libei/_capi/libeis.py`)
- liboeffis bindings → Lazy library loader: resolves functions (evidence: `src/libei/_capi/liboeffis.py`)
- EI client → C object wrappers: wraps C pointers (evidence: `src/libei/ei.py`)
- EIS server → C object wrappers: wraps C pointers (evidence: `src/libei/eis.py`)
