Merge remote-tracking branch 'origin/develop' into work/include-provider

Author: b-re-w

.github/workflows/stubs.yml

@@ -32,8 +32,6 @@ concurrency:
 jobs:
   stubs:
     name: Generate stubs
-    # ubuntu, not macos: two Kotlin names can differ only by case (`graphics.Shadow` the class module and
-    # `graphics.shadow` the package), which are two paths here and one on a case-insensitive filesystem.
     runs-on: ubuntu-latest
     permissions:
       contents: write   # attaching the stubs to a tag's release
@@ -108,3 +106,44 @@ jobs:
           gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 \
             || gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes "Kotlin-name stubs for the Compose version this tag builds against."
           gh release upload "$GITHUB_REF_NAME" build/kotlin-stubs.zip --clobber
+
+  # Issue #44: the stub layout is case-unique, so the stubs generate, extract and type-check on a
+  # case-insensitive filesystem too (`graphics.Shadow` the class and `graphics.shadow` the package).
+  stubs-macos:
+    name: Generate stubs (macOS, case-insensitive)
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'zulu'
+          cache: 'gradle'
+
+      - name: Setup Python (for mypy)
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Generate the stubs over the Compose jars
+        run: ./gradlew :ksp-fixtures:compose:generatePythonStubs --console=plain
+
+      - name: No two stub paths are equal under case folding
+        run: |
+          python3 - ksp-fixtures/compose/build/generated/pythonStubs/desktopMain <<'PY'
+          import os, sys
+          seen = {}
+          for root, dirs, files in os.walk(sys.argv[1]):
+              for name in dirs + files:
+                  rel = os.path.relpath(os.path.join(root, name), sys.argv[1])
+                  seen.setdefault(rel.casefold(), []).append(rel)
+          clashes = [v for v in seen.values() if len(v) > 1]
+          print("clashes:", clashes)
+          sys.exit(1 if clashes else 0)
+          PY
+
+      - name: Type-check a consumer against them (mypy)
+        run: tools/stubs/check-stubs.sh ksp-fixtures/compose/build/generated/pythonStubs/desktopMain

docs/SPEC.md

@@ -173,14 +173,19 @@ All in `PM/commonTest`, so they run wherever the interpreter loads.
 - **U-8** A function on a Kotlin-named module carries Kotlin's own surface and nothing else: the
   Kotlin declaration name, keyword arguments by **Kotlin parameter names**, Kotlin defaults for omitted
   parameters, overload sets under the base name, and its signature as public metadata
