develop

Native modules

Device features such as the camera, files and secure storage come as separate pip packages. Only the modules you list are compiled into your app.

Use a module

Install the package, then add its name to modules in your app config.

terminal

pip install pyxpo-secure-store

pyproject.toml

[tool.pyxpo]
modules = ["secure-store"]

python

import pyxpo_secure_store as SecureStore

async def save_token(token):
    await SecureStore.set_item_async("token", token)

async def load_token():
    return await SecureStore.get_item_async("token")

Adding or removing a module changes the native app, so run pyxpo run or pyxpo build again. Hot reload alone is not enough. If you call a module that is not listed, pyxpo raises ModuleNotLinkedError and tells you what to add.

Official modules

Package	modules entry	What it does
`pyxpo-storage`	`storage`	Fast key-value storage for settings and small app data, with hooks that re-render on change.
`pyxpo-secure-store`	`secure-store`	Keep tokens and secrets encrypted in the iOS Keychain and Android Keystore, with optional biometrics.
`pyxpo-file-system`	`file-system`	Read, write, copy and download files in the app's document and cache folders.
`pyxpo-sqlite`	`sqlite`	Real SQLite databases with expo-sqlite's API: dict rows, transactions, prepared statements and a provider.
`pyxpo-image-picker`	`image-picker`	Pick photos and videos from the library, or take new ones with the camera.
`pyxpo-image-manipulator`	`image-manipulator`	Resize, crop, rotate, flip, compress and convert images on the device.
`pyxpo-media-library`	`media-library`	Save photos and videos to the device gallery, with permission helpers.
`pyxpo-camera`	`camera`	A CameraView component for photos, videos and live barcode and QR scanning.
`pyxpo-audio`	`audio`	Play sounds from files and URLs with play, pause, seek, loop and volume, and a hook for components.
`pyxpo-drawing-canvas`	`drawing-canvas`	A finger and pen drawing view with undo, redo, clear and PNG or JPEG export.
`pyxpo-whiteboard`	`whiteboard`	A full whiteboard: pen, marker, eraser, fill, nine shapes, page patterns, undo, a ready toolbar and export.
`pyxpo-mesh-view`	`mesh-view`	Play a picture bent by a triangle mesh frame by frame on the GPU, and export it to MP4 or GIF.
`pyxpo-sharing`	`sharing`	Open the native share sheet for files, images, links and text.
`pyxpo-application`	`application`	The installed app's name, id, version, build number, install time and signing details.
`pyxpo-device`	`device`	Brand, model, OS, memory, phone or tablet, uptime and Android system features.
`pyxpo-haptics`	`haptics`	Taps, success and error buzzes, selection ticks and the Android system haptics.
`pyxpo-localization`	`localization`	The user's languages, region, currency, number separators, time zone and clock style.
`pyxpo-network`	`network`	Connection type, online or offline, internet reachability, IP address and live changes.
`pyxpo-location`	`location`	Current and live position, compass heading, geocoding both ways and permission hooks.
`pyxpo-fetch`	`fetch`	HTTP requests with the web fetch API: streaming bodies, abort, timeouts, redirects and cookies.
`pyxpo-web-browser`	`web-browser`	In-app browser with a colored toolbar, OAuth sign-in sessions and Custom Tabs warm-up.
`pyxpo-dot-env`	`dot-env`	.env files per build mode, typed getters, and a build that stops when a secret would ship.
`pyxpo-notifications`	`notifications`	Local notifications, schedules, taps, Android channels and remote push through APNs and FCM.
`pyxpo-google-mobile-ads`	`google-mobile-ads`	AdMob banner, native, interstitial, rewarded and app open ads, with consent and settings for apps for children.

Write your own module

A module is a normal pip package with three parts:

Python code that your app imports.
A pyxpo-module.json file that names the module and its native class.
Optional native sources: ios/*.swift, android/src/main/** and web.js for the browser and the desktop window.

pyproject.toml (of the module)

[project]
name = "pyxpo-haptics"

[project.entry-points."pyxpo.modules"]
haptics = "pyxpo_haptics"

pyxpo_haptics/pyxpo-module.json

{
  "schemaVersion": 1,
  "nativeContract": 1,
  "name": "haptics",
  "native": "Haptics"
}

The Python side calls the native class through pyxpo.module_api, which also has helpers for platform checks and events. pyxpo.module_testing lets you test a module without a device.

Views and calls on the web

A module that ships a web.js next to its pyxpo-module.json also runs in the web build and the desktop window. The page loads the file after its own script. Register a view type for native_view and a handler for call:

pyxpo_thing/web.js

(function () {
  pyxpoPage.defineView("PxThing", (el, emit) => {
    // el is the element the layout engine sizes. emit(name, value) calls on_<name> in Python.
    return {
      update(props, removed) { /* every prop except style; the first update has them all */ },
      dispose() {},
    };
  });

  pyxpoPage.defineModule("Thing", (method, args, page) => {
    const view = page.view(args[0]);   // the view instance for a view_tag
    return view.doSomething(args[1]);  // a value or a Promise
  });
})();

Add web.js to the package data in pyproject.toml. A module with no web.js renders its views as an empty View on the web. See pyxpo-drawing-canvas for a full example.