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 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). 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 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. 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, 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
Component model	Component	component, Component, memo
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, use_resource, use_transition, use_deferred_value, create_context
Suspense	Suspense	Suspense, Resource, start_resource, lazy
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, Navigation, use_navigation, use_route, use_is_focused, LinkingConfig
Testing	Testing	render, render_hook, FakeBackend, FakeHost
Styling	Style	StyleSheet, Style, StyleProp, style, Theme, ThemeContext, use_theme
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
Native views	Native views	NativeViewRegistry, ViewHandler
Mutation ops	Mutation ops	CreateOp, UpdateOp, InsertOp, DestroyOp, SetFrameOp
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, ViewHandler, native_component, register_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.