pythonx-compose 0.1.0a1__py3-none-any.whl

pythonx/compose/pythonx-map.toml

@@ -0,0 +1,73 @@
+# Which Kotlin package each `pythonx.compose.*` module wraps, and which value classes may be
+# written as their raw primitive.
+#
+# **This file is the reason the binder does not have to know Compose exists.**
+# `python-multiplatform` used to carry `register_package('pythonx.compose', 'androidx.compose')` in
+# its own `commonMain`, which made the language boundary know a UI library by name and put every
+# other library one core edit away. It carries nothing now: an embedder installs this map, and the
+# `.pyi` generator reads the same file, so the name an IDE completes and the name the interpreter
+# resolves cannot drift apart.
+#
+# The mapping is not inferable from any artefact, which is why it is written down rather than
+# derived: `pythonx.compose.layout` wraps `androidx.compose.foundation.layout` and drops
+# `foundation.`, and nothing in the jar says so. `UI.ipynb` -- this project's user-facing
+# specification -- is what settles the spelling; every module below is one it imports, or a package
+# those imports resolve through.
+
+[modules]
+# The four `UI.ipynb` imports by name.
+"pythonx.compose.layout"    = "androidx.compose.foundation.layout"
+"pythonx.compose.material3" = "androidx.compose.material3"
+"pythonx.compose.runtime"   = "androidx.compose.runtime"
+"pythonx.compose.ui"        = "androidx.compose.ui"
+
+# `DefaultIcons` (INTENT section 5.7) is `Icons.Default`, which lives here: `Icons` is an object of
+# `material-icons-core`, and `Icons.Default.Add` is an extension property read on `Icons.Filled`.
+"pythonx.compose.material"       = "androidx.compose.material"
+"pythonx.compose.material.icons" = "androidx.compose.material.icons"
+
+# Reached through the four above rather than imported directly: a `Modifier` chain returns into
+# `ui.unit` and `ui.graphics`, and `ui.text` is where `TextStyle` lives.
+"pythonx.compose.ui.unit"     = "androidx.compose.ui.unit"
+"pythonx.compose.ui.text"     = "androidx.compose.ui.text"
+"pythonx.compose.ui.graphics" = "androidx.compose.ui.graphics"
+# `ImageVector`, what an icon is (`Icons.Default.Add`): without this row its stub types it `Any`.
+"pythonx.compose.ui.graphics.vector" = "androidx.compose.ui.graphics.vector"
+
+# `TextFieldState` and `rememberTextFieldState`, what `TextField(state=...)` takes (INTENT section
+# 5.8). The state-based overload keeps the buffer and the IME composing region inside Compose, so
+# nothing crosses into Python per keystroke; Python makes the state and reads or writes it on demand.
+"pythonx.compose.foundation.text.input" = "androidx.compose.foundation.text.input"
+
+# The long spelling, kept beside the short one because both are real: the generated stubs use
+# `pythonx.compose.layout`, and the render fixtures in `python-multiplatform` were written against
+# the fully-qualified form. Mapping both means neither is wrong while the spelling settles.
+"pythonx.compose.foundation.layout" = "androidx.compose.foundation.layout"
+"pythonx.compose.foundation"        = "androidx.compose.foundation"
+"pythonx.compose"                   = "androidx.compose"
+
+[value-classes]
+# A value class here may be written as the primitive it wraps: `padding(16)` for `padding(Dp(16f))`.
+#
+# `Dp`'s public constructor is the identity on its float, so the two spellings mean the same thing.
+# `Color` and `TextUnit` are deliberately absent even though they look like numbers: both pack
+# several fields into one `packedValue`, so a raw number decodes as something else entirely rather
+# than as the value the caller meant. Adding one here is this package's decision to make, which is
+# the point of the section being in this file rather than in the binder.
+raw-primitive-allowed = [
+    "androidx.compose.ui.unit.Dp",
+]
+
+[aliases."pythonx.compose.material3"]
+# Names a module also answers for, because the notebook imports them from there (INTENT section 5.2):
+# `from pythonx.compose.material3 import Column, Row, Spacer`, while Kotlin declares them in
+# `androidx.compose.foundation.layout`. Each is the same object as in its home module; this is data,
+# not a wrapper, and the rule that serves it is the one in `_reexport.py`.
+"pythonx.compose.layout" = ["Column", "Row", "Spacer"]
+#
+# An entry is a list of names lent under the SAME name, or a table `{ lent name = "Path.To.Attr" }`
+# that lends an attribute path of the source under a DIFFERENT name: the notebook's `DefaultIcons`
+# is Kotlin's `Icons.Default` (INTENT section 5.7). The first segment is a name of the source module,
+# each further one an attribute read. A path with a dot is read afresh on every access and never kept,
+# the way the binder serves `Icons.Default` (a live property); a plain name is resolved once.
+"pythonx.compose.material.icons" = { DefaultIcons = "Icons.Default" }

