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; on a text field help, error, required (True or the words to show), set_error(text), validate()
validate(a, b, ...)	checks every field given, shows the message of each empty required one, returns whether all passed
image	local path or HTTPS URL in src; command on a tap, or zoom=True to open it full screen with pinch zoom
view_image(src)	opens any picture full screen, where it can be pinched, double-tapped and dragged; describe= for a screen reader
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 or row= built from components, layout="grid"/columns, on_end_reached, on_refresh and prefetch; height: auto scrolls with its screen; swipe_right/swipe_left, reorder, on_reorder(item, index)
swipe	what a swiped row does: icon, text, on_swipe(item), color, keep=True (slide back), undo="message" (snackbar with Undo)
pager	tabs over pages that swipe; id, screen, parent; select(index)
tab	one page of a pager: text, icon, describe, parent= the pager
chart	kind="bar", "line" (fill=True), "donut" (center=) or "ring" (value, max); items read by x/y; on_click(item); set_items(), set_value()
chips	options that stay selected: options, selected, multiple=True (a list), on_change(value), icons, check=False, required=True (one always selected); chips wrap onto more lines
segmented	two to five segments in one pill, one always selected unless multiple=True; the same arguments as chips
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

Navigation and screen chrome

API	Purpose
on_click_navigate(screen, data=None)	Navigates from a callback
back()	Closes this screen and returns to the one that opened it (finish() on the phone). New in 1.12.0
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, id=None)	Adds the persistent audio mini-player

Overlays and feedback

API	Purpose
bottom_sheet	Material bottom sheet that drags down to close: a title, text and items, or with screen= the components put in it with parent=; on_close, open(), close()
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
native	Your own Java as a named block with a required preview= answer, plus Gradle dependency, manifest entry and R8 keep rule; 1.9.0
nfc	Foreground tag status/reading, one-shot text/URI writes, cancellation and settings; 1.9.0
contacts	Scoped phone/email picker, permission-based list/get, native create/edit forms and settings; 1.9.0
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
haptics / speech	A touch you can feel; reading aloud and dictation — 1.13.0
browser / downloads	A web page over the app or inside it; a download by the system — 1.13.0
calendar / phone	An event to add; the dialler and messages, filled in for the person — 1.13.0
recorder / printing	The microphone; printing or a PDF — 1.13.0
incoming	Links and shares that open the app — 1.13.0
home_widget / quick_tile	A home-screen widget; a quick settings tile — 1.13.0
ads / updates / health	AdMob; updates through Google Play; Health Connect — 1.13.0
timer	A function run later, or again and again, while its screen is on show — 1.13.0
network	Online or not, over what, paid for or not, and when that changes — 1.13.0
display	Staying on, brightness, the bars, which way up — 1.13.0
app_lock	The app locks itself after a while away; the phone's own lock opens it — 1.13.0
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 NFC tags for all six methods, two-argument callbacks, the JSON tag shape, normal manifest permission, lifecycle and write safety. The complete app source requires the development library; installing the current published version does not add this API.

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.