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_press=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, Portal, ErrorBoundary
Hooks	Hooks	use_state, use_reducer, use_effect, use_layout_effect, use_memo, use_ref, use_imperative_handle, use_context, use_back_handler, use_window_dimensions, use_safe_area_insets, use_keyboard_height, use_color_scheme, 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, use_theme
Appearance	Appearance	use_color_scheme, appearance.set_color_scheme, appearance.get_color_scheme
Images	Images	images.fetch, images.clear_cache
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
Diagnostics	Diagnostics	HookOrderError, warn, is_dev, report_error
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.