Native modules

See More

Cross-platform wrappers around device APIs that are not part of the view tree: camera and photo gallery, GPS, app-scoped file I/O, and local notifications. Each module is implemented twice (once per platform) and dispatches at runtime based on the IS_ANDROID and IS_IOS flags from pythonnative.utils.

Apart from FileSystem, every public method is a coroutine: await Camera.take_photo(), await Location.get_current(), and so on. For the call-site patterns and the runtime they're scheduled on, see the Async + data guide.

Camera

Cross-platform camera and gallery access.

Both entry points are coroutines: await Camera.take_photo() returns the saved image path (a str) or None if the user cancels. Internally each call instantiates a fresh native delegate / activity request and bridges its completion onto the PythonNative asyncio runtime, so callers don't have to know whether the picker is backed by UIImagePickerController (iOS) or Intent(MediaStore.ACTION_IMAGE_CAPTURE) (Android).

Example

import pythonnative as pn

async def add_photo():
    path = await pn.Camera.take_photo()
    if path is None:
        return  # user cancelled
    await save_to_album(path)

Classes:

Name	Description
Camera	Camera and image-picker interface.

Functions:

Name	Description
deliver_android_activity_result	Forward an Activity result to the registered camera coroutine.

Camera

Camera and image-picker interface.

All methods are static coroutines. They dispatch to the iOS or Android implementation at call time based on the runtime platform.

Methods:

Name	Description
take_photo	Launch the device camera to capture a photo.
pick_from_gallery	Open the system gallery picker.

take_photo async staticmethod

take_photo(**options: Any) -> Optional[str]

Launch the device camera to capture a photo.

Parameters:

Name	Type	Description	Default
**options	Any	Reserved for platform-specific tuning. Currently unused; future kwargs (e.g., quality, flash_mode) will land here.	{}

Returns:

Type	Description
Optional[str]	The saved image path, or None if the user cancelled or
Optional[str]	no camera is available.

pick_from_gallery async staticmethod

pick_from_gallery(**options: Any) -> Optional[str]

Open the system gallery picker.

Parameters:

Name	Type	Description	Default
**options	Any	Reserved for platform-specific tuning.	{}

Returns:

Type	Description
Optional[str]	The selected image path, or None if the user cancelled.

deliver_android_activity_result

deliver_android_activity_result(request_code: int, result_code: int, data: Any) -> bool

Forward an Activity result to the registered camera coroutine.

The host Activity should call this from onActivityResult so the pending take_photo / pick_from_gallery awaitable receives a path. Returns True if a Python callback was invoked (so the host can short-circuit further handlers).

Location

Cross-platform location / GPS access.

Location.get_current is a coroutine that resolves to a (latitude, longitude) tuple, or None if no recent fix is available or the user denies permission.

Permission prompts are triggered the first time a location-using API is called; ensure the appropriate manifest entries (android.permission.ACCESS_FINE_LOCATION) and Info.plist keys (NSLocationWhenInUseUsageDescription) are present.

Example

import pythonnative as pn

async def show_position():
    coords = await pn.Location.get_current()
    if coords is None:
        return
    lat, lon = coords
    print(f"You are at {lat:.5f}, {lon:.5f}")

Classes:

Name	Description
Location	GPS / location-services interface.

Location

GPS / location-services interface.

Methods:

Name	Description
get_current	Request the device's current location.

get_current async staticmethod

get_current(**options: Any) -> Optional[Coords]

Request the device's current location.

Parameters:

Name	Type	Description	Default
**options	Any	Reserved for platform-specific tuning (e.g., accuracy, timeout).	{}

Returns:

Type	Description
Optional[Coords]	(latitude, longitude) if a fix was obtained, otherwise
Optional[Coords]	None.

File system

Cross-platform app-scoped file I/O.

Provides static helpers for reading, writing, and deleting files in the app's sandboxed storage area. Relative paths are resolved against FileSystem.app_dir; absolute paths are used as-is.

Example

from pythonnative import FileSystem

FileSystem.write_text("notes/today.txt", "Hello, file system!")
print(FileSystem.read_text("notes/today.txt"))

Classes:

Name	Description
FileSystem	App-scoped file I/O.

FileSystem

App-scoped file I/O.

Every instance method operates on either an absolute path or a path relative to app_dir. Errors are swallowed and reported as falsy return values (None for readers, False for writers) so callers can treat the API as best-effort.

Methods:

Name	Description
app_dir	Return the app's writable data directory.
read_text	Read a text file.
write_text	Write a text file, creating parent directories as needed.
exists	Return whether a file or directory exists.
delete	Delete a single file.
list_dir	List the entries in a directory.
read_bytes	Read a binary file.
write_bytes	Write a binary file, creating parent directories as needed.
get_size	Return file size in bytes.
ensure_dir	Create a directory (and any missing parents) idempotently.
join	Join path components using the OS separator.

app_dir staticmethod

app_dir() -> str

Return the app's writable data directory.

On Android the result is Context.getFilesDir(). On iOS it is the user's Documents directory. On a desktop machine without either runtime, a .pythonnative_data directory is created under the user's home folder.

Returns:

Type	Description
str	Absolute path to the app's data directory.

read_text staticmethod

