How pyapp-kit/superqt works
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.