GitHub Viewer
# PythonNative
PythonNative is a cross-platform toolkit for building native **Android**
and **iOS** apps in plain Python. The component model is React-style
(function components plus hooks plus a reconciler); rendering and
device APIs are native Swift and Kotlin, driven over a small bridge
with one transaction per commit. Application components run in Python.
## A taste
```python
import pythonnative as pn
@pn.component
def Counter(initial: int = 0):
count, set_count = pn.use_state(initial)
return pn.Column(
pn.Text(f"Count: {count}", style=pn.style(font_size=24, bold=True)),
pn.Button("+", on_press=lambda: set_count(count + 1)),
style=pn.style(spacing=12, padding=16),
)
```
That same `Counter` mounts as a `UILabel` plus a `UIButton` inside a
`UIView` on iOS, and as a `TextView` plus a `Button` inside a
`FrameLayout` on Android. The shared Yoga layout engine interprets
`flex`, `padding`, and `position` beside the native widgets.
Platform controls and fonts supply their own intrinsic sizes.
## Why PythonNative?
- **Real native widgets.** UIKit and Android controls provide platform
behavior. Configure accessibility labels and roles, and test navigation
and interaction on each platform.
- **A familiar component model**. If you know React or React Native,
you already know how PythonNative works.
- **Python application code.** Components run on a dedicated asyncio
application thread. Validated commits connect Python state to native widgets.
- **Ordinary asyncio.** One standard application loop runs Python work
independently of the native UI thread. Components can be `async def` and await data right in
the body, with [`Suspense`][pythonnative.Suspense] providing the
loading state declaratively. See the
[Async + data guide](guides/async.md).
- **Typed styling.** [`pn.Style`][pythonnative.style.Style] is a
`TypedDict` with `Literal` enums for every fixed-value field, so
mypy and your editor catch typos in `align_items` or
`font_weight` before the app ever runs. The
[`pn.style(...)`][pythonnative.style.style] helper makes the
call sites tidy.
- **Native-backed navigation.** The root `Stack.Navigator` drives
the platform's real navigation controller (Android Navigation
Component fragments on Android, `UINavigationController` on iOS),
so transitions, back gestures, and state preservation are exactly
what users expect from a first-class native app.
- **A Metro-style dev loop.** `pn start` runs one dev server for the
browser preview and every connected debug build. Save a file and
each client Fast Refreshes in place, preserving component state;
their logs stream back into the same terminal. See the
[Development workflow](guides/dev-workflow.md).
- **Dev-mode diagnostics.** Uncaught errors show a full-screen RedBox
with the traceback instead of crashing; typos in style keys and
duplicate list keys print "did you mean" warnings; conditional
hooks raise at the source. Every check is skipped in production.
- **Browser preview.** `pn preview` renders your app in a browser tab
inside a phone frame, through the same bridge protocol the Swift and
Kotlin runtimes speak, so you can iterate on UI, state, and
navigation in milliseconds (no simulator boot required). See the
[Browser preview guide](guides/browser-preview.md).
- **An extension SDK.** [`pythonnative.sdk`](api/sdk.md) lets you
wrap any platform widget as a first-class element with
type-checked props, and PyPI plugins auto-register through the
`pythonnative.handlers` entry-point group.
- **A small surface.** A handful of element factories, a handful of
hooks, and one navigation primitive.
## Quick links
- New here? Start with [Getting started](getting-started.md).
- Want to see it run right now? Try the
[Browser preview](guides/browser-preview.md).
- Want the bigger picture? Read [Mental model](concepts/mental-model.md).
- Looking up an API? [Package overview](api/pythonnative.md).
- Wrapping a custom widget? Read
[Custom native components](guides/custom-native-components.md).
- Stuck on an error? Try [Troubleshooting](meta/troubleshooting.md).
## Project status
PythonNative is under active development. The public API documented
on this site is the supported surface; expect breaking changes only at
minor version bumps until 1.0. See the
[Changelog](meta/changelog.md) for what shipped in each release.
## Get involved
- Source code:
[github.com/pythonnative/pythonnative](https://github.com/pythonnative/pythonnative).
- File a bug or feature request:
[GitHub issues](https://github.com/pythonnative/pythonnative/issues).
- Contribute: [Contributing](meta/contributing.md).
## Next steps
- Install and scaffold your first project: [Getting started](getting-started.md).
- Learn how the runtime fits together: [Architecture](concepts/architecture.md).