# asweigart/pyautogui architecture

> Architecture diagram of the GitHub repository asweigart/pyautogui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asweigart/pyautogui
- Repository: https://github.com/asweigart/pyautogui

## Overview

##### Project Type and Purpose
- Type: A cross-platform Python library/module for GUI automation.

##### File Structure
- Top-level:
– pyautogui/ : core module code
– docs/ : documentation source
– tests/ : automated unit tests
– setup.py, Pipfile, tox.ini : build, packaging, and CI configuration
- In pyautogui/:
– __main__.py : CLI entry point (if run as a script)
– __init__.py : public API definitions
– _pyautogui_win.py, _pyautogui_osx.py, _pyautogui_x11.py, _pyautogui_java.py : OS-specific adapters
- External dependencies referenced in README:
– rubicon-objc (macOS), python-xlib (Linux), ctypes/Win32 (Windows)
– Pillow (screenshots), pyscreeze (image location), pymsgbox (dialogs), pytweening (easing functions)

##### Extract Key Insights from README
- “Hide complexity behind a simple API” – indicates an adapter/abstraction pattern.
- Three major OS‐adapter paths (Windows API via ctypes, Cocoa via rubicon-objc, X11 via python-xlib).
- Additional helper modules for screenshots and dialogs.

##### Main Components & Their Interactions
a. User Script / Client Code
- Imports pyautogui API calls (moveTo, click, write, screenshot, alert, etc.).
b. Core API Layer (pyautogui/__init__.py)
- Exposes unified functions, handles argument normalization.
- Dispatches calls to helper modules (pyscreeze, pymsgbox, pytweening) as needed.
c. OS Adapter Layer
- Reads current platform; routes core requests to one of:
– WindowsAdapter (_pyautogui_win.py) via ctypes → Win32 API
– MacOSAdapter (_pyautogui_osx.py) via rubicon-objc → Cocoa API
– LinuxAdapter (_pyautogui_x11.py) via python-xlib → X11 API
– (Optional) JavaAdapter (_pyautogui_java.py)
d. External Libraries & Services
- Pillow/pyscreeze: image capture & search
- pytweening: motion easing
e. Operating System & Hardware
- OS kernel and windowing system ultimately perform mouse/keyboard events and screen capture.

##### Architectural Patterns
- Adapter pattern for each OS API
- Facade in the core API to unify diverse backends
- Plugin-style extensibility: drop-in modules for new platforms or services

##### Essential Elements
– Core Logic vs. Adapters vs. Third-party Modules vs. Client Code.
- Configuration files (e.g., setup.py) off to the side for build/deployment context.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Code
    subgraph "User Code / Client"
        UserScript["User Script / Client Code"]:::client
    end

    %% Core Library
    subgraph "Core Library"
        CoreAPI["Core API Layer"]:::core
        CLI["CLI Entry Point"]:::core
    end

    %% OS Adapters
    subgraph "Platform-specific Adapters"
        WinAdapter["WindowsAdapter (ctypes → Win32 API)"]:::adapter
        MacAdapter["MacOSAdapter (rubicon-objc → Cocoa API)"]:::adapter
        LinuxAdapter["LinuxAdapter (python-xlib → X11 API)"]:::adapter
        JavaAdapter["JavaAdapter (optional plugin)"]:::adapter
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Pillow["Pillow / pyscreeze"]:::external
        PyMsgBox["pymsgbox"]:::external
        Tweening["pytweening"]:::external
    end

    %% OS Kernel & Hardware
    subgraph "OS Kernel & Hardware"
        OSKernel["OS Kernel & Windowing System"]:::infra
    end

    %% Side Modules
    Docs["Documentation (docs/)"]:::infra
    ModuleRef["Module Reference (docs/source/pyautogui.rst)"]:::infra
    Tests["Automated Tests (tests/)"]:::infra
    Build["Build & Packaging Config\n(setup.py, Pipfile, tox.ini)"]:::infra

    %% Connections
    UserScript -->|"function call"| CoreAPI
    CLI -->|"invokes CLI commands"| CoreAPI
    CoreAPI -->|"dispatch to adapter"| WinAdapter
    CoreAPI -->|"dispatch to adapter"| MacAdapter
    CoreAPI -->|"dispatch to adapter"| LinuxAdapter
    CoreAPI -->|"dispatch to adapter"| JavaAdapter
    WinAdapter -->|"calls Win32 API"| OSKernel
    MacAdapter -->|"calls Cocoa API"| OSKernel
    LinuxAdapter -->|"calls X11 API"| OSKernel
    JavaAdapter -->|"calls Java Robot API"| OSKernel
    CoreAPI -->|"uses image capture"| Pillow
    CoreAPI -->|"uses dialogs"| PyMsgBox
    CoreAPI -->|"uses easing"| Tweening

    Tests -->|"mocks/verifies"| CoreAPI
    Tests -->|"mocks/verifies"| WinAdapter
    Tests -->|"mocks/verifies"| MacAdapter
    Tests -->|"mocks/verifies"| LinuxAdapter
    Docs -->|"documents API"| CoreAPI
    Docs -->|"provides examples"| WinAdapter
    ModuleRef -->|"auto-generated docs"| CoreAPI
    Build -->|"build config for"| CoreAPI
    Build -->|"CI config for"| Tests

    %% Click Events
    click CoreAPI "https://github.com/asweigart/pyautogui/blob/master/pyautogui/__init__.py"
    click CLI "https://github.com/asweigart/pyautogui/blob/master/pyautogui/__main__.py"
    click WinAdapter "https://github.com/asweigart/pyautogui/blob/master/pyautogui/_pyautogui_win.py"
    click MacAdapter "https://github.com/asweigart/pyautogui/blob/master/pyautogui/_pyautogui_osx.py"
    click LinuxAdapter "https://github.com/asweigart/pyautogui/blob/master/pyautogui/_pyautogui_x11.py"
    click JavaAdapter "https://github.com/asweigart/pyautogui/blob/master/pyautogui/_pyautogui_java.py"
    click Docs "https://github.com/asweigart/pyautogui/tree/master/docs/"
    click ModuleRef "https://github.com/asweigart/pyautogui/blob/master/docs/source/pyautogui.rst"
    click Tests "https://github.com/asweigart/pyautogui/tree/master/tests/"
    click Build "https://github.com/asweigart/pyautogui/blob/master/setup.py"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef core fill:#FCE4EC,stroke:#880E4F,stroke-width:1px
    classDef adapter fill:#E8F5E9,stroke:#1B5E20,stroke-width:1px
    classDef external fill:#E3F2FD,stroke:#0D47A1,stroke-width:1px
    classDef infra fill:#FFF3E0,stroke:#E65100,stroke-width:1px
```
