Public API¶

This is the supported surface exported by apkpy_lib. Import individual names for clarity:

from apkpy_lib import Screen, Theme, button, label, run

New to the library? Start with the essential API reference. It groups the smallest stable surface needed for screens, components, state, feeds, data, networking and device integrations, then links here for the broader catalogue.

Browse by module¶

DATA CORETyped SQLite and migrations

Models, constraints, async CRUD, transactions and safe upgrades.

UIScreens, components and layout

Theme, navigation, overlays and responsive composition.

DATASETFeeds, state and lifecycle

Virtual rows, paging, mutations and reactive bindings.

MEDIAAudio, video, uploads and files

Background playback, Media3 and streamed transfer.

NETWORKHTTP, WebSocket, SQLite and crypto

Remote data, local persistence and protected values.

ANDROIDDevice integrations

Push, maps, location, camera, permissions and services.

CONTENTNative documents

Rich spans, Markdown and expandable trees.

This page remains a compact all-in-one index. The module pages are easier to scan and link to complete task guides.

App structure¶

API	Purpose
`Screen(id, background_image=None, scroll=False)`	Defines an Android screen/Activity
`run(start_screen=None, theme=None)`	Starts the Previewer and defines the app entry
`Theme(...)`	Supplies global design tokens and component defaults
`device(name)`	Selects a Previewer device preset or responsive mode
`declare_permissions(perms)`	Adds Android manifest permissions

Screen methods:

Method	Purpose
`get_param(key, default="")`	Reads a value passed during navigation
`on_click_navigate(button, to, data=None)`	Connects an existing button to a screen

Components¶

API	Important arguments
`label`	`text`, `id`, `variant`, `screen`, `parent`
`button`	`text`, `command`, `variant`, `icon`
`inputs` / `input_field`	`placeholder`, `type`, `on_change`
`image`	local path or HTTPS URL in `src`
`video`	Media3 video with poster, controls, callbacks, seek, speed and mute
`container`	composable parent surface
`card`	title, subtitle, image, content, actions and variant
`card_action`	detached action for semantic cards
`list_view`	items, click callback and optional rich rows
`virtual_collection`	virtualized list/grid with reusable template, `on_end_reached`, `on_refresh` and `prefetch`
`rich_text`	native inline spans with emphasis, colour, size, code and links
`markdown`	native structured text without a WebView
`tree_view`	expandable hierarchy backed by visible recycled rows
`carousel`	horizontal rich-item shelf
`grid`	rich-item grid with `cols`
`spinner`	circular loading indicator
`skeleton`	animated content placeholder
`empty_state`	empty result with optional action
`error_state`	error result with optional retry

Common component methods:

Method	Purpose
`get_value()`	Reads the current input/value
`set_value(value)`	Updates text, image or input state where supported
`show()` / `hide()`	Controls visibility
`set_items(items, has_more=True)`	Replaces collection content and completes an active refresh
`append_items(items, has_more=True)`	Appends a virtual-collection page without resetting its position
`prepend_items(items)`	Inserts records at the beginning while preserving the visible item
`update_item(item_id, changes, key="id", optimistic=False)`	Patches one keyed record and optionally stores a rollback snapshot
`remove_item(item_id, key="id", optimistic=False)`	Removes one keyed record and optionally stores a rollback snapshot
`merge_items(items, key="id")`	Updates matching records in place and appends new keys without duplicates
`rollback(mutation_id=None)`	Restores one optimistic transaction, or the latest pending transaction
`commit(mutation_id=None)`	Accepts one optimistic transaction and discards its snapshot
`finish_load(has_more=True)`	Releases a virtual collection after an empty or failed page
`refresh()`	Starts the guarded `on_refresh` flow manually

Reactive state and lifecycle¶

API	Purpose
`state(initial, id=None)`	Creates an observable value shared by Previewer and Android
`ReactiveState.bind(component, template="{value}")`	Updates a component value automatically
`ReactiveState.bind_visibility(component, when=True)`	Connects component visibility to a boolean state
`lifecycle(screen, on_mount=None, on_resume=None, on_pause=None, on_destroy=None)`	Scopes work to one screen lifecycle

State objects also expose get, set, increment, decrement and toggle.

Native documents¶

API	Signature and model
`rich_text(spans, id=None, screen=None, parent=None, selectable=True)`	Span keys: `text`, `bold`, `italic`, `underline`, `strike`, `code`, `color`, `size`, `link`
`markdown(source, id=None, screen=None, parent=None, selectable=True)`	Headings, emphasis, links, code, quotes, lists, checkboxes and dividers
`tree_view(nodes, id=None, screen=None, parent=None, expand_depth=1, row_height=58)`	Node keys: `title`, `subtitle`, `key`, `expanded`, recursive `children`

Android uses SpannableStringBuilder for text and a RecyclerView containing only visible tree rows. The helper classes are generated only when these APIs are present. See Native rich content for complete examples, data-model notes and Previewer/Android behavior.

Layout¶

API	Purpose
`row(*children)`	Describes a horizontal arrangement
`column(*children)`	Describes a vertical arrangement
`responsive(mobile, tablet=None, landscape=None, breakpoint=600, ...)`	Switches arrangements by viewport