read_text(path: str, encoding: str = 'utf-8') -> Optional[str]

Read a text file.

Parameters:

Name	Type	Description	Default
path	str	Absolute path or path relative to app_dir.	required
encoding	str	Text encoding (default "utf-8").	'utf-8'

Returns:

Type	Description
Optional[str]	File contents as a str, or None if the file cannot be
Optional[str]	read.

write_text staticmethod

write_text(path: str, content: str, encoding: str = 'utf-8') -> bool

Write a text file, creating parent directories as needed.

Parameters:

Name	Type	Description	Default
path	str	Absolute or app_dir-relative path.	required
content	str	String to write.	required
encoding	str	Text encoding (default "utf-8").	'utf-8'

Returns:

Type	Description
bool	True on success, False on OSError.

exists staticmethod

exists(path: str) -> bool

Return whether a file or directory exists.

Parameters:

Name	Type	Description	Default
path	str	Absolute or app_dir-relative path.	required

Returns:

Type	Description
bool	True if the path exists.

delete staticmethod

delete(path: str) -> bool

Delete a single file.

Parameters:

Name	Type	Description	Default
path	str	Absolute or app_dir-relative path.	required

Returns:

Type	Description
bool	True on success, False on OSError.

list_dir staticmethod

list_dir(path: str = '') -> list

List the entries in a directory.

Parameters:

Name	Type	Description	Default
path	str	Absolute or app_dir-relative path. Defaults to the app data directory itself.	''

Returns:

Type	Description
list	A list of entry names, or an empty list on error.

read_bytes staticmethod

read_bytes(path: str) -> Optional[bytes]

Read a binary file.

Parameters:

Name	Type	Description	Default
path	str	Absolute or app_dir-relative path.	required

Returns:

Type	Description
Optional[bytes]	File contents as bytes, or None if the file cannot be
Optional[bytes]	read.

write_bytes staticmethod

write_bytes(path: str, data: bytes) -> bool

Write a binary file, creating parent directories as needed.

Parameters:

Name	Type	Description	Default
path	str	Absolute or app_dir-relative path.	required
data	bytes	Bytes to write.	required

Returns:

Type	Description
bool	True on success, False on OSError.

get_size staticmethod

get_size(path: str) -> Optional[int]

Return file size in bytes.

Parameters:

Name	Type	Description	Default
path	str	Absolute or app_dir-relative path.	required

Returns:

Type	Description
Optional[int]	File size in bytes, or None if the file is missing or
Optional[int]	unreadable.

ensure_dir staticmethod

ensure_dir(path: str) -> bool

Create a directory (and any missing parents) idempotently.

Parameters:

Name	Type	Description	Default
path	str	Absolute or app_dir-relative path.	required

Returns:

Type	Description
bool	True on success or if the directory already exists.

join staticmethod

join(*parts: Any) -> str

Join path components using the OS separator.

Equivalent to os.path.join(*map(str, parts)). Provided as a convenience so callers do not need to import os.path directly.

Parameters:

Name	Type	Description	Default
*parts	Any	Path components (each coerced to str).	()

Returns:

Type	Description
str	The joined path string.

Notifications

Cross-platform local notifications.

Provides coroutines for requesting permission and scheduling / cancelling local push notifications. Uses Android's NotificationManager or iOS's UNUserNotificationCenter.

On iOS you must await Notifications.request_permission() before scheduling. On Android 13+ the runtime permission should be requested through standard Android APIs (the manifest declaration is otherwise sufficient).

Example

import pythonnative as pn

async def setup_reminders():
    if not await pn.Notifications.request_permission():
        return
    await pn.Notifications.schedule(
        title="Reminder",
        body="Time for a walk!",
        delay_seconds=60,
        identifier="walk",
    )

Classes:

Name	Description
Notifications	Local notification interface.

Notifications

Local notification interface.

Methods:

Name	Description
request_permission	Request notification permission from the user.
schedule	Schedule a local notification.
cancel	Cancel a pending notification by its identifier.

request_permission async staticmethod

request_permission() -> bool

Request notification permission from the user.

On Android the manifest declaration is normally sufficient for legacy permission grants and this returns True without prompting (the runtime POST_NOTIFICATIONS prompt for Android 13+ should be requested via standard Android APIs).

Returns:

Type	Description
bool	True if granted (or no prompt is needed), False
bool	otherwise.

schedule async staticmethod

schedule(title: str, body: str = '', *, delay_seconds: float = 0, identifier: str = 'default', **options: Any) -> bool

Schedule a local notification.

Parameters:

Name	Type	Description	Default
title	str	Notification title.	required
body	str	Notification body text.	''
delay_seconds	float	Seconds from now until delivery. Use 0 for an effectively immediate notification.	0
identifier	str	Stable ID used by cancel to target this notification.	'default'
**options	Any	Reserved for future tuning (e.g., sound, badge, category).	{}

Returns:

Type	Description
bool	True on success, False if the underlying native
bool	call failed.

cancel async staticmethod

cancel(identifier: str = 'default') -> None

Cancel a pending notification by its identifier.

Parameters:

Name	Type	Description	Default
identifier	str	The same string passed to schedule.	'default'

Next steps

• See guidance and permission setup in Native modules guide.