Native modules¶

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.

Native API modules for device capabilities.

Provides cross-platform Python interfaces to common device APIs:

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

Each module auto-detects the platform at import time and dispatches to the appropriate native APIs via Chaquopy (Android) or rubicon-objc (iOS). On a desktop machine without either runtime, the modules raise informative RuntimeError instances when called.

Modules:

Name	Description
`camera`	Cross-platform camera and gallery access.
`file_system`	Cross-platform app-scoped file I/O.
`location`	Cross-platform location / GPS access.
`notifications`	Cross-platform local notifications.

Classes:

Name	Description
`Camera`	Camera and image-picker interface.
`FileSystem`	App-scoped file I/O.
`Location`	GPS / location-services interface.
`Notifications`	Local notification interface.

Camera ¶

Camera and image-picker interface.

All methods are static. They dispatch to the Android or iOS implementation at call time based on IS_ANDROID (from pythonnative.utils).

Methods:

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

take_photo `staticmethod` ¶

take_photo(on_result: Optional[Callable[[Optional[str]], None]] = None, **options: Any) -> None

Launch the device camera to capture a photo.

Parameters:

Name	Type	Description	Default
`on_result`	`Optional[Callable[[Optional[str]], None]]`	Callable invoked with the saved image path, or `None` if the user cancelled.	`None`
`**options`	`Any`	Reserved for platform-specific tuning. Currently unused; future kwargs (e.g., `quality`, `flash_mode`) will land here.	`{}`

pick_from_gallery `staticmethod` ¶

pick_from_gallery(on_result: Optional[Callable[[Optional[str]], None]] = None, **options: Any) -> None

Open the system gallery picker.

Parameters:

Name	Type	Description	Default
`on_result`	`Optional[Callable[[Optional[str]], None]]`	Callable invoked with the selected image path, or `None` if the user cancelled.	`None`
`**options`	`Any`	Reserved for platform-specific tuning.	`{}`

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.

Location ¶

GPS / location-services interface.

All methods are static and dispatch to the correct platform implementation at call time.

Methods:

Name	Description
`get_current`	Request the device's current location.

get_current `staticmethod` ¶

get_current(on_result: Optional[Callable[[Optional[Tuple[float, float]]], None]] = None, **options: Any) -> None

Request the device's current location.

Parameters:

Name	Type	Description	Default
`on_result`	`Optional[Callable[[Optional[Tuple[float, float]]], None]]`	Callable invoked with `(latitude, longitude)` tuples, or `None` if no recent fix is available or the user denies permission.	`None`
`**options`	`Any`	Reserved for platform-specific tuning (e.g., `accuracy`, `timeout`).	`{}`

Notifications ¶

Local notification interface.

All methods are static and dispatch to the correct platform implementation at call time.

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 `staticmethod` ¶

request_permission(on_result: Optional[Callable[[bool], None]] = None) -> None

Request notification permission from the user.

On Android, the manifest declaration is normally sufficient for legacy permission grants and this method calls back with True without prompting.

Parameters:

Name	Type	Description	Default
`on_result`	`Optional[Callable[[bool], None]]`	Callable invoked with `True` if the user accepted, `False` if they declined or the prompt failed.	`None`

schedule `staticmethod` ¶

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

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`).	`{}`

cancel `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'`

Camera¶

Cross-platform camera and gallery access.

Provides static methods for capturing a photo or picking an image from the device gallery. The platform implementation is selected at call time and uses Android's Intent/MediaStore APIs or iOS's UIImagePickerController.

All methods accept an on_result callback that receives either the saved image path (a str) or None if the user cancels.

Example

from pythonnative import Camera

def handle(path):
    print("Photo saved to" if path else "Cancelled", path)

Camera.take_photo(on_result=handle)

Classes:

Name	Description
`Camera`	Camera and image-picker interface.

Camera ¶

Camera and image-picker interface.

All methods are static. They dispatch to the Android or iOS implementation at call time based on IS_ANDROID (from pythonnative.utils).

Methods:

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

take_photo `staticmethod` ¶

take_photo(on_result: Optional[Callable[[Optional[str]], None]] = None, **options: Any) -> None

Launch the device camera to capture a photo.

Parameters:

Name	Type	Description	Default
`on_result`	`Optional[Callable[[Optional[str]], None]]`	Callable invoked with the saved image path, or `None` if the user cancelled.	`None`
`**options`	`Any`	Reserved for platform-specific tuning. Currently unused; future kwargs (e.g., `quality`, `flash_mode`) will land here.	`{}`

pick_from_gallery `staticmethod` ¶

pick_from_gallery(on_result: Optional[Callable[[Optional[str]], None]] = None, **options: Any) -> None

Open the system gallery picker.

Parameters:

