# pyapp-kit/superqt architecture

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

- Interactive diagram: https://gitdiagram.com/pyapp-kit/superqt
- Repository: https://github.com/pyapp-kit/superqt

## Overview

##### Project type and purpose
- This is an open-source Python library (“superqt”) that bundles missing QtWidgets components and utilities for PyQt/PySide.

##### File structure
- Top-level:
- src/superqt/… – the library code, organized by feature area.
- docs/        – MkDocs-based documentation source (%mkdocs.yml%).
- examples/    – standalone .py demos that consume the library.
- tests/       – pytest suite validating each module.
- CI config (.github/, codecov.yml, pre-commit etc.).
- src/superqt is subdivided by functionality:
- cmap, collapsible, combobox, elidable, fonticon, iconify, qtcompat, selection, sliders, spinbox, switch, utils.
- Build & publish: pyproject.toml, packaging to PyPI, GitHub Actions workflow.

##### README for additional insights
- Confirms Python ≥3.9, supports PyQt5/6 & PySide2/6.
- Core deliverables: “widgets” and “utilities.”

a. Main components
- Qt Layer (external): PyQt5/PySide2 & PyQt6/PySide6.
- superqt Library:
· Widget Modules (cmap, collapsible, combobox, elidable, sliders, spinbox, switch, selection, iconify, fonticon)
· Utility Modules (utils/_*, qtcompat)
- Consumer Layers:
· Example Applications (examples/*.py)
· End-user Applications (not in repo, but implied)
- Support Infrastructure:
· Documentation (docs/)
· Test Suite (tests/)
· CI/CD (GitHub Actions)
b. Relationships & interactions
- CI/CD → Test Suite → Codecov/Publish (workflow triggers tests, coverage, deploy).
- Documentation → MkDocs → Hosted site (build docs from docs/).
c. Architectural patterns & principles
- Modular packaging: each widget group is its own subpackage.
- Layered dependencies: core utilities (thread, error-handling, flow layouts) underpin all widgets.
- Compatibility adapter (qtcompat) abstracts differences between PyQt/PySide versions.
- Separation of concerns: widgets vs utilities vs docs vs tests.
d. Technologies & frameworks
- Python packaging: pyproject.toml, pytest, codecov, pre-commit.
- Documentation: MkDocs, custom macros (docs/_macros.py).
- CI: GitHub Actions (test_and_deploy.yml).
- GUI: Qt bindings (PyQt5/6, PySide2/6).

##### Elements
- “Qt Bindings” (external)
- “superqt/widgets/*”
- “superqt/utils/*”
- “superqt/qtcompat”
- “Examples”
- “Tests”
- “Docs”
- “CI/CD Pipeline”
- From “Qt Bindings” → library modules.
- From library modules → utilities/qtcompat.
- From Examples/Tests → library modules.
- From CI/CD → Tests → Codecov/PyPI.
- From Docs → MkDocs build → Hosted docs.
- Core modules in another (e.g., green).
- Labels:
- Name each module group and config file (pyproject, mkdocs.yml).
- Language/runtime (Python ≥3.9).
- Version compatibility adapters (qtcompat).

##### Detailed capture of essential elements
- Don’t simply list folders; group them by role (widget vs utility vs support).
- “qtcompat” sitting between Qt Bindings and higher-level modules as an adapter.
- Plugin pattern in fonticon (_plugins entry point discovery).
- Docs macros generating site, showing the feedback loop if docs fail to build.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Qt Layer
    subgraph "Qt Layer"
        QtBindings["Qt Bindings"]:::external
    end

    %% Core Library
    subgraph "superqt Library"
        direction TB
        subgraph "Widgets" 
            direction TB
            Cmap["cmap"]:::core
            Collapsible["collapsible"]:::core
            ComboBox["combobox"]:::core
            Elidable["elidable"]:::core
            Sliders["sliders"]:::core
            SpinBox["spinbox"]:::core
            Switch["switch"]:::core
            Selection["selection"]:::core
            Iconify["iconify"]:::core
            FontIcon["fonticon"]:::core
        end
        subgraph "Utilities"
            direction TB
            Utils["utils"]:::core
            QtCompat["qtcompat"]:::core
        end
    end

    %% Support Infrastructure
    subgraph "Support Assets"
        direction TB
        Examples["Examples"]:::support
        Tests["Test Suite"]:::support
        Docs["Documentation"]:::support
        Packaging["Packaging & Metadata"]:::support
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        direction TB
        CICD["GitHub Actions"]:::pipeline
        Codecov["Codecov"]:::pipeline
        PyPI["PyPI Publish"]:::pipeline
    end

    %% Arrows
    QtBindings -->|imports| QtCompat
    QtCompat -->|adapts| Cmap
    QtCompat -->|adapts| Collapsible
    QtCompat -->|adapts| ComboBox
    QtCompat -->|adapts| Elidable
    QtCompat -->|adapts| Sliders
    QtCompat -->|adapts| SpinBox
    QtCompat -->|adapts| Switch
    QtCompat -->|adapts| Selection
    QtCompat -->|adapts| Iconify
    QtCompat -->|adapts| FontIcon

    Cmap -->|uses| Utils
    Collapsible -->|uses| Utils
    ComboBox -->|uses| Utils
    Elidable -->|uses| Utils
    Sliders -->|uses| Utils
    SpinBox -->|uses| Utils
    Switch -->|uses| Utils
    Selection -->|uses| Utils
    Iconify -->|uses| Utils
    FontIcon -->|uses| Utils

    Examples -->|imports| Cmap
    Examples -->|imports| Utils
    Tests -->|imports| Cmap
    Tests -->|imports| Utils

    CICD -->|runs| Tests
    Tests -->|reports| Codecov
    CICD -->|publishes| PyPI

    Docs -->|builds| DocsSite["MkDocs Build"]:::pipeline
    DocsSite -->|hosts| HostedDocs["Hosted Docs"]:::support

    Packaging -->|defines| PyProj["pyproject.toml"]:::support
    Packaging -->|includes| Readme["README.md"]:::support
    Packaging -->|includes| License["LICENSE"]:::support
    Packaging -->|includes| Changelog["CHANGELOG.md"]:::support

    %% Click Events
    click Cmap "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/cmap/"
    click Collapsible "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/collapsible/"
    click ComboBox "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/combobox/"
    click Elidable "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/elidable/"
    click Sliders "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/sliders/"
    click SpinBox "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/spinbox/"
    click Switch "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/switch/"
    click Selection "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/selection/"
    click Iconify "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/iconify/"
    click FontIcon "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/fonticon/"
    click Utils "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/utils/"
    click QtCompat "https://github.com/pyapp-kit/superqt/tree/main/src/superqt/qtcompat/"
    click Docs "https://github.com/pyapp-kit/superqt/tree/main/docs/"
    click Examples "https://github.com/pyapp-kit/superqt/tree/main/examples/"
    click Tests "https://github.com/pyapp-kit/superqt/tree/main/tests/"
    click CICD "https://github.com/pyapp-kit/superqt/blob/main/ .github/workflows/test_and_deploy.yml"
    click Codecov "https://github.com/pyapp-kit/superqt/blob/main/codecov.yml"
    click Readme "https://github.com/pyapp-kit/superqt/blob/main/README.md"
    click PyProj "https://github.com/pyapp-kit/superqt/blob/main/pyproject.toml"
    click License "https://github.com/pyapp-kit/superqt/tree/main/LICENSE"
    click Changelog "https://github.com/pyapp-kit/superqt/blob/main/CHANGELOG.md"
    click DocsSite "https://github.com/pyapp-kit/superqt/blob/main/mkdocs.yml"

    %% Styles
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef core fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef support fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef pipeline fill:#87CEFA,stroke:#333,stroke-width:1px
```
