English | 한국어

Why

Jetpack Compose and Compose Multiplatform are a superb way to build UI, if you write Kotlin. pythonx-compose is for people who write Python. It does not reimplement Compose and it does not invent a new widget set: it takes the real androidx.compose.* API, which python-multiplatform exposes to Python under its Kotlin names, and restructures it into a Pythonic package, pythonx.compose.

from pythonx.compose.runtime import Composable
from pythonx.compose.material3 import Text, Button

@Composable
def Greeting():
    Button(on_click=lambda: print("hi"), content=lambda: Text("Hello from Python"))

_{These names resolve today, by one rule, inside an app that embeds the binder; per-widget render proofs are still pending. See Status.}

✨ Principles

• The original API, Pythonic names. Every parameter is Compose's own parameter, in snake_case: onClick → on_click, horizontalAlignment → horizontal_alignment. Upper-case names (types, objects, composables) keep their Kotlin spelling; every other name is snake_case only (fillMaxWidth → fill_max_width, toURLString → to_url_string), and an explicit overload keeps its suffix (padding__Dp).
• Extension functions are methods. Modifier.padding(16).size(24).fill_max_width() chains exactly as it does in Kotlin. Keyword arguments to such a method are snake_case too (m.padding(padding_values=...)), as they are on the module function padding(m, padding_values=...); Kotlin's own spelling still works at run time, and the type stubs offer only the Pythonic one.
• Kotlin objects are namespaces. Alignment.Center and Arrangement.End are read without parentheses; functions inside them are snake_case: Arrangement.spaced_by(8). Constants can also be reached grouped by their declared type, as the notebook writes them: Alignment.Horizontal.End is Alignment.End.
• @Composable stays. Screens are decorated Python functions.
• A real package. pythonx/ is ordinary Python source that imports androidx.compose.* and reshapes it. The binder never renames a namespace. Since python-multiplatform #131 it serves snake_case names and keywords itself, by this package's rule; this package keeps the module grouping and the snake_case-only surface.
• One manifest. pythonx-map.toml says which pythonx.compose.* module stands for which Kotlin package. It lives inside the package and ships in the wheel. The runtime and the .pyi generator read the same file, so what your editor completes is what the interpreter resolves.

🧩 Architecture at a glance

flowchart LR
    app["Your Python UI<br/>@Composable def Screen()"] --> px["pythonx.compose<br/>(this package, real Python)"]
    px --> ax["androidx.compose.*<br/>Kotlin names, exposed by python-multiplatform"]
    ax --> compose["Jetpack / Compose Multiplatform"]
    map["pythonx-map.toml"] -.-> px
    map -.-> pyi[".pyi stubs<br/>(in the wheel)"]

Each module is a real file whose __init__.py calls one re-export rule; names resolve on first use. Column, Row and Spacer are importable from pythonx.compose.material3 as well as pythonx.compose.layout, as the notebook writes them (the manifest's [aliases]).

🚀 Quick start

uv add --prerelease allow pythonx-compose
# or, with pypackpack, into a package of a ppp workspace:
ppp core add "pythonx-compose==0.1.0a2"
# or, with toolchain-lite:
tcl install pythonx-compose

From a clone, to run the tests:

git clone https://github.com/thisisthepy/pythonx-compose
cd pythonx-compose
uv run --with pytest --with mypy pytest tests -q

What runs today, from the repository root:

from pythonx.compose.runtime import Composable

@Composable                      # an identity decorator: the function stays a plain function
def Screen():
    """A screen."""
    return "drawn"

assert Screen() == "drawn" and Screen.__name__ == "Screen"

import tomllib                   # the manifest: the one place the mapping is written down

with open("pythonx/compose/pythonx-map.toml", "rb") as f:
    manifest = tomllib.load(f)

manifest["modules"]["pythonx.compose.layout"]
# 'androidx.compose.foundation.layout'
manifest["value-classes"]["raw-primitive-allowed"]
# ['androidx.compose.ui.unit.Dp']   ->  padding(16) means padding(16.dp)

from pythonx.compose._reexport import python_name   # the naming rule, no binder needed

python_name("fillMaxWidth")   # 'fill_max_width'
python_name("toURLString")    # 'to_url_string'
python_name("Modifier")       # 'Modifier'

Reading a Compose name such as pythonx.compose.material3.Text needs the binder, which the Kotlin host installs; outside an app it raises a RuntimeError saying so.

The tests that drive a Modifier chain and overload dispatch read the binder's adaptation layer from a sibling python-multiplatform checkout (or PYTHONMULTIPLATFORM_HOME); without one they are skipped.

📦 Installation

Distributed as the pip package pythonx-compose (Python 3.11 or later), providing the import package pythonx.compose, with the manifest inside the wheel, and typed: .pyi stubs generated from real Compose 1.11.1 and py.typed ship with it. It runs inside an app that embeds CPython through python-multiplatform; it is not a standalone desktop toolkit.

🧪 Status

The full list is on the guide's Status page.

📖 Documentation

• Guide: docs/guide/, bilingual (English / 한국어)
• Korean README: docs/locale/README_ko.md

🔌 Ecosystem

🤝 Contributing

Development is intent-first and test-first: a change starts as a specification change, then a failing test, then code. The guide lists what is open and where help is useful. Please open an issue before large changes.

Maintainers

License

Apache License 2.0 © 2023–2024 BREW (b-re-w), Jong-uk Lee (rnoro5122)