Name	Type	Description	Default
`on_result`	`Optional[Callable[[Optional[str]], None]]`	Callable invoked with the selected image path, or `None` if the user cancelled.	`None`
`**options`	`Any`	Reserved for platform-specific tuning.	`{}`

Location¶

Cross-platform location / GPS access.

Provides static methods for requesting the device's current coordinates. Uses Android's LocationManager or iOS's CLLocationManager. Permission prompts are triggered by the system 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

from pythonnative import Location

def handle(coords):
    if coords is None:
        print("Location unavailable")
    else:
        lat, lon = coords
        print(f"You are at {lat:.5f}, {lon:.5f}")

Location.get_current(on_result=handle)

Classes:

Name	Description
`Location`	GPS / location-services interface.

Location ¶

GPS / location-services interface.

All methods are static and dispatch to the correct platform implementation at call time.

Methods:

Name	Description
`get_current`	Request the device's current location.

get_current `staticmethod` ¶

get_current(on_result: Optional[Callable[[Optional[Tuple[float, float]]], None]] = None, **options: Any) -> None

Request the device's current location.

Parameters:

Name	Type	Description	Default
`on_result`	`Optional[Callable[[Optional[Tuple[float, float]]], None]]`	Callable invoked with `(latitude, longitude)` tuples, or `None` if no recent fix is available or the user denies permission.	`None`
`**options`	`Any`	Reserved for platform-specific tuning (e.g., `accuracy`, `timeout`).	`{}`

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 static methods for requesting permission, scheduling, and cancelling local push notifications. Uses Android's NotificationManager or iOS's UNUserNotificationCenter.

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

Example

from pythonnative import Notifications

Notifications.request_permission(lambda granted: print("granted=", granted))
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.

All methods are static and dispatch to the correct platform implementation at call time.

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 `staticmethod` ¶

request_permission(on_result: Optional[Callable[[bool], None]] = None) -> None

Request notification permission from the user.

On Android, the manifest declaration is normally sufficient for legacy permission grants and this method calls back with True without prompting.

Parameters:

Name	Type	Description	Default
`on_result`	`Optional[Callable[[bool], None]]`	Callable invoked with `True` if the user accepted, `False` if they declined or the prompt failed.	`None`

schedule `staticmethod` ¶

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

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`).	`{}`

cancel `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.

Native modules¶

Camera ¶

take_photo staticmethod ¶

pick_from_gallery staticmethod ¶

FileSystem ¶

app_dir staticmethod ¶

read_text staticmethod ¶

write_text staticmethod ¶

exists staticmethod ¶

delete staticmethod ¶

list_dir staticmethod ¶

read_bytes staticmethod ¶

write_bytes staticmethod ¶

get_size staticmethod ¶

ensure_dir staticmethod ¶

join staticmethod ¶

Location ¶

get_current staticmethod ¶

Notifications ¶

request_permission staticmethod ¶

schedule staticmethod ¶

cancel staticmethod ¶

Camera¶

Camera ¶

take_photo staticmethod ¶

pick_from_gallery staticmethod ¶

Location¶

Location ¶

get_current staticmethod ¶

File system¶

FileSystem ¶

app_dir staticmethod ¶

read_text staticmethod ¶

write_text staticmethod ¶

exists staticmethod ¶

delete staticmethod ¶

list_dir staticmethod ¶

read_bytes staticmethod ¶

write_bytes staticmethod ¶

get_size staticmethod ¶

ensure_dir staticmethod ¶

join staticmethod ¶

Notifications¶

Notifications ¶

request_permission staticmethod ¶

schedule staticmethod ¶

cancel staticmethod ¶

Next steps¶

take_photo `staticmethod` ¶

pick_from_gallery `staticmethod` ¶

app_dir `staticmethod` ¶

read_text `staticmethod` ¶

write_text `staticmethod` ¶

exists `staticmethod` ¶

delete `staticmethod` ¶

list_dir `staticmethod` ¶

read_bytes `staticmethod` ¶

write_bytes `staticmethod` ¶

get_size `staticmethod` ¶

ensure_dir `staticmethod` ¶

join `staticmethod` ¶

get_current `staticmethod` ¶

request_permission `staticmethod` ¶

schedule `staticmethod` ¶

cancel `staticmethod` ¶

take_photo `staticmethod` ¶

pick_from_gallery `staticmethod` ¶

get_current `staticmethod` ¶

app_dir `staticmethod` ¶

read_text `staticmethod` ¶

write_text `staticmethod` ¶

exists `staticmethod` ¶

delete `staticmethod` ¶

list_dir `staticmethod` ¶

read_bytes `staticmethod` ¶

write_bytes `staticmethod` ¶

get_size `staticmethod` ¶

ensure_dir `staticmethod` ¶

join `staticmethod` ¶

request_permission `staticmethod` ¶

schedule `staticmethod` ¶

cancel `staticmethod` ¶