Package overview

PythonNative re-exports a small public surface from pythonnative/__init__.py. Most user code only ever touches the names in this overview; deeper internals (reconciler, native_views, page) are documented for contributors and integrators.

Entry point

Your app module defines a top-level component named App:

import pythonnative as pn

@pn.component
def App():
    return pn.NavigationContainer(...)

The bundled Android ScreenFragment and iOS ViewController load your app by module path ("app.main") and look up the module's top-level App attribute. There is no registration step or imperative bootstrap call. If you need to expose a differently-named root component, configure the templates to load an explicit dotted path like "app.main.RootScreen" instead.

PythonNative: declarative native UI for Android and iOS.

PythonNative is a cross-platform toolkit that turns Python @component functions into real, native Android and iOS views. The component model is React-like (function components plus hooks), but rendering happens through direct platform bindings: Chaquopy on Android (Java) and rubicon-objc on iOS (Objective-C). There is no JavaScript bridge.

Key building blocks:

• Element factories (Text, Button, Column, etc.) return immutable Element descriptors.
• Hooks (use_state, use_effect, use_reducer, etc.) manage state, side effects, and context inside @component functions.
• Navigation is built from NavigationContainer plus one of the create_stack_navigator, create_tab_navigator, or create_drawer_navigator factories.
• Styling uses a single style dict per element (or a list of dicts), composable via StyleSheet. PythonNative ships a fully-typed Style TypedDict so editors and mypy validate every key as you type.
• Animations use the Animated namespace, modeled on React Native's animation API. Animations are driven natively (Core Animation / ViewPropertyAnimator) whenever possible.
• Gestures attach to any view via the gestures= prop using descriptors from pythonnative.gestures (Tap, LongPress, Pan, Swipe, Pinch, Rotation).
• Custom native components can be authored with the pythonnative.sdk package: define a typed Props dataclass, implement a ViewHandler for each platform, and register it via @native_component (or expose it from a PyPI package via the pythonnative.handlers entry-point group).

Example

import pythonnative as pn

@pn.component
def App():
    count, set_count = pn.use_state(0)
    return pn.Column(
        pn.Text(f"Count: {count}", style=pn.style(font_size=24)),
        pn.Button("+", on_click=lambda: set_count(count + 1)),
        style=pn.style(spacing=12),
    )

Where to look next

The reference is split per module so each page stays scannable:

Area	Page	Key symbols
Element factories	Components	Text, Button, Column, Row, ScrollView, FlatList, SectionList, Modal, Pressable, StatusBar, KeyboardAvoidingView, RefreshControl, Picker, Fragment, ErrorBoundary
Hooks	Hooks	use_state, use_reducer, use_effect, use_memo, use_ref, use_context, use_window_dimensions, use_safe_area_insets, use_keyboard_height, memo
Animations	Animated	Animated, AnimatedValue, use_animated_value
System dialogs	Alerts	Alert
Platform	Platform	Platform
Navigation	Navigation	NavigationContainer, create_stack_navigator, create_tab_navigator, create_drawer_navigator, use_navigation
Styling	Style	StyleSheet, Style, StyleProp, style, ThemeContext
Element descriptor	Element	Element
Screen host	Screen	create_screen
Reconciler	Reconciler	Reconciler
Native modules	Native modules	Camera, Location, FileSystem, Notifications
Native views	Native views	NativeViewRegistry, ViewHandler
Hot reload	Hot reload	FileWatcher, ModuleReloader
Custom components SDK	SDK	Props, ViewHandler, native_component, register_component, element_factory
Utilities	Utilities	IS_ANDROID, IS_IOS, get_android_context
CLI	CLI (pn)	pn init, pn run, pn clean

Property reference

All visual and layout properties pass through the style dict (or a list of dicts). The full per-component property catalogue lives in Component properties.