feat(components,utils)!: unify constructors; set Android context

owenthcarey · owenthcarey · commit 4c06b67214ea · 2025-10-09T13:49:49.000-07:00
diff --git a/apps/pythonnative_demo/app/main_page.py b/apps/pythonnative_demo/app/main_page.py
@@ -7,11 +7,11 @@ def __init__(self, native_instance):
 
     def on_create(self):
         super().on_create()
-        stack_view = pn.StackView(self.native_instance)
+        stack_view = pn.StackView()
         # list_data = ["item_{}".format(i) for i in range(100)]
         # list_view = pn.ListView(self.native_instance, list_data)
         # stack_view.add_view(list_view)
-        button = pn.Button(self.native_instance, "Button")
+        button = pn.Button("Button")
         button.set_on_click(lambda: self.navigate_to(""))
         # button.set_on_click(lambda: print("Button was clicked!"))
         stack_view.add_view(button)
diff --git a/apps/pythonnative_demo/app/second_page.py b/apps/pythonnative_demo/app/second_page.py
@@ -7,8 +7,8 @@ def __init__(self, native_instance):
 
     def on_create(self):
         super().on_create()
-        stack_view = pn.StackView(self.native_instance)
-        label = pn.Label(self.native_instance, "Second page!")
+        stack_view = pn.StackView()
+        label = pn.Label("Second page!")
         stack_view.add_view(label)
         self.set_root_view(stack_view)
 
diff --git a/docs/api/pythonnative.md b/docs/api/pythonnative.md
@@ -1,3 +1,9 @@
 # pythonnative package
 
 API reference will be generated here via mkdocstrings.
+
+Key flags and helpers (0.2.0):
+
+- `pythonnative.utils.IS_ANDROID`: platform flag with robust detection for Chaquopy/Android.
+- `pythonnative.utils.get_android_context()`: returns the current Android Activity/Context when running on Android.
+- `pythonnative.utils.set_android_context(ctx)`: set by `pythonnative.Page` on Android; you generally don’t call this directly.
diff --git a/docs/concepts/components.md b/docs/concepts/components.md
@@ -1,3 +1,31 @@
 # Components
 
 High-level overview of PythonNative components and how they map to native UI.
+
+## Constructor pattern (0.2.0)
+
+- All core components share a consistent, contextless constructor on both platforms.
+- On Android, a `Context` is acquired implicitly from the current `Activity` set by `pn.Page`.
+- On iOS, UIKit classes are allocated/initialized directly.
+
+Examples:
+
+```python
+import pythonnative as pn
+
+class MainPage(pn.Page):
+    def __init__(self, native_instance):
+        super().__init__(native_instance)
+
+    def on_create(self):
+        super().on_create()
+        stack = pn.StackView()
+        stack.add_view(pn.Label("Hello"))
+        stack.add_view(pn.Button("Tap me"))
+        stack.add_view(pn.TextField("initial"))
+        self.set_root_view(stack)
+```
+
+Notes:
+- `pn.Page` stores the Android `Activity` so components like `pn.Button()` and `pn.Label()` can construct their native counterparts.
+- If you construct views before the `Page` is created on Android, a runtime error will be raised because no `Context` is available.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -10,5 +10,6 @@ pn --help
   - Scaffolds `app/`, `pythonnative.json`, `requirements.txt`, `.gitignore`
 - Run: `pn run android` or `pn run ios`
   - Uses bundled templates; copies your `app/` into the platform project
+  - On Android, `pn.Page` provides the Activity context so components can be created without passing a context
 - Clean: `pn clean`
   - Removes the `build/` directory safely
diff --git a/src/pythonnative/activity_indicator_view.py b/src/pythonnative/activity_indicator_view.py
@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -31,10 +31,11 @@ def stop_animating(self) -> None:
     from java import jclass
 
     class ActivityIndicatorView(ActivityIndicatorViewBase, ViewBase):
-        def __init__(self, context) -> None:
+        def __init__(self) -> None:
             super().__init__()
             self.native_class = jclass("android.widget.ProgressBar")
             # self.native_instance = self.native_class(context, None, android.R.attr.progressBarStyleLarge)
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             self.native_instance.setIndeterminate(True)
 
