# ctrondlp/pyguitest architecture

> Architecture diagram of the GitHub repository ctrondlp/pyguitest, 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/pyguitest
- Repository: https://github.com/ctrondlp/pyguitest

## Overview

Pyguitest is a cross-platform Python library for automating real desktop applications. A script connects to a detected desktop session, queries available capabilities, then uses one API for accessible-element interaction, input, windows, screenshots, and clipboard operations. The registry selects platform backends, which implement the shared capability contract. The README documents backend coverage; the source index and excerpts establish selected imports and implementation relationships. Some backend wiring is unsampled, so those connections are omitted rather than inferred.

Main entry points: [`src/pyguitest/__init__.py`](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/__init__.py) (GUI Session API), [`src/pyguitest/backends/__init__.py`](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/__init__.py) (Backend Registry), [`src/pyguitest/backends/macos.py`](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/macos.py) (macOS Backend), [`src/pyguitest/backends/capture.py`](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/capture.py) (Screenshots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["GUI Session API<br/>[__init__.py]"]
end

subgraph group_runtime["Runtime Assembly"]
  node_session["Session Detection<br/>[session.py]"]
  node_registry["Backend Registry<br/>[__init__.py]"]
  node_composite["Composite Backend<br/>[composite.py]"]
end

subgraph group_shared["Shared Operations"]
  node_contract["Capability Contract<br/>[base.py]"]
  node_capabilities["Capability Model<br/>[capabilities.py]"]
  node_elements["Accessible Elements<br/>[atspi.py]"]
  node_capture["Screenshots<br/>[capture.py]"]
  node_image["Image Search<br/>[imagesearch.py]"]
  node_input["Input Injection<br/>[input.py]"]
  node_clipboard["Clipboard<br/>[clipboard.py]"]
  node_window["Window Control<br/>[windows.py]"]
end

subgraph group_linux["Linux Backends"]
  node_portal["Remote Desktop Portal<br/>[portal.py]"]
  node_x11["X11 Backend<br/>[x11.py]"]
  node_gnome["GNOME Shell Backend<br/>[gnomeshell.py]"]
end

subgraph group_platforms["Other Platforms"]
  node_windows["Windows Backend<br/>[win32.py]"]
  node_winapi["Windows API Bindings<br/>[_winapi.py]"]
  node_uia["Windows UI Automation<br/>[uia.py]"]
  node_macos["macOS Backend<br/>[macos.py]"]
  node_macapi["macOS API Bindings<br/>[_macapi.py]"]
end

node_user(("Automation Script"))

node_user -->|"uses"| node_api
node_api -->|"detects session"| node_session
node_api -->|"connects through"| node_registry
node_api -->|"queries support"| node_capabilities
node_registry -->|"assembles backends"| node_composite
node_composite -->|"implements"| node_contract
node_contract -->|"declares"| node_capabilities
node_registry -->|"registers"| node_elements
node_registry -->|"registers"| node_portal
node_registry -->|"registers"| node_x11
node_registry -->|"registers"| node_gnome
node_registry -->|"registers"| node_windows
node_registry -->|"registers"| node_uia
node_registry -->|"registers"| node_macos
node_windows -->|"uses"| node_winapi
node_uia -->|"uses"| node_winapi
node_macos -->|"uses"| node_macapi
node_macos -->|"uses"| node_capture
node_image -.->|"searches captured pixels"| node_capture
node_api -->|"sends input"| node_input
node_api -->|"finds and acts"| node_elements
node_api -->|"controls windows"| node_window
node_api -->|"captures screenshots"| node_capture
node_api -->|"reads and writes"| node_clipboard

click node_api "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/__init__.py"
click node_session "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/session.py"
click node_registry "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/__init__.py"
click node_composite "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/composite.py"
click node_contract "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/base.py"
click node_capabilities "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/capabilities.py"
click node_elements "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/atspi.py"
click node_capture "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/capture.py"
click node_image "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/imagesearch.py"
click node_input "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/input.py"
click node_clipboard "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/clipboard.py"
click node_window "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/windows.py"
click node_portal "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/portal.py"
click node_x11 "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/x11.py"
click node_gnome "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/gnomeshell.py"
click node_windows "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/win32.py"
click node_winapi "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/_winapi.py"
click node_uia "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/uia.py"
click node_macos "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/macos.py"
click node_macapi "https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/_macapi.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_api toneBlue
class node_session,node_registry,node_composite toneAmber
class node_contract,node_capabilities,node_elements,node_capture,node_image,node_input,node_clipboard,node_window toneMint
class node_portal,node_x11,node_gnome toneRose
class node_windows,node_winapi,node_uia,node_macos,node_macapi,node_user toneIndigo
```

## Components

### Public API

- [GUI Session API](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/__init__.py): `src/pyguitest/__init__.py`

### Runtime Assembly

- [Session Detection](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/session.py): `src/pyguitest/session.py`
- [Backend Registry](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/__init__.py): `src/pyguitest/backends/__init__.py`
- [Composite Backend](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/composite.py): `src/pyguitest/backends/composite.py`

### Shared Operations

- [Capability Contract](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/base.py): `src/pyguitest/backends/base.py`
- [Capability Model](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/capabilities.py): `src/pyguitest/capabilities.py`
- [Accessible Elements](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/atspi.py): `src/pyguitest/backends/atspi.py`
- [Screenshots](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/capture.py): `src/pyguitest/backends/capture.py`
- [Image Search](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/imagesearch.py): `src/pyguitest/backends/imagesearch.py`
- [Input Injection](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/input.py): `src/pyguitest/backends/input.py`
- [Clipboard](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/clipboard.py): `src/pyguitest/backends/clipboard.py`
- [Window Control](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/windows.py): `src/pyguitest/backends/windows.py`

### Linux Backends

- [Remote Desktop Portal](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/portal.py): `src/pyguitest/backends/portal.py`
- [X11 Backend](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/x11.py): `src/pyguitest/backends/x11.py`
- [GNOME Shell Backend](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/gnomeshell.py): `src/pyguitest/backends/gnomeshell.py`

### Other Platforms

- [Windows Backend](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/win32.py): `src/pyguitest/backends/win32.py`
- [Windows API Bindings](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/_winapi.py): `src/pyguitest/backends/_winapi.py`
- [Windows UI Automation](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/uia.py): `src/pyguitest/backends/uia.py`
- [macOS Backend](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/macos.py): `src/pyguitest/backends/macos.py`
- [macOS API Bindings](https://github.com/ctrondlp/pyguitest/blob/main/src/pyguitest/backends/_macapi.py): `src/pyguitest/backends/_macapi.py`

### Other components

- **Automation Script**

## Connections

- Automation Script → GUI Session API: uses
- GUI Session API → Session Detection: detects session (evidence: `src/pyguitest/__init__.py`)
- GUI Session API → Backend Registry: connects through (evidence: `src/pyguitest/__init__.py`)
- GUI Session API → Capability Model: queries support (evidence: `src/pyguitest/__init__.py`)
- Backend Registry → Composite Backend: assembles backends (evidence: `src/pyguitest/backends/__init__.py`)
- Composite Backend → Capability Contract: implements (evidence: `src/pyguitest/backends/composite.py`)
- Capability Contract → Capability Model: declares (evidence: `src/pyguitest/backends/base.py`)
- Backend Registry → Accessible Elements: registers (evidence: `src/pyguitest/backends/__init__.py`)
- Backend Registry → Remote Desktop Portal: registers (evidence: `src/pyguitest/backends/__init__.py`)
- Backend Registry → X11 Backend: registers (evidence: `src/pyguitest/backends/__init__.py`)
- Backend Registry → GNOME Shell Backend: registers (evidence: `src/pyguitest/backends/__init__.py`)
- Backend Registry → Windows Backend: registers (evidence: `src/pyguitest/backends/__init__.py`)
- Backend Registry → Windows UI Automation: registers (evidence: `src/pyguitest/backends/__init__.py`)
- Backend Registry → macOS Backend: registers (evidence: `src/pyguitest/backends/__init__.py`)
- Windows Backend → Windows API Bindings: uses (evidence: `src/pyguitest/backends/win32.py`)
- Windows UI Automation → Windows API Bindings: uses (evidence: `src/pyguitest/backends/uia.py`)
- macOS Backend → macOS API Bindings: uses (evidence: `src/pyguitest/backends/macos.py`)
- macOS Backend → Screenshots: uses (evidence: `src/pyguitest/backends/macos.py`)
- Image Search → Screenshots: searches captured pixels
- GUI Session API → Input Injection: sends input
- GUI Session API → Accessible Elements: finds and acts
- GUI Session API → Window Control: controls windows (evidence: `src/pyguitest/__init__.py`)
- GUI Session API → Screenshots: captures screenshots
- GUI Session API → Clipboard: reads and writes