Skip to content

pythonnative package

Public API

create_page

pythonnative.create_page(...) — called internally by native templates to bootstrap the root component. You don't call this directly.

Element functions

  • pythonnative.Text, Button, Column, Row, ScrollView, TextInput, Image, Switch, ProgressBar, ActivityIndicator, WebView, Spacer
  • pythonnative.View, SafeAreaView, Modal, Slider, Pressable, FlatList

Each returns an Element descriptor. Visual and layout properties are passed via style={...}. See the Component Property Reference for full details.

ErrorBoundary

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.

Element

pythonnative.Element — the descriptor type returned by element functions. You generally don't create these directly.

Hooks

Function component primitives:

  • pythonnative.component — decorator to create a function component
  • pythonnative.use_state(initial) — local component state
  • pythonnative.use_reducer(reducer, initial_state) — reducer-based state management; returns (state, dispatch)
  • pythonnative.use_effect(effect, deps) — side effects, run after native commit
  • pythonnative.use_navigation() — navigation handle (navigate/go_back/get_params)
  • pythonnative.use_route() — convenience hook for current route params
  • pythonnative.use_focus_effect(effect, deps) — like use_effect but only runs when the screen is focused
  • pythonnative.use_memo(factory, deps) — memoised values
  • pythonnative.use_callback(fn, deps) — stable function references
  • pythonnative.use_ref(initial) — mutable ref object
  • pythonnative.use_context(context) — read from context
  • pythonnative.create_context(default) — create a new context
  • pythonnative.Provider(context, value, child) — provide a context value

Declarative, component-based navigation system:

  • pythonnative.NavigationContainer(child) — root container for the navigation tree
  • pythonnative.create_stack_navigator() — create a stack-based navigator (returns object with .Navigator and .Screen)
  • pythonnative.create_tab_navigator() — create a tab-based navigator
  • pythonnative.create_drawer_navigator() — create a drawer-based navigator

Batching

  • pythonnative.batch_updates() — context manager that batches multiple state updates into a single re-render

Styling

  • pythonnative.StyleSheet — utility for creating and composing style dicts
  • pythonnative.ThemeContext — built-in theme context (defaults to light theme)

Native API modules

  • pythonnative.native_modules.Camera — photo capture and gallery picking
  • pythonnative.native_modules.Location — GPS / location services
  • pythonnative.native_modules.FileSystem — app-scoped file I/O
  • pythonnative.native_modules.Notifications — local push notifications

Internal helpers

  • pythonnative.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.

Reconciler

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.

Hot reload

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.

Native view registry

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)