# ComposeUI

> ComposeUI is a small MVVM layer for building UIs in Python. You write the views once, as typed `attrs` classes, and a renderer binds each view to a widget of a backend: Qt (desktop, through `qtpy`), Textual (terminal), or the web (Starlette and htmx). Signals carry the events between the views, the model, and the app. Early-stage (pre-alpha): the API is small and still moving.

`composeui.core` holds the views, signals, and application, and imports no backend. A study file saves the views' state as JSON (`cattrs`). Python 3.9 and later; install from PyPI with `pip install "composeui[web,pyside6]"`.

## Start here

- [Overview](https://ehmoussi.github.io/composeui/index.html): how the views, the optional model, signals, and renderers fit together
- [README](https://github.com/ehmoussi/composeui/blob/main/README.md): installation and a quickstart window

## User guide

- [User guide](https://ehmoussi.github.io/composeui/user-guide.html): index of the pages below
- [Core concepts](https://ehmoussi.github.io/composeui/user-guide/core-concepts.html): views, signals, the model, studies, and the backends, and how ComposeUI maps to MVVM
- [Building views](https://ehmoussi.github.io/composeui/user-guide/building-views.html): define views, lay them out, forms and validation, the main view, saving and loading state
- [Widgets](https://ehmoussi.github.io/composeui/user-guide/widgets.html): labels, buttons, inputs, sliders, progress bars, metrics, expanders, trees, Markdown, and the File menu
- [Organizing the window](https://ehmoussi.github.io/composeui/user-guide/organizing-the-window.html): pages, tabs, resizable panes, a list of views, menus, toolbars, a sidebar, and dialogs
- [Tables](https://ehmoussi.github.io/composeui/user-guide/tables.html): a table of records with sorting, filtering, and widgets in cells; a large table read from a list, SQLite, or a dataframe
- [Charts](https://ehmoussi.github.io/composeui/user-guide/charts.html): line, scatter, step, and bar charts, log axes, reference lines, clicks, and report images
- [Maps](https://ehmoussi.github.io/composeui/user-guide/maps.html): geographic points on Qt Location and deck.gl maps, tile usage, viewport signals, and saved state
- [Running work in threads](https://ehmoussi.github.io/composeui/user-guide/threads.html): jobs, their progress and failures, and reusable loading tasks
- [A SQLite model](https://ehmoussi.github.io/composeui/user-guide/sqlite-model.html): keep the app's data in SQLite with `SqliteModel`
- [Importing CSV data](https://ehmoussi.github.io/composeui/user-guide/csv-import.html): a SQLite table of an `attrs` row class, filled from a CSV file or URL
- [Translating the app](https://ehmoussi.github.io/composeui/user-guide/translation.html): translation catalogs, and checking them
- [Running the app](https://ehmoussi.github.io/composeui/user-guide/running-the-app.html): start an app on a backend, reload it on a change, and serve it on the web
- [Testing your app](https://ehmoussi.github.io/composeui/user-guide/testing.html): test the views, forms, jobs, and a model with pytest, without a backend
- [Using a coding agent](https://ehmoussi.github.io/composeui/user-guide/coding-agents.html): install the ComposeUI skill for coding agents

## Examples

- [Examples guide](https://ehmoussi.github.io/composeui/examples-guide.html): the example apps (pipe form, catalogue, chart, sweep, task view, large table, Uber pickups, Uber pickups on a dataframe, Batman, Markdown viewer, web hello, Textual demo) and how to run them

## Reference

- [Widget catalog](https://ehmoussi.github.io/composeui/widgets.html): every view that a backend renders
- [API reference](https://ehmoussi.github.io/composeui/api/index.html): built from the docstrings of `composeui.core` (view, signal, application, model, sqlitemodel, dataframesource, dashboard, study, translation, translationcheck, jobs, renderer, registry, reload, chartimage) and the backends

## Contributing

- [Technical guide](https://ehmoussi.github.io/composeui/technical-guide.html): architecture, adding a widget or a backend, development commands, and checks

## Optional

- [ComposeUI skill](https://ehmoussi.github.io/composeui/skills/composeui/SKILL.md): rules for a coding agent that writes a ComposeUI app (a `SKILL.md` file)
- [Source repository](https://github.com/ehmoussi/composeui): code, issues, and the roadmap (`ROADMAP.md`)