pythonx/compose/runtime/__init__.py

@@ -0,0 +1,128 @@
+"""`pythonx/compose/runtime/__init__.py` -- the 2024 `Composable` class, gone, and what is left.
+
+## What used to be here, and why it never ran
+
+A decorator class (`Composable`) holding one `__composer`, plus `ComposeApp`, `KotlinComposable`,
+`KotlinWidget` and a `CoroutineScope` family, all built on `jclass` --
+`_runtime = jclass("io.github.thisisthepy.pycomposeui.RuntimeKt")` -- chaquopy's name-based
+Java/Kotlin class lookup. `jclass` was never imported in this module, in any commit where the module
+had content (`git log -p` on this file shows no `import jclass` anywhere), so every one of those five
+module-level statements raised `NameError` before a single class body executed:
+
+    >>> from pythonx.compose.runtime import Composable
+    NameError: name 'jclass' is not defined
+
+That is not incidental breakage, it is a different technology than this repository now targets.
+`jclass` is chaquopy's global; `PythonMultiplatform`'s binder is a different bridge
+(`docs/pythonx-adapter-design.md` §5.1, in `PythonMultiplatform`, reads the same class as "the 2024
+`Composable` class", and `agent-rules.md` §12 retires name-based JVM lookup by name). The other half
+of what `Composable.__call__` did -- inspecting `self.compose.__code__.co_varnames` to find where
+`content` sat, so it could be popped out and wrapped specially -- is retired for the same reason
+`modifier.py`'s mangled-suffix search was: `docs/pythonx-adapter-design.md` §5.6/§7 record that
+composer threading, `$changed` and `$default` are now arithmetic the binder's `_bind_composable` (`python_multiplatform.binding`) does from
+a slot's *declared type*, uniformly, for a `content` lambda exactly as for any other parameter. There
+is nothing left for a Python-side base class to detect or thread by hand.
+
+## What is left
+
+One identity decorator, `Composable`, kept because `UI.ipynb` writes `@Composable` on every
+screen-defining function and that surface is one an application author should keep being able to
+write. Nothing needs to happen to the decorated function for it to work: the composer any nested
+`pythonx.compose.*` call needs comes from the one hand-written Kotlin `@Composable`
+(`PythonComposition`, in `PythonMultiplatform`) pushing it once per composition pass, and from the
+*callee's* slot type deciding whether and how to thread it -- never from anything the caller does.
+A plain `def Screen(): Button(...)` already works with no wrapper, no base class and no `content=`
+slot detection; `@Composable` changes nothing about that and exists only so the notebook's own
+spelling keeps working.
+
+## The app root and `state`
+
+`@app` declares the screen the host draws; `state(initial)` makes a value Compose observes. The host
+is configured once with `PythonContent("pythonx.compose.runtime", "app_root")`: it reads the module
+attribute `app_root`, a Compose `MutableState` whose `.value` is a zero-argument callable or `None`
+(nothing is drawn). `app(fn)` writes `app_root.value = fn` and returns `fn` unchanged, so declaring
+the root again -- in a notebook cell, say -- replaces the screen. There is deliberately no update or
+refresh function (`docs/INTENT.md` section 5.1).
+
+Both states come from `_new_state`, the one place that asks the binder for
+`androidx.compose.runtime.mutableStateOf`. `app_root` is created on first read, because the binder may
+be installed after `pythonx` is imported. A Python object with a `.value` would not make Compose
+recompose, so when the binder cannot supply `mutableStateOf` (python-multiplatform #38) `_new_state`
+raises instead of falling back to one.
+
+## How it is reached
+
+By its own dotted name: `import pythonx.compose.runtime` loads this file. The binder used to put a
+synthetic `pythonx` with `__path__ = []` into `sys.modules`, which made every file under
+`pythonx/compose/` unreachable; PythonMultiplatform `d00f413f` moved its layer to
+`python_multiplatform.binding` and leaves `pythonx` to this package (AGENTS.md section 12).
+`tests/test_runtime_module.py::TheModuleIsTheFileOnDisk` checks that against the binder's real source.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def Composable(target):
+    """Identity. `UI.ipynb` writes `@Composable def Screen(): ...`; nothing needs to happen to
+    `Screen` for that to work, because the composer every nested `pythonx.compose.*` call needs is
+    threaded by `PythonComposition`/`python_multiplatform.binding._bind_composable` from the *callee's* declared slot
+    type, not from anything the caller -- decorated or not -- does. See the module docstring for
+    what used to be here and why it is gone.
+    """
+    return target
+
+
+
+app_root: State
+"""The state the host reads (`PythonContent("pythonx.compose.runtime", "app_root")`); annotated
+only, created on first read by `__getattr__` below."""
+
+
+def _new_state(initial):
+    """A Compose `MutableState` holding `initial`, from the binder's `mutableStateOf`.
+
+    Never a Python stand-in: only a state Compose created is observed by composition.
+    """
+    try:
+        import androidx.compose.runtime as kotlin_runtime
+
+        make = kotlin_runtime.mutableStateOf
+    except (ImportError, AttributeError) as missing:
+        raise RuntimeError(
+            "androidx.compose.runtime.mutableStateOf is not available from the binder: "
+            "calling it from Python needs python-multiplatform #38"
+        ) from missing
+    return make(initial)
+
+
+def state(initial):
+    """A Compose state holding `initial`; read and write it through `.value`."""
+    return _new_state(initial)
+
+
+def app(root):
+    """Declare `root`, a zero-argument function, as the screen the host draws; returns it unchanged.
+
+    Declaring again replaces the screen; there is no update call.
+    """
+    sys.modules[__name__].app_root.value = root
+    return root
+
+
+from pythonx.compose._reexport import reexport
+
+_reexported_getattr, _reexported_dir = reexport(__name__)
+
+
+def __getattr__(name):
+    if name == "app_root":
+        created = _new_state(None)
+        globals()["app_root"] = created
+        return created
+    return _reexported_getattr(name)
+
+
+def __dir__():
+    return sorted(set(_reexported_dir()) | {"app_root"})

pythonx/compose/runtime/__init__.pyi

@@ -0,0 +1,180 @@
+# GENERATED by scripts/gen_stubs.py from python-multiplatform's Kotlin-named stubs (artifact kotlin-stubs, workflow run 37103737430, commit a5028618, Compose 1.11.1). Do not edit.
+import typing as _t
+import pythonx.compose.ui
+
+class _Composer_materialize(_t.Protocol):
+    def __call__(self, modifier: pythonx.compose.ui.Modifier) -> pythonx.compose.ui.Modifier: ...
+
+class _CompositionLocalAccessorScope_mediaQuery(_t.Protocol):
+    def __call__(self, query: _t.Callable[[pythonx.compose.ui.UiMediaScope], bool]) -> bool: ...
+
+class _CompositionLocalAccessorScope_mediaQuery__CompositionLocalAccessorScope_Boolean(_t.Protocol):
+    def __call__(self, query: _t.Callable[[pythonx.compose.ui.UiMediaScope], bool]) -> bool: ...
+
+class _MutableState_setValue(_t.Protocol):
+    def __call__(self, this_obj: _t.Any | None, property: _t.Any, value: _t.Any | None) -> None: ...
+
+class _State_getValue(_t.Protocol):
+    def __call__(self, this_obj: _t.Any | None, property: _t.Any) -> _t.Any | None: ...
+
+class AbstractApplier:
+    """Kotlin: androidx.compose.runtime.AbstractApplier"""
+
+class Applier:
+    """Kotlin: androidx.compose.runtime.Applier"""
+
+class Composer:
+    """Kotlin: androidx.compose.runtime.Composer"""
+    materialize: _t.ClassVar[_Composer_materialize]
+
+class CompositionLocal:
+    """Kotlin: androidx.compose.runtime.CompositionLocal"""
+
+class CompositionLocalAccessorScope:
+    """Kotlin: androidx.compose.runtime.CompositionLocalAccessorScope"""
+    media_query: _t.ClassVar[_CompositionLocalAccessorScope_mediaQuery]
+    media_query__CompositionLocalAccessorScope_Boolean: _t.ClassVar[_CompositionLocalAccessorScope_mediaQuery__CompositionLocalAccessorScope_Boolean]
+
+class CompositionLocalContext:
+    """Kotlin: androidx.compose.runtime.CompositionLocalContext"""
+
+class MutableState(State):
+    """Kotlin: androidx.compose.runtime.MutableState"""
+    set_value: _t.ClassVar[_MutableState_setValue]
+    @property
+    def value(self) -> _t.Any | None:
+        """Kotlin property: androidx.compose.runtime.MutableState.value (androidx.compose.runtime.MutableState.value: kotlin.Any?)"""
+        ...
+    @value.setter
+    def value(self, value: _t.Any | None) -> None:
+        """Kotlin property: androidx.compose.runtime.MutableState.value="""
+        ...
+
+class ProduceStateScope:
+    """Kotlin: androidx.compose.runtime.ProduceStateScope"""
+
+class SnapshotFlowManager:
+    """Kotlin: androidx.compose.runtime.SnapshotFlowManager"""
+
+class SnapshotMutationPolicy:
+    """Kotlin: androidx.compose.runtime.SnapshotMutationPolicy"""
+
+class State:
+    """Kotlin: androidx.compose.runtime.State"""
+    get_value: _t.ClassVar[_State_getValue]
+    @property
+    def value(self) -> _t.Any | None:
+        """Kotlin property: androidx.compose.runtime.State.value (androidx.compose.runtime.State.value: kotlin.Any?)"""
+        ...
+
+def collect_as_state(receiver: _t.Any, /, context: _t.Any = ...) -> State:
+    """Kotlin: kotlinx.coroutines.flow.StateFlow.collectAsState(context: kotlin.coroutines.CoroutineContext): androidx.compose.runtime.State"""
+    ...
+
+def derived_state_of__Any(calculation: _t.Callable[[], _t.Any | None]) -> State:
+    """Kotlin: androidx.compose.runtime.derivedStateOf(calculation: kotlin.Function0): androidx.compose.runtime.State"""
+    ...
+
+def derived_state_of__SnapshotMutationPolicy_Any(policy: SnapshotMutationPolicy, calculation: _t.Callable[[], _t.Any | None]) -> State:
+    """Kotlin: androidx.compose.runtime.derivedStateOf(policy: androidx.compose.runtime.SnapshotMutationPolicy, calculation: kotlin.Function0): androidx.compose.runtime.State"""
+    ...
+
+def get_value(receiver: State, /, this_obj: _t.Any | None, property: _t.Any) -> _t.Any | None:
+    """Kotlin: androidx.compose.runtime.State.getValue(thisObj: kotlin.Any?, property: kotlin.reflect.KProperty): kotlin.Any"""
+    ...
+
+def mutable_state_list_of() -> _t.Any:
+    """Kotlin: androidx.compose.runtime.mutableStateListOf(): androidx.compose.runtime.snapshots.SnapshotStateList"""
+    ...
+
+def mutable_state_map_of() -> _t.Any:
+    """Kotlin: androidx.compose.runtime.mutableStateMapOf(): androidx.compose.runtime.snapshots.SnapshotStateMap"""
+    ...
+
+def mutable_state_of(value: _t.Any | None, policy: SnapshotMutationPolicy = ...) -> MutableState:
+    """Kotlin: androidx.compose.runtime.mutableStateOf(value: kotlin.Any?, policy: androidx.compose.runtime.SnapshotMutationPolicy): androidx.compose.runtime.MutableState"""
+    ...
+
+def mutable_state_set_of() -> _t.Any:
+    """Kotlin: androidx.compose.runtime.mutableStateSetOf(): androidx.compose.runtime.snapshots.SnapshotStateSet"""
+    ...
+
+def never_equal_policy() -> SnapshotMutationPolicy:
+    """Kotlin: androidx.compose.runtime.neverEqualPolicy(): androidx.compose.runtime.SnapshotMutationPolicy"""
+    ...
+
+def produce_state__Any_Any(initial_value: _t.Any | None, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State:
+    """Kotlin: androidx.compose.runtime.produceState(initialValue: kotlin.Any?, producer: kotlin.Function2): androidx.compose.runtime.State"""
+    ...
+
+def produce_state__Any_Any_Any(initial_value: _t.Any | None, key1: _t.Any | None, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State:
+    """Kotlin: androidx.compose.runtime.produceState(initialValue: kotlin.Any?, key1: kotlin.Any?, producer: kotlin.Function2): androidx.compose.runtime.State"""
+    ...
+
+def produce_state__Any_Any_Any_Any(initial_value: _t.Any | None, key1: _t.Any | None, key2: _t.Any | None, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State:
+    """Kotlin: androidx.compose.runtime.produceState(initialValue: kotlin.Any?, key1: kotlin.Any?, key2: kotlin.Any?, producer: kotlin.Function2): androidx.compose.runtime.State"""
+    ...
+
+def produce_state__Any_Any_Any_Any_Any(initial_value: _t.Any | None, key1: _t.Any | None, key2: _t.Any | None, key3: _t.Any | None, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State:
+    """Kotlin: androidx.compose.runtime.produceState(initialValue: kotlin.Any?, key1: kotlin.Any?, key2: kotlin.Any?, key3: kotlin.Any?, producer: kotlin.Function2): androidx.compose.runtime.State"""
+    ...
+
+def produce_state__Any_Array_Any(initial_value: _t.Any | None, keys: _t.Any, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State:
+    """Kotlin: androidx.compose.runtime.produceState(initialValue: kotlin.Any?, keys: kotlin.Array, producer: kotlin.Function2): androidx.compose.runtime.State"""
+    ...
+
+def referential_equality_policy() -> SnapshotMutationPolicy:
+    """Kotlin: androidx.compose.runtime.referentialEqualityPolicy(): androidx.compose.runtime.SnapshotMutationPolicy"""
+    ...
+
+def remember_updated_state(new_value: _t.Any | None) -> State:
+    """Kotlin: androidx.compose.runtime.rememberUpdatedState(newValue: kotlin.Any?): androidx.compose.runtime.State"""
+    ...
+
+def set_value(receiver: MutableState, /, this_obj: _t.Any | None, property: _t.Any, value: _t.Any | None) -> None:
+    """Kotlin: androidx.compose.runtime.MutableState.setValue(thisObj: kotlin.Any?, property: kotlin.reflect.KProperty, value: kotlin.Any?): kotlin.Unit"""
+    ...
+
+def snapshot_flow__Any(block: _t.Callable[[], _t.Any | None]) -> _t.Any:
+    """Kotlin: androidx.compose.runtime.snapshotFlow(block: kotlin.Function0): kotlinx.coroutines.flow.Flow"""
+    ...
+
+def snapshot_flow__SnapshotFlowManager_Any(manager: SnapshotFlowManager, block: _t.Callable[[], _t.Any | None]) -> _t.Any:
+    """Kotlin: androidx.compose.runtime.snapshotFlow(manager: androidx.compose.runtime.SnapshotFlowManager, block: kotlin.Function0): kotlinx.coroutines.flow.Flow"""
+    ...
+
+def structural_equality_policy() -> SnapshotMutationPolicy:
+    """Kotlin: androidx.compose.runtime.structuralEqualityPolicy(): androidx.compose.runtime.SnapshotMutationPolicy"""
+    ...
+
+@_t.overload
+def derived_state_of(calculation: _t.Callable[[], _t.Any | None]) -> State: ...
+@_t.overload
+def derived_state_of(policy: SnapshotMutationPolicy, calculation: _t.Callable[[], _t.Any | None]) -> State: ...  # type: ignore[overload-cannot-match]
+
+@_t.overload
+def produce_state(initial_value: _t.Any | None, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State: ...
+@_t.overload
+def produce_state(initial_value: _t.Any | None, key1: _t.Any | None, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State: ...  # type: ignore[overload-cannot-match]
+@_t.overload
+def produce_state(initial_value: _t.Any | None, key1: _t.Any | None, key2: _t.Any | None, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State: ...  # type: ignore[overload-cannot-match]
+@_t.overload
+def produce_state(initial_value: _t.Any | None, key1: _t.Any | None, key2: _t.Any | None, key3: _t.Any | None, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State: ...  # type: ignore[overload-cannot-match]
+@_t.overload
+def produce_state(initial_value: _t.Any | None, keys: _t.Any, producer: _t.Callable[[ProduceStateScope, _t.Any], _t.Any | None]) -> State: ...  # type: ignore[overload-cannot-match]
+
+@_t.overload
+def snapshot_flow(block: _t.Callable[[], _t.Any | None]) -> _t.Any: ...
+@_t.overload
+def snapshot_flow(manager: SnapshotFlowManager, block: _t.Callable[[], _t.Any | None]) -> _t.Any: ...  # type: ignore[overload-cannot-match]
+
+def Composable(target):
+    ...
+
+app_root: State
+
+def state(initial):
+    ...
+
+def app(root):
+    ...

pythonx/compose/ui/__init__.py

@@ -0,0 +1,21 @@
+"""`pythonx/compose/ui/__init__.py` -- the 2024 `from .modifier import Modifier` wrapper, unexecuted, and why.
+
+## What used to be here, and why it never ran
+
+A `try...except` block executing `from .modifier import Modifier`, `modifier = Modifier()`, and
+`from .alignment import Alignment, AbsoluteAlignment`. `alignment.py` depended on `from java import jclass`
+(Chaquopy-era JVM class lookup, retired in this codebase).
+
+## How `pythonx.compose.ui` resolves
+
+`import pythonx.compose.ui` loads this file; it is an ordinary package on disk. The binder serves the
+Kotlin package under its Kotlin name, `androidx.compose.ui`, as a separate module, and renames
+nothing. This file re-exports it under Pythonic names (`Modifier`, `describe_modifier`, ...) by the
+one rule in `pythonx/compose/_reexport.py` (SPEC section 3); it names no declaration itself.
+"""
+
+from __future__ import annotations
+
+from pythonx.compose._reexport import reexport
+
+__getattr__, __dir__ = reexport(__name__)