diff --git a/src/pythonnative/button.py b/src/pythonnative/button.py
@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import Callable
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -36,9 +36,10 @@ def set_on_click(self, callback: Callable[[], None]) -> None:
     from java import dynamic_proxy, jclass
 
     class Button(ButtonBase, ViewBase):
-        def __init__(self, context, title: str = "") -> None:
+        def __init__(self, title: str = "") -> None:
             super().__init__()
             self.native_class = jclass("android.widget.Button")
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             self.set_title(title)
 
diff --git a/src/pythonnative/cli/pn.py b/src/pythonnative/cli/pn.py
@@ -53,8 +53,8 @@ def __init__(self, native_instance):
 
     def on_create(self):
         super().on_create()
-        stack = pn.StackView(self.native_instance)
-        stack.add_view(pn.Label(self.native_instance, \"Hello from PythonNative!\"))
+        stack = pn.StackView()
+        stack.add_view(pn.Label(\"Hello from PythonNative!\"))
         self.set_root_view(stack)
 """
             )
diff --git a/src/pythonnative/image_view.py b/src/pythonnative/image_view.py
@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -32,9 +32,10 @@ def get_image(self) -> str:
     from java import jclass
 
     class ImageView(ImageViewBase, ViewBase):
-        def __init__(self, context, image: str = "") -> None:
+        def __init__(self, image: str = "") -> None:
             super().__init__()
             self.native_class = jclass("android.widget.ImageView")
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             if image:
                 self.set_image(image)
diff --git a/src/pythonnative/label.py b/src/pythonnative/label.py
@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -31,9 +31,10 @@ def get_text(self) -> str:
     from java import jclass
 
     class Label(LabelBase, ViewBase):
-        def __init__(self, context, text: str = "") -> None:
+        def __init__(self, text: str = "") -> None:
             super().__init__()
             self.native_class = jclass("android.widget.TextView")
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             self.set_text(text)
 
diff --git a/src/pythonnative/page.py b/src/pythonnative/page.py
@@ -31,7 +31,7 @@
 
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, set_android_context
 from .view import ViewBase
 
 # ========================================
@@ -103,6 +103,8 @@ def __init__(self, native_instance) -> None:
             self.native_class = jclass("android.app.Activity")
             self.native_instance = native_instance
             # self.native_instance = self.native_class()
+            # Stash the Activity so child views can implicitly acquire a Context
+            set_android_context(native_instance)
 
         def set_root_view(self, view) -> None:
             self.native_instance.setContentView(view.native_instance)
diff --git a/src/pythonnative/progress_view.py b/src/pythonnative/progress_view.py
@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -31,10 +31,11 @@ def get_progress(self) -> float:
     from java import jclass
 
     class ProgressView(ProgressViewBase, ViewBase):
-        def __init__(self, context) -> None:
+        def __init__(self) -> None:
             super().__init__()
             self.native_class = jclass("android.widget.ProgressBar")
             # self.native_instance = self.native_class(context, None, android.R.attr.progressBarStyleHorizontal)
+            context = get_android_context()
             self.native_instance = self.native_class(context, None, jclass("android.R$attr").progressBarStyleHorizontal)
             self.native_instance.setIndeterminate(False)
 
diff --git a/src/pythonnative/stack_view.py b/src/pythonnative/stack_view.py
@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import Any, List
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -29,9 +29,10 @@ def add_view(self, view) -> None:
     from java import jclass
 
     class StackView(StackViewBase, ViewBase):
-        def __init__(self, context) -> None:
+        def __init__(self) -> None:
             super().__init__()
             self.native_class = jclass("android.widget.LinearLayout")
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             self.native_instance.setOrientation(self.native_class.VERTICAL)
 
diff --git a/src/pythonnative/switch.py b/src/pythonnative/switch.py
@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -31,9 +31,10 @@ def is_on(self) -> bool:
     from java import jclass
 
     class Switch(SwitchBase, ViewBase):
-        def __init__(self, context, value: bool = False) -> None:
+        def __init__(self, value: bool = False) -> None:
             super().__init__()
             self.native_class = jclass("android.widget.Switch")
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             self.set_on(value)
 
diff --git a/src/pythonnative/text_field.py b/src/pythonnative/text_field.py
@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -31,9 +31,10 @@ def get_text(self) -> str:
     from java import jclass
 
     class TextField(TextFieldBase, ViewBase):
-        def __init__(self, context, text: str = "") -> None:
+        def __init__(self, text: str = "") -> None:
             super().__init__()
             self.native_class = jclass("android.widget.EditText")
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             self.native_instance.setSingleLine(True)
             self.set_text(text)
diff --git a/src/pythonnative/text_view.py b/src/pythonnative/text_view.py
@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -31,9 +31,10 @@ def get_text(self) -> str:
     from java import jclass
 
     class TextView(TextViewBase, ViewBase):
-        def __init__(self, context, text: str = "") -> None:
+        def __init__(self, text: str = "") -> None:
             super().__init__()
             self.native_class = jclass("android.widget.EditText")
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             self.native_instance.setLines(3)
             self.native_instance.setMaxLines(5)
diff --git a/src/pythonnative/utils.py b/src/pythonnative/utils.py
@@ -1,3 +1,67 @@
 import os
+from typing import Any, Optional
 
-IS_ANDROID = "ANDROID_BOOTLOGO" in os.environ
+# Platform detection with multiple fallbacks suitable for Chaquopy/Android
+_is_android: Optional[bool] = None
+
+
+def _detect_android() -> bool:
+    # 1) Direct environment hints commonly present on Android
+    env = os.environ
+    if "ANDROID_BOOTLOGO" in env or "ANDROID_ROOT" in env or "ANDROID_DATA" in env or "ANDROID_ARGUMENT" in env:
+        return True
+
+    # 2) Chaquopy-specific: the builtin 'java' package is available
+    try:
+        # Import inside try so importing this module doesn't explode off-device
+        from java import jclass
+
+        _ = jclass  # silence linter unused
+        return True
+    except Exception:
+        pass
+
+    # 3) Last resort: some Android Python dists set os.name/others, but avoid false positives
+    return False
+
+
+def _ensure_platform_detection() -> None:
+    global _is_android
+    if _is_android is None:
+        _is_android = _detect_android()
+
+
+def _get_is_android() -> bool:
+    _ensure_platform_detection()
+    assert _is_android is not None
+    return _is_android
+
+
+IS_ANDROID: bool = _get_is_android()
+
+# Global hook to access the current Android Activity/Context from Python code
+_android_context: Any = None
+
+
+def set_android_context(context: Any) -> None:
+    """Record the current Android Activity/Context for implicit constructor use.
+
+    On Android, Python UI components require a Context to create native views.
+    We capture it when a Page is constructed from the host Activity so component
+    constructors can be platform-consistent and avoid explicit context params.
+    """
+
+    global _android_context
+    _android_context = context
+
+
+def get_android_context() -> Any:
+    """Return the previously set Android Activity/Context or raise if missing."""
+
+    if not IS_ANDROID:
+        raise RuntimeError("get_android_context() called on non-Android platform")
+    if _android_context is None:
+        raise RuntimeError(
+            "Android context is not set. Ensure Page is initialized from an Activity " "before constructing views."
+        )
+    return _android_context
diff --git a/src/pythonnative/web_view.py b/src/pythonnative/web_view.py
@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-from .utils import IS_ANDROID
+from .utils import IS_ANDROID, get_android_context
 from .view import ViewBase
 
 # ========================================
@@ -27,9 +27,10 @@ def load_url(self, url: str) -> None:
     from java import jclass
 
     class WebView(WebViewBase, ViewBase):
-        def __init__(self, context, url: str = "") -> None:
+        def __init__(self, url: str = "") -> None:
             super().__init__()
             self.native_class = jclass("android.webkit.WebView")
+            context = get_android_context()
             self.native_instance = self.native_class(context)
             self.load_url(url)
 
