Native views¶

The bridge between PythonNative's element tree and concrete native widgets. Every element type maps to a ViewHandler implementation in the NativeViewRegistry; the platform-specific handlers are registered lazily so importing pythonnative on the desktop never pulls in Chaquopy or rubicon-objc.

Platform-specific native-view creation and update logic.

This package provides the NativeViewRegistry that maps element type names (e.g., "Text", "Button") to platform-specific ViewHandler implementations. The reconciler calls the registry to create, update, and re-parent native views.

Platform handlers live in dedicated submodules:

pythonnative.native_views.base: shared ViewHandler protocol and utilities.
pythonnative.native_views.android: Android handlers (Chaquopy / Java bridge).
pythonnative.native_views.ios: iOS handlers (rubicon-objc).

All platform-branching is handled at registration time via lazy imports, so this package can be imported on any platform for testing. A mock registry can be installed via set_registry to drive the reconciler with no real native views.

Modules:

Name	Description
`android`	Android native-view handlers (Chaquopy / Java bridge).
`base`	Shared base classes and utilities for native-view handlers.
`ios`	iOS native-view handlers (rubicon-objc).

Classes:

Name	Description
`NativeViewRegistry`	Map element type names to platform-specific view handlers.

Functions:

Name	Description
`get_registry`	Return the process-wide registry, lazily registering handlers.
`set_registry`	Install a custom registry (primarily for testing).

NativeViewRegistry ¶

NativeViewRegistry()

Map element type names to platform-specific view handlers.

The reconciler depends only on this protocol: create_view, update_view, add_child, remove_child, insert_child. Implementations may be real (Android/iOS) or mocked for tests.

Methods:

Name	Description
`register`	Register `handler` to service elements of type `type_name`.
`create_view`	Create a native view for `type_name` and apply initial props.
`update_view`	Apply `changed_props` to an existing native view.
`add_child`	Append `child` to `parent`.
`remove_child`	Remove `child` from `parent`.
`insert_child`	Insert `child` into `parent` at `index`.

register ¶

register(type_name: str, handler: ViewHandler) -> None

Register handler to service elements of type type_name.

Parameters:

Name	Type	Description	Default
`type_name`	`str`	The element type name (e.g., `"Text"`).	required
`handler`	`ViewHandler`	A `ViewHandler` instance for the active platform.	required

create_view ¶

create_view(type_name: str, props: Dict[str, Any]) -> Any

Create a native view for type_name and apply initial props.

Parameters:

Name	Type	Description	Default
`type_name`	`str`	The element type name.	required
`props`	`Dict[str, Any]`	Initial props dict.	required

Returns:

Type	Description
`Any`	The platform-native view object.

Raises:

Type	Description
`ValueError`	If no handler is registered for `type_name`.

update_view ¶

update_view(native_view: Any, type_name: str, changed_props: Dict[str, Any]) -> None

Apply changed_props to an existing native view.

Silently ignored if no handler is registered for type_name.

Parameters:

Name	Type	Description	Default
`native_view`	`Any`	The platform-native view.	required
`type_name`	`str`	The element type name.	required
`changed_props`	`Dict[str, Any]`	A dict containing only props whose values changed since the previous render. Removed props are signaled with a value of `None`.	required

add_child ¶

add_child(parent: Any, child: Any, parent_type: str) -> None

Append child to parent.

Parameters:

Name	Type	Description	Default
`parent`	`Any`	Parent native view.	required
`child`	`Any`	Native view to append.	required
`parent_type`	`str`	Element type of the parent (for handler lookup).	required

remove_child ¶

remove_child(parent: Any, child: Any, parent_type: str) -> None

Remove child from parent.

Parameters:

Name	Type	Description	Default
`parent`	`Any`	Parent native view.	required
`child`	`Any`	Child native view to remove.	required
`parent_type`	`str`	Element type of the parent.	required

insert_child ¶

insert_child(parent: Any, child: Any, parent_type: str, index: int) -> None

Insert child into parent at index.

Parameters:

Name	Type	Description	Default
`parent`	`Any`	Parent native view.	required
`child`	`Any`	Child native view to insert.	required
`parent_type`	`str`	Element type of the parent.	required
`index`	`int`	Zero-based insertion position among `parent`'s existing children.	required

get_registry ¶

get_registry() -> NativeViewRegistry

Return the process-wide registry, lazily registering handlers.

The first call instantiates the registry and registers either the Android or iOS handlers based on IS_ANDROID. Subsequent calls return the same instance.