API	Purpose
`on_click_navigate(screen, data=None)`	Navigates from a callback
`bottom_nav(screens, labels=None, icons=None)`	Adds top-level bottom navigation
`app_bar(...)`	Adds a fixed Material toolbar
`sliver_app_bar(...)`	Adds a collapsible image toolbar
`action(icon, ...)`	Creates an app-bar icon action
`mini_player(open=None)`	Adds the persistent audio mini-player

Overlays and feedback¶

API	Purpose
`bottom_sheet`	Selectable Material bottom sheet
`modal`	Confirm/cancel modal
`menu` / `popup_menu`	Anchored compact menu
`context_menu`	Right-click/long-press menu
`tooltip`	Accessible help attached to a component
`date_picker` / `time_picker`	Native date/time selection
`snackbar`	Transient message with optional action
`toast`	Brief platform message
`alert` / `confirm`	Native informational/confirmation dialogs

Overlay definitions returned by sheets, modals, menus and pickers expose open() and close().

Data and security¶

Object/helper	Methods
`storage`	`set`, `get`, `delete`, `clear`, `keys`
`crypto`	`hash_password`, `verify_password`, `encrypt`, `decrypt`
`db`	Typed models, schema, filters, migrations and transactions; legacy `execute`, `query`, `last_insert_id`, `begin`, `commit`, `rollback` remain available
`https`	`get`, `post`, `put`, `patch`, `delete`
`json_get(json_string, path)`	Reads a safe dotted JSON path
`random`	`randint`, `choice`, `random`
`datetime`	`now`, `date`, `time`, and numeric date/time parts

Typed database API (1.3.0–1.3.1)¶

Area	Calls
Field declarations	`integer`, `real`, `text`, `boolean`, `datetime`, `json`, `blob`, `now`
Schema	`model`, `index`, `relation`, `schema`
Model operations	`insert`, `insert_many`, `get(include=...)`, `find(include=...)`, `observe`, `update`, `delete`, `count`
Observer	`refresh`, `update_query`, `close`
Filters	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, `ends_with`, `in_`, `is_null`, `and_`, `or_`
Ordering	`asc`, `desc`
Migration	`migration`, `create_table`, `add_column`, `rename_column`, `create_index`, `rename_index`, `drop_index`, `rename_table`, `sql`

See Data Core for signatures, result types, examples and migration safety rules. See Reactive Data for relation aliases, batched includes, observer lifecycle and invalidation semantics.

Media, files and identity¶

Object/helper	Methods
`audio`	playback, background playback, seek, queue, controls, favourites and playlists
`uploads`	streaming multipart file, image, audio and video uploads with progress/cancel
`websocket`	persistent WS/WSS connections, send queue, reconnect and close
`files`	`download`, `path`, `exists`, `delete`, `pick` (any file type)
`upload_button`	one button that picks a file and uploads it
`auth`	`login`, `user`, `token`, `is_logged_in`, `logout`

Audio methods:

play, play_background, pause, resume, stop, seek, play_playlist, next, previous, shuffle, repeat, now_playing, controls, is_liked, toggle_like, like_button, liked_list, add_to_playlist, play_saved_playlist, playlists_list, edit_playlist, playlist_editor, remove_from_playlist and delete_playlist.

On Android, background playback is owned by a generated foreground service and native MediaSession. It supplies notification and lock-screen metadata and transport actions, audio-focus handling, buffering state and guarded player polling. This API currently describes normal source playback and explicit offline files; it does not promise automatic audio caching, adaptive quality or gapless transitions.

Device integrations¶

Object/API	Purpose
`permissions`	Runtime Android permission requests
`notify`	System notifications
`notifications`	Channels, permission checks/requests and cancellation; extended notification API — 1.7.0
`share`	Native share sheet
`clipboard`	System clipboard
`camera`	Native camera capture
`sensors`	Shake, compass, steps, light and proximity; accelerometer, gyroscope and pressure added in 1.7.0
`battery`	Percentage, charging and power-saver snapshots
`wallpaper`	Static wallpaper with image preview and confirmation; home/lock/both — 1.7.0
`flashlight`	The torch on the back -- on, off, toggle, and whether it is lit. No permission
`gallery`	Native media picker
`location`	Current position and city
`map_view`	OpenStreetMap tiles, markers, route, user layer and follow controls
`routes`	cancellable driving, walking or cycling route calculation
`push`	FCM listener, device token, topic subscription and Preview simulation
`service`	Periodic and one-shot background work
`background_job`	Persistent work queue with constraints, retries, cancellation and observable progress
`apps`	Installed-app listing, permissions, extraction and hashing

For behavior and security notes, use the topic guides rather than relying on this compact index alone.

See Notifications for the full notify() signature, copyable examples, zero-argument action callbacks, progress, pictures, the desktop drawer's controls and Android permission/lifecycle limits.

See Sensors and battery for exact callback signatures, units, permissions, complete examples and Previewer simulation limits. The three new sensor methods belong to the 1.7.0. The static wallpaper guide covers the new wallpaper.set() and wallpaper.available() APIs, with a complete gallery example.

The Version 1.2.1 guide documents feed pagination, prefetch, refresh, retry and generated Android behavior. The wider runtime is documented in the Version 1.2.0 guide.