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, hosts) 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 HomeScreen() -> pn.Node:
    return pn.Text("Hello from PythonNative")


Root = pn.StackNavigator(HomeScreen)


@pn.component
def App() -> pn.Node:
    return pn.NavigationContainer(Root)

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). Python owns the logical component tree and reconciliation on a dedicated asyncio application thread. Versioned commits cross into Swift PythonNativeKit on iOS and the Kotlin pythonnative module on Android. Those renderers own widgets, Yoga layout, measurement, gestures, and animation frames on the platform UI thread. The browser preview uses DOM widgets and Yoga WebAssembly.

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: screens are components whose parameters are their route params, listed in module-level StackNavigator, TabNavigator, or DrawerNavigator values and rendered by NavigationContainer. nav.push(ItemScreen(id=42)) is checked by the type checker.
• Styling uses a style dict per element (or a list of dicts), typed by the Style TypedDict. StyleSheet namespaces group named styles, and one Theme styles the app and its navigators.
• State lives in hooks for a component and in a typed Store for the app.
• Animations use the Animated namespace. Serialized graphs connect values, arithmetic, interpolation, and style bindings. Native timing, spring, decay, scroll, and gesture drivers update supported bindings without Python work on every frame.
• 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 and declare the component with define_component, which returns its element factory (or expose it from a PyPI package via the pythonnative.handlers entry-point group).

Example

import pythonnative as pn

@pn.component
def App() -> pn.Node:
    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(gap=12),
    )

Where to look next

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

Area	Page	Key symbols
Component model	Component	component, Component, memo, Node, Element.with_key
Element factories	Components	Text, Button, Column, Row, ScrollView, FlatList, SectionList, Modal, Pressable, PressState, Ripple, StatusBar, KeyboardAvoidingView, RefreshControl, Picker, Fragment, Portal, ErrorBoundary
Shared props	Components	AccessibilityProps, ViewProps
Typed event payloads	Components	LayoutEvent, ScrollEvent, SelectionEvent, KeyPressEvent, ContentSizeEvent, ImageLoadEvent, WebNavigationEvent
Imperative handles	Handles	ViewHandle, TextInputHandle, ScrollViewHandle, WebViewHandle, ScrollOffset, ListController
Hooks	Hooks	use_state, use_reducer, use_effect (with Deps), 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 (a ColorScheme), use_resource, use_transition, use_deferred_value, create_context
Suspense	Suspense	Suspense, Resource, start_resource, lazy
Animations	Animated	Animated, AnimatedValue, use_animated_value, Easing, EasingSpec, AnimationResult, ANIMATABLE_PROPS
Gestures	Gestures	Tap, LongPress, Pan, Swipe, Fling, Pinch, Rotation, GestureEvent, SwipeDirection
System dialogs	Alerts	Alert
Platform	Platform	Platform
Navigation	Navigation	NavigationContainer, StackNavigator, TabNavigator, DrawerNavigator, Screen, Group, ScreenOptions, TabBarStyle, Navigation, NavigationRef, use_navigation, use_screen_options, use_route, use_is_focused, use_focus_effect, LinkTable
Testing	Testing	render, render_hook, within, wait_for, fake_clock, FakeBackend, FakeHost
Styling	Style	Style, style, StyleProp, StyleSheet, ABSOLUTE_FILL, resolve_style, Color, DynamicColor, TransformSpec
Theming	Theme	Theme, Colors, Typography, Spacing, Radii, LIGHT_THEME, DARK_THEME, ThemeProvider, use_theme, use_styles
App state	Store	Store, use_store
Appearance	Appearance	use_color_scheme, appearance.set_color_scheme, appearance.get_color_scheme
Images	Images	Image, ImageBackground
Element descriptor	Element	Element
Screen host	Hosts	create_screen, ScreenHost
Reconciler	Reconciler	Reconciler
Native modules	Native modules	Camera, Location, FileSystem, Notifications, Keyboard, Dimensions, PixelRatio, Device, Localization, AccessibilityInfo, use_locales, use_screen_reader_enabled, use_reduce_motion
Native views	Native views	get_backend, set_backend, BridgeBackend
Mutation ops	Mutation ops	CreateOp, UpdateOp, InsertOp, DestroyOp
Event routing	Events	EventRegistry, dispatch_event, extract_events
Platform metrics	Platform metrics	SafeAreaInsets, WindowDimensions, subscribe
Dev server	Dev server	DevServer, DevClient, WebTransport
Hot reload	Hot reload	apply_reload, ModuleReloader
Diagnostics	Diagnostics	HookOrderError, warn, is_dev, report_error
Custom components SDK	SDK	Props, define_component, element_factory
Utilities	Utilities	IS_ANDROID, IS_IOS, IS_WEB
CLI	CLI (pn)	pn init, pn run, pn clean, and more in the CLI reference

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.