Pickers

The pickers capability opens the system photo and document pickers. See the Pickers guide for setup and platform differences.

Let the user choose photos, videos, and documents with the system pickers.

Enable it in pythonnative.toml. The pickers themselves need no permission: the system shows them in its own process, and the app only gets what the user chose. Declare photo_library only if you also read the library directly.

[plugins]
use = ["pickers"]

Example

from pythonnative.pickers import pick_documents, pick_images

async def add_photos() -> None:
    for photo in await pick_images(limit=5):
        await upload(photo.path, photo.mime_type)

async def attach_pdf() -> None:
    files = await pick_documents(types=["application/pdf"])
    if files:
        print(files[0].name, files[0].size)

Classes:

Name	Description
PickedFile	One file the user chose, already copied somewhere the app can read.

Functions:

Name	Description
pick_images	Open the system photo picker.
pick_videos	Open the system photo picker, showing only videos.
pick_documents	Open the system document picker.

PickedFile dataclass

PickedFile(path: str, name: str, mime_type: str, size: int)

One file the user chose, already copied somewhere the app can read.

Attributes:

Name	Type	Description
path	str	The copy in the app's cache directory, which the system may clear when it runs low on space, so move what you want to keep. In the browser preview, this is a blob: URL.
name	str	The name the file had, for display.
mime_type	str	Its MIME type, or application/octet-stream when unknown.
size	int	Its size in bytes.

pick_images async

pick_images(
    limit: int = 1, quality: float = 0.9
) -> List[PickedFile]

Open the system photo picker.

Parameters:

Name	Type	Description	Default
limit	int	The most photos the user can choose, or 0 for as many as the system allows. iOS 13 can only ever choose one. Where Android falls back to the document picker, which can't enforce a number, extra choices are dropped.	1
quality	float	JPEG quality from 0 to 1. Below 1, photos are re-encoded as JPEG, which also turns HEIC into something every library can read. PNG and GIF keep their bytes, to preserve transparency and animation. At 1, every photo keeps its original bytes.	0.9

Returns:

Type	Description
List[PickedFile]	The chosen photos, in the order chosen. An empty list means the user
List[PickedFile]	canceled.

Raises:

Type	Description
NativeModuleError	With the code busy when a picker is already open.

pick_videos async

pick_videos(limit: int = 1) -> List[PickedFile]

Open the system photo picker, showing only videos.

Parameters:

Name	Type	Description	Default
limit	int	The most videos the user can choose, or 0 for as many as the system allows. iOS 13 can only ever choose one.	1

Returns:

Type	Description
List[PickedFile]	The chosen videos, with their original bytes. An empty list means the
List[PickedFile]	user canceled.

Raises:

Type	Description
NativeModuleError	With the code busy when a picker is already open.

pick_documents async

pick_documents(
    types: Optional[Sequence[str]] = None,
    multiple: bool = False,
) -> List[PickedFile]

Open the system document picker.

Parameters:

Name	Type	Description	Default
types	Optional[Sequence[str]]	The MIME types to offer, such as "application/pdf" or "image/*". None offers every file.	None
multiple	bool	Let the user choose more than one.	False

Returns:

Type	Description
List[PickedFile]	The chosen files. An empty list means the user canceled.

Raises:

Type	Description
NativeModuleError	With the code busy when a picker is already open.