- 
-
- Build native Android and iOS apps in Python. -
- -
- 
- 
- 
- Documentation · - Getting Started · - Examples · - Contributing -
- ---- - -## Overview - -PythonNative is a cross-platform toolkit for building native Android and iOS apps in Python. It provides a **declarative, React-like component model** with hooks and automatic reconciliation, powered by Chaquopy on Android and rubicon-objc on iOS. Write function components with `use_state`, `use_effect`, and friends, just like React, and let PythonNative handle creating and updating native views. - -## Features - -- **Declarative UI:** Describe *what* your UI should look like with element functions (`Text`, `Button`, `Column`, `Row`, etc.). PythonNative creates and updates native views automatically. -- **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect`, and navigation with `use_navigation`, all through one consistent pattern. -- **`style` prop:** Pass all visual and layout properties through a single `style` dict, composable via `StyleSheet`. -- **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. -- **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge. -- **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app. -- **Navigation:** Push and pop screens with argument passing via the `use_navigation()` hook. -- **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access. - -## Quick Start - -### Installation - -```bash -pip install pythonnative -``` - -### Usage - -```python -import pythonnative as pn - - -@pn.component -def MainPage(): - count, set_count = pn.use_state(0) - return pn.Column( - pn.Text(f"Count: {count}", style={"font_size": 24}), - pn.Button( - "Tap me", - on_click=lambda: set_count(count + 1), - ), - style={"spacing": 12, "padding": 16}, - ) -``` - -## Documentation - -Visit [docs.pythonnative.com](https://docs.pythonnative.com/) for the full documentation, including getting started guides, platform-specific instructions for Android and iOS, API reference, and working examples. - -## Contributing - -Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, coding standards, and guidelines for submitting pull requests. - -## License - -[MIT](LICENSE) diff --git a/api/component-properties/index.html b/api/component-properties/index.html new file mode 100644 index 0000000..a560f0c --- /dev/null +++ b/api/component-properties/index.html @@ -0,0 +1,1669 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +All visual and layout properties are passed via the style dict (or list of dicts) to element functions. Behavioural properties (callbacks, data, content) remain as keyword arguments.
style)¶All components accept these layout properties in their style dict:
width — fixed width in dp (Android) / pt (iOS)height — fixed heightflex — flex grow factor (shorthand for flex_grow)flex_grow — how much a child grows to fill available spaceflex_shrink — how much a child shrinks when space is limitedmargin — outer spacing (int, float, or dict with horizontal, vertical, left, top, right, bottom)min_width, max_width — width constraintsmin_height, max_height — height constraintsalign_self — override parent alignment ("stretch", "flex_start", "center", "flex_end")key — stable identity for reconciliation (passed as a kwarg, not inside style)pn.View(*children, style={
+ "flex_direction": "column",
+ "justify_content": "center",
+ "align_items": "center",
+ "overflow": "hidden",
+ "spacing": 8,
+ "padding": 16,
+ "background_color": "#F5F5F5",
+})
+Universal flex container (like React Native's View). Defaults to flex_direction: "column".
Flex container properties (inside style):
flex_direction — "column" (default), "row", "column_reverse", "row_reverse"justify_content — "flex_start", "center", "flex_end", "space_between", "space_around", "space_evenly"align_items — "stretch", "flex_start", "center", "flex_end"overflow — "visible" (default), "hidden"spacing, padding, background_colorpn.Text(text, style={"font_size": 18, "color": "#333", "bold": True, "text_align": "center"})
+text — display string (positional)font_size, color, bold, text_align, background_color, max_linespn.Button(title, on_click=handler, style={"color": "#FFF", "background_color": "#007AFF", "font_size": 16})
+title — button label (positional)on_click — callback () -> Noneenabled — interactive state (kwarg, default True)color, background_color, font_sizepn.Column(*children, style={"spacing": 12, "padding": 16, "align_items": "center"})
+pn.Row(*children, style={"spacing": 8, "justify_content": "space_between"})
+Convenience wrappers for View with fixed flex_direction:
Column = View with flex_direction: "column" (always vertical)Row = View with flex_direction: "row" (always horizontal)
*children — child elements (positional)
spacing — gap between children (dp / pt)padding — inner padding (int for all sides, or dict with horizontal, vertical, left, top, right, bottom)align_items — cross-axis alignment: "stretch", "flex_start", "center", "flex_end", "leading", "trailing"justify_content — main-axis distribution: "flex_start", "center", "flex_end", "space_between", "space_around", "space_evenly"overflow — "visible" (default), "hidden"background_color — container backgroundpn.SafeAreaView(*children, style={"background_color": "#FFF", "padding": 8})
+Container that respects safe area insets (notch, status bar).
+pn.ScrollView(child, style={"background_color": "#FFF"})
+pn.TextInput(value="", placeholder="Enter text", on_change=handler, secure=False,
+ style={"font_size": 16, "color": "#000", "background_color": "#FFF"})
+on_change — callback (str) -> None receiving new textpn.Image(source="https://example.com/photo.jpg", style={"width": 200, "height": 150, "scale_type": "cover"})
+source — image URL (http://... / https://...) or local resource namewidth, height, scale_type ("cover", "contain", "stretch", "center"), background_colorpn.Switch(value=False, on_change=handler)
+on_change — callback (bool) -> Nonepn.Slider(value=0.5, min_value=0.0, max_value=1.0, on_change=handler)
+on_change — callback (float) -> Nonepn.ProgressBar(value=0.5, style={"background_color": "#EEE"})
+value — 0.0 to 1.0pn.ActivityIndicator(animating=True)
+pn.WebView(url="https://example.com")
+pn.Spacer(size=16, flex=1)
+size — fixed dimension in dp / ptflex — flex grow factorpn.Pressable(child, on_press=handler, on_long_press=handler)
+Wraps any child element with tap/long-press handling.
+pn.Modal(*children, visible=show_modal, on_dismiss=handler, title="Confirm",
+ style={"background_color": "#FFF"})
+Overlay dialog shown when visible=True.
pn.Element("TabBar", {
+ "items": [
+ {"name": "Home", "title": "Home"},
+ {"name": "Settings", "title": "Settings"},
+ ],
+ "active_tab": "Home",
+ "on_tab_select": handler,
+})
+Native tab bar — typically created automatically by Tab.Navigator.
| Platform | +Native view | +
|---|---|
| Android | +BottomNavigationView |
+
| iOS | +UITabBar |
+
items — list of {"name": str, "title": str} dicts defining each tabactive_tab — the name of the currently active tabon_tab_select — callback (str) -> None receiving the selected tab namepn.FlatList(data=items, render_item=render_fn, key_extractor=key_fn,
+ separator_height=1, style={"background_color": "#FFF"})
+data — list of itemsrender_item — (item, index) -> Element functionkey_extractor — (item, index) -> str for stable keysseparator_height — spacing between itemspythonnative.create_page(...) — called internally by native templates to bootstrap the root component. You don't call this directly.
pythonnative.Text, Button, Column, Row, ScrollView, TextInput, Image, Switch, ProgressBar, ActivityIndicator, WebView, Spacerpythonnative.View, SafeAreaView, Modal, Slider, Pressable, FlatListEach returns an Element descriptor. Visual and layout properties are passed via style={...}. See the Component Property Reference for full details.
pythonnative.ErrorBoundary(child, fallback=...) — catches render errors in child and displays fallback instead. fallback may be an Element or a callable that receives the exception and returns an Element.
pythonnative.Element — the descriptor type returned by element functions. You generally don't create these directly.
Function component primitives:
+pythonnative.component — decorator to create a function componentpythonnative.use_state(initial) — local component statepythonnative.use_reducer(reducer, initial_state) — reducer-based state management; returns (state, dispatch)pythonnative.use_effect(effect, deps) — side effects, run after native commitpythonnative.use_navigation() — navigation handle (navigate/go_back/get_params)pythonnative.use_route() — convenience hook for current route paramspythonnative.use_focus_effect(effect, deps) — like use_effect but only runs when the screen is focusedpythonnative.use_memo(factory, deps) — memoised valuespythonnative.use_callback(fn, deps) — stable function referencespythonnative.use_ref(initial) — mutable ref objectpythonnative.use_context(context) — read from contextpythonnative.create_context(default) — create a new contextpythonnative.Provider(context, value, child) — provide a context valueDeclarative, component-based navigation system:
+pythonnative.NavigationContainer(child) — root container for the navigation treepythonnative.create_stack_navigator() — create a stack-based navigator (returns object with .Navigator and .Screen)pythonnative.create_tab_navigator() — create a tab-based navigatorpythonnative.create_drawer_navigator() — create a drawer-based navigatorpythonnative.batch_updates() — context manager that batches multiple state updates into a single re-renderpythonnative.StyleSheet — utility for creating and composing style dictspythonnative.ThemeContext — built-in theme context (defaults to light theme)pythonnative.native_modules.Camera — photo capture and gallery pickingpythonnative.native_modules.Location — GPS / location servicespythonnative.native_modules.FileSystem — app-scoped file I/Opythonnative.native_modules.Notifications — local push notificationspythonnative.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 internally during page bootstrapping; you generally don't call this directly.pythonnative.utils.get_android_fragment_container() — returns the current Fragment container ViewGroup used for page rendering.pythonnative.reconciler.Reconciler — diffs element trees and applies minimal native mutations. Supports key-based child reconciliation, function components, context providers, and error boundaries. Effects are flushed after each mount/reconcile pass. Used internally by create_page.
pythonnative.hot_reload.FileWatcher — watches a directory for file changes and triggers a callback. Used by pn run --hot-reload.
pythonnative.hot_reload.ModuleReloader — reloads changed Python modules on the device and triggers page re-rendering.
pythonnative.native_views.NativeViewRegistry — maps element type names to platform-specific handlers. Use set_registry() to inject a mock for testing.
The native_views package is organised into submodules:
pythonnative.native_views.base — shared ViewHandler protocol and utilities (parse_color_int, resolve_padding, LAYOUT_KEYS)pythonnative.native_views.android — Android handlers (only imported at runtime on Android via Chaquopy)pythonnative.native_views.ios — iOS handlers (only imported at runtime on iOS via rubicon-objc)