-  (`inspect.signature`, `python_multiplatform.describe`; contract in `KotlinSurface.kt`'s KDoc). No
+  (`inspect.signature`, `python_multiplatform.describe`; contract in `KotlinSurface.kt`'s KDoc).
+  `describe(module, name)` describes any bound name, a named constant (`STATIC_GETTER`) included,
+  without evaluating it (#36). A module's `dir()` lists its direct child packages/objects and reading
+  one as an attribute imports it (#35) — Kotlin names only. No
   member or parameter is renamed; the binder creates no `pythonx` module and a real `pythonx` package
   on disk is what `import pythonx` loads. The answer is the same whichever installer
   (`PythonProxySource`, `PythonxAdapter`) ran first for a table. `Status: implemented` on desktop —
-  `PM/desktopTest/.../pythonx/KotlinNamedSurfaceTest.kt`, `ksp-fixtures/compose/.../KotlinSignatureMetadataTest.kt`.
+  `PM/desktopTest/.../pythonx/KotlinNamedSurfaceTest.kt`, `BinderNamespaceTest.kt`, `ksp-fixtures/compose/.../KotlinSignatureMetadataTest.kt`.
 - **U-9** A Pythonic package can serve extra member names on a Kotlin proxy through one hook,
   `python_multiplatform.binding.add_member_resolver(fn)`, `fn(kotlin_type_name, requested_name,
-  kotlin_member_names) -> kotlin_name | None`, asked only when no Kotlin member of that name exists.
+  kotlin_member_names) -> kotlin_name | (kotlin_name, keyword_map) | None`, asked when no Kotlin member
+  of that name exists — and, for a Kotlin-named member, only when a call passes keywords and only for
+  its `{python_kw: kotlinParam}` keyword map (#34).
   The binder renames nothing itself (no resolver: `AttributeError`), and aliases are cached in the
   registry, not written on the proxy class (`dir()` stays Kotlin-only). Contract in `KotlinSurface.kt`'s
   KDoc. `Status: implemented` on desktop — `PM/desktopTest/.../pythonx/MemberResolverTest.kt`,
@@ -211,6 +216,15 @@ All in `PM/commonTest`, so they run wherever the interpreter loads.
   `ksp-fixtures/compose/src/desktopTest/` (`ComposableRenderTest.kt`, `M3ProofRenderTest.kt`,
   `CallbackDrivenRenderTest.kt`, pointer/drag render tests), `GP/artifact/ComposableBindingTest.kt`;
   `planned` on Android, iOS and wasm.
+- **B-8** A host draws a Python-declared application root with
+  `python.multiplatform.compose.PythonContent(root: PyObject)` or `PythonContent(module, attribute)`,
+  from the `python-multiplatform-compose` module (`python-multiplatform` itself does not depend on
+  Compose). The root is a Python callable, or a Compose `State` that Python holds whose value is that
+  callable. The state is read inside the composition, so a Python write into it replaces the root on
+  the next frame with no host call; Python callables a root passed into composables are released when
+  that root is replaced or the composition is disposed. The entry point names no library.
+  `Status: implemented` on desktop — `ksp-fixtures/compose/.../PythonContentRenderTest.kt`; the module
+  compiles for Android, nothing runs there yet.
 - **B-7** The plugin generates `.pyi` stubs for the Kotlin-named modules only, under Kotlin names
   (keyword parameters by Kotlin name, `= ...` for a Kotlin default, receiver positional-only). Types are
   the declared Kotlin types: one stub class per bound type in the module of its own package, `Dp | float`
@@ -262,6 +276,12 @@ All in `PM/commonTest`, so they run wherever the interpreter loads.
 - **N-3** Binding Kotlin/Native klib declarations at run time (B-2). `Status: planned`.
 - **N-4** Linux and Windows desktop runs in CI (P-2). `Status: planned`.
 - **N-5** Native-image upcall verification as an automated test (U-6). `Status: planned`.
+- **N-6** Compose state created and written from Python through the binder:
+  `androidx.compose.runtime.mutableStateOf(x)` callable, and `.value` of the returned `MutableState`
+  readable and writable on its proxy. Neither is bound today: the walker emits only `FUNCTION` and
+  `STATIC_GETTER` entries (no instance members), and declines every declaration whose signature
+  mentions a type parameter. B-8's test writes its root state through a fixture-local KSP-bound
+  setter instead. `Status: planned`.
 
 ---
 

docs/design/pyi-generation-design.md

@@ -346,10 +346,18 @@ turns `PaddingValues`, `TextStyle`, `Color`, `AnnotatedString` and `Dp` itself i
 collapses to its `float`). It is the honest loss of this design, not a bug to chase: the alternatives
 are a differently named class (a renamed spelling the binder does not have) or a private side module.
 
-**Case-colliding module paths** (`androidx.compose.ui.graphics.Shadow`, a class module, and
-`...graphics.shadow`, a package) are two files on Linux and one on macOS and Windows.
-`PythonStubsTask` warns (`caseCollidingPaths`); generate and publish from a case-sensitive
-filesystem, which is why the CI job (`.github/workflows/stubs.yml`) runs on ubuntu.
+**Stub paths are case-unique** (issue #44). `androidx.compose.ui.graphics.Shadow` (a class the runtime
+exposes as a module) and `...graphics.shadow` (a package) would be one directory on macOS and Windows.
+The rule: a class module whose path equals a sibling's under case folding (directories above a module
+count) is emitted in its parent package's `__init__.pyi` -- as the class `Shadow`, its functions as
+`@staticmethod`s, nested class modules as nested classes -- and the package keeps `shadow/__init__.pyi`.
+In each colliding group the all-lower-case spelling is the package and keeps its path. A class module
+without a collision still gets its own `<Class>/__init__.pyi`. The runtime import path is unchanged; only
+the stub layout moves, and `from androidx.compose.ui.graphics import Shadow` resolves to the class.
+If the parent package already defines a function of the same name the class cannot sit beside it, and
+nothing is emitted for that module (the runtime resolves the name to the function too).
+`StubCaseLayoutTest` asserts no two emitted paths are equal under `lowercase()`;
+`PythonStubsTask` still warns (`caseCollidingPaths`) as a backstop, and the CI job runs on macOS as well.
 
 ### 3.2 Java declarations have no types to map
 

gradle/libs.versions.toml

@@ -12,6 +12,9 @@ androidx-lifecycle = "2.10.0"
 androidx-material = "1.12.0"
 androidx-test-junit = "1.2.1"
 compose-plugin = "1.11.1"
+# JetBrains stopped publishing material-icons with Compose after 1.7.3 (Maven Central: newest is 1.7.3);
+# it is the version Compose Multiplatform 1.11.x points to, resolved against 1.11.1's ui/ui-graphics.
+compose-material-icons = "1.7.3"
 graalvm-buildtools = "0.10.6"
 junit = "4.13.2"
 kotlin = "2.4.20-Beta2"
@@ -20,6 +23,7 @@ kotlinx-coroutines = "1.8.1"
 ksp = "2.3.11"
 
 [libraries]
+compose-material-icons-core = { module = "org.jetbrains.compose.material:material-icons-core", version.ref = "compose-material-icons" }
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
 kotlin-test-junit = { module = "org.jetbrains.kotlin:kotlin-test-junit", version.ref = "kotlin" }
 junit = { group = "junit", name = "junit", version.ref = "junit" }

ksp-fixtures/compose/build.gradle.kts

@@ -45,10 +45,13 @@ kotlin {
         }
         val desktopMain by getting {
             dependencies {
+                implementation(projects.pythonMultiplatformCompose)
                 implementation(compose.runtime)
                 implementation(compose.foundation)
                 implementation(compose.material3)
                 implementation(compose.ui)
+                // `Icons.Default.Add` and friends (issue #37): the one place an `ImageVector` is built.
+                implementation(libs.compose.material.icons.core)
                 implementation(compose.desktop.currentOs)
             }
         }
@@ -92,6 +95,8 @@ pythonBindings {
             "androidx.compose.ui.graphics",
             "androidx.compose.ui.res",
             "androidx.compose.ui",
+            // 5. `material.icons` -- `Icons.Default` and the icon properties behind it (issue #37).
+            "androidx.compose.material.icons",
         ),
     )
     // Stubs on: `generatePythonStubs` over the real Compose jars is what `tools/stubs/check-stubs.sh` (the mypy

ksp-fixtures/compose/src/desktopMain/kotlin/fixture/compose/PythonComposed.kt

@@ -1,9 +1,9 @@
 package fixture.compose
 
-import androidx.compose.runtime.currentComposer
 import androidx.compose.runtime.remember
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.composed
+import python.multiplatform.compose.withPythonComposer
 import python.multiplatform.ffi.PyObject
 import python.multiplatform.ffi.Python3
 import python.multiplatform.ffi.types.basic.PyInt
@@ -53,8 +53,9 @@ import python.native.ffi.PyLong_AsLongLong
  *
  * ### The composer, and the receiver, cross the same way [PythonComposition]'s does
  *
- * [currentComposer] is rooted and pushed onto `pythonx`'s composer stack (`pythonx.push_composer`) for
- * the duration of the call, so [factory] may itself call a bound composable (the same contract
+ * The composer is rooted and pushed onto the binding layer's composer stack for the duration of the
+ * call by `python-multiplatform-compose`'s `withPythonComposer` -- the same helper [PythonComposition]
+ * uses -- so [factory] may itself call a bound composable (the same contract
  * [PythonComposition] documents). `this` -- the `Modifier` chain [factory] receives as its receiver,
  * matching `@Composable Modifier.() -> Modifier` -- is rooted too and passed as a bare handle
  * (`int`), which `PythonxAdapter._coerce`'s OBJECT branch already accepts as a caller-selected
@@ -76,11 +77,11 @@ fun pythonComposed(modifier: Modifier, factory: PyObject): Modifier = modifier.c
     slot.invocations++
     ComposedInvocationSlot.lastCreated = slot
 
-    val composer = currentComposer
-    val composerRef = HandleTable.register(composer)
-    val receiverRef = HandleTable.register(this)
-    try {
-        Python3.exec("import python_multiplatform.binding as _pm_binding\n_pm_binding.push_composer(${composerRef.raw})")
+    val receiver = this
+    // The receiver is rooted *inside* the composer call: Compose forbids a try/finally around a
+    // composable invocation, so the release cannot wrap `withPythonComposer` from outside.
+    withPythonComposer {
+        val receiverRef = HandleTable.register(receiver)
         try {
             val receiverHandle = PyInt.from(receiverRef.raw)
             try {
@@ -101,19 +102,16 @@ fun pythonComposed(modifier: Modifier, factory: PyObject): Modifier = modifier.c
                     } else {
                         Python3.withPython { PyLong_AsLongLong(result.pointer) }
                     }
-                    (HandleTable.resolveRaw(raw) as? Modifier) ?: this
+                    (HandleTable.resolveRaw(raw) as? Modifier) ?: receiver
                 } finally {
                     result.close()
                 }
             } finally {
                 receiverHandle.close()
             }
         } finally {
-            Python3.exec("import python_multiplatform.binding as _pm_binding\n_pm_binding.pop_composer()")
+            HandleTable.release(receiverRef)
         }
-    } finally {
-        HandleTable.release(receiverRef)
-        HandleTable.release(composerRef)
     }
 }