Returns:

Type	Description
`NativeViewRegistry`	The active `NativeViewRegistry`.

set_registry ¶

set_registry(registry: NativeViewRegistry) -> None

Install a custom registry (primarily for testing).

Replaces the lazy singleton so subsequent get_registry calls return registry. Pass a mock to drive the reconciler from unit tests without touching real native APIs.

Parameters:

Name	Type	Description	Default
`registry`	`NativeViewRegistry`	The replacement registry.	required

Base classes¶

Shared base classes and utilities for native-view handlers.

Provides the ViewHandler protocol implemented by Android and iOS handlers, plus common helpers for color parsing, padding normalization, and flex-layout constants shared across platforms.

Classes:

Name	Description
`ViewHandler`	Protocol implemented by every native-view handler.

Functions:

Name	Description
`parse_color_int`	Parse a color value into a signed 32-bit ARGB int.
`resolve_padding`	Normalize a padding value to `(left, top, right, bottom)`.
`is_vertical`	Return whether `direction` represents a vertical (column) axis.

ViewHandler ¶

Protocol implemented by every native-view handler.

A ViewHandler knows how to create, update, and re-parent native views of one element type. The reconciler dispatches through the NativeViewRegistry; handlers never need to know about Element or VNode.

Subclasses must override create and update. Container handlers override the child-management methods; leaf handlers can leave them as no-ops.

Methods:

Name	Description
`create`	Create a fresh native view and apply initial props.
`update`	Apply only the props that changed since the last render.
`add_child`	Append `child` to `parent`. No-op for leaf handlers.
`remove_child`	Remove `child` from `parent`. No-op for leaf handlers.
`insert_child`	Insert `child` at `index`. Defaults to appending.

create ¶

create(props: Dict[str, Any]) -> Any

Create a fresh native view and apply initial props.

Parameters:

Name	Type	Description	Default
`props`	`Dict[str, Any]`	Initial props dict.	required

Returns:

Type	Description
`Any`	The platform-native view object.

Raises:

Type	Description
`NotImplementedError`	Subclasses must override.

update ¶

update(native_view: Any, changed_props: Dict[str, Any]) -> None

Apply only the props that changed since the last render.

Parameters:

Name	Type	Description	Default
`native_view`	`Any`	The platform-native view to mutate.	required
`changed_props`	`Dict[str, Any]`	Props whose values changed (a value of `None` indicates the prop was removed).	required

Raises:

Type	Description
`NotImplementedError`	Subclasses must override.

add_child ¶

add_child(parent: Any, child: Any) -> None

Append child to parent. No-op for leaf handlers.

remove_child ¶

remove_child(parent: Any, child: Any) -> None

Remove child from parent. No-op for leaf handlers.

insert_child ¶

insert_child(parent: Any, child: Any, index: int) -> None

Insert child at index. Defaults to appending.

parse_color_int ¶

parse_color_int(color: Union[str, int]) -> int

Parse a color value into a signed 32-bit ARGB int.

Accepts "#RRGGBB", "#AARRGGBB", or a raw integer. Java APIs such as setBackgroundColor expect a signed 32-bit int, so values with a high alpha byte (e.g., 0xFF......) must be converted to their negative two's-complement equivalent.

Parameters:

Name	Type	Description	Default
`color`	`Union[str, int]`	Hex string (with or without leading `#`) or an int.	required

Returns:

Type	Description
`int`	Signed 32-bit ARGB int suitable for Android's color APIs.

resolve_padding ¶

resolve_padding(padding: Any) -> tuple

Normalize a padding value to (left, top, right, bottom).

Accepts:

None: returns (0, 0, 0, 0).
A scalar int/float: same value on all sides.
A dict with any of horizontal, vertical, left, right, top, bottom, all keys.

Parameters:

Name	Type	Description	Default
`padding`	`Any`	One of the forms above.	required

Returns:

Type	Description
`tuple`	A 4-tuple of `(left, top, right, bottom)` ints.

is_vertical ¶

is_vertical(direction: str) -> bool

Return whether direction represents a vertical (column) axis.

Platform handlers

The Android and iOS handler implementations live in pythonnative.native_views.android and pythonnative.native_views.ios respectively. They are imported only at runtime on the corresponding platform; we don't render their API tables here because they're internal to the runtime and require platform-only dependencies (Chaquopy / rubicon-objc) to be importable for mkdocstrings to introspect them.

Next steps¶

Read the high-level model in Native views (concept).
See how the reconciler drives handlers in Reconciler.