Skip to content

SKILL.md

Latest commit

 

History

History
149 lines (108 loc) · 6.68 KB

SKILL.md

File metadata and controls

149 lines (108 loc) · 6.68 KB
Raw
name pythonide-native
description Choose and implement PythonIDE iOS native modules for permissions, device state, sensors, storage, keychain, photos, camera, location, notifications, networking, Bluetooth, health, speech, media, and system actions. Use with pythonide-appui when a MiniApp needs native capability behind user-triggered callbacks.
license MIT
version 1.0.0
last_updated 2026-06-19
user_invocable true

PythonIDE Native

Discovery and implementation rules for iOS native Python modules. This skill does not replace pythonide-appui; pair both when building MiniApps that call system capabilities.

Read Before Coding

  1. iOS native index
  2. Native capabilities schema
  3. llms-full.txt native module table
  4. Focused module page: https://pythonide.xin/docs/pages/<module-id>/
  5. references.md in this skill for the full entry routing table
  6. When the UI shell is AppUI, also load pythonide-appui

Chinese module docs are authoritative for scenarios; schema and stubs are authoritative for API names.

Use When

  • The task needs permissions, device facts, sensors, storage, secrets, user content, networking, peripherals, notifications, speech, audio/video, shortcuts, Live Activities, or Core ML
  • You must choose the correct module before writing import statements
  • An AppUI MiniApp needs callback-side native work beyond bridge components

Do Not Use When

  • The task is only AppUI layout, navigation, controls, or inline bridge components with no extra module logic
  • The runtime is widget, scene, or plain stdlib Python with no iOS integration
  • The app name mentions a capability but the code never calls it

Required Flow

  1. Route by schema entry kind: module, appui_bridge, topic, reference
  2. Import only modules whose APIs are called
  3. Check availability or authorization before sensitive operations
  4. Request permission only from a named user-triggered callback
  5. Handle denied, restricted, unavailable, cancelled, empty, offline, timeout, and error outcomes visibly
  6. Persist small non-secret state with storage, queryable records with database, secrets with keychain
  7. Keep native side effects out of AppUI body()

AppUI Pairing

UI need Start here Then
Inline picker/camera/map/share/video pythonide-appui bridge table Add native module only for post-processing
Button-triggered GPS, notification, save-to-photos pythonide-appui shell import location / notification / photos in callback
Device status dashboard pythonide-appui import device, permission, storage
Script-only automation this skill only plain Python file

Permission Pattern

import permission
import storage


def ensure_photos_access():
    status = permission.status("photos")
    if status.get("status") not in {"authorized", "limited"}:
        status = permission.request("photos")
    storage.set_json("native.photos_status", status)
    return status

Module Categories

Foundation & persistence

clipboard, console, database, dialogs, keychain, permission, storage

Device & sensors

biometric, device, haptics, health, location, motion

System & comms

calendar_events, contacts, font_picker, live_activity, mail, message, notification

Media & vision

audio_recorder, audio_session, avplayer, coreml, media_composer, music, music_player, now_playing, pdf, photos, qrcode, shazam, sound, speech, speech_recognition, video_recorder, vision, vision_helper

Connectivity & background

background, background_download, ble_peripheral, bluetooth, http_server, network, nfc, ssh, weather, websocket

Automation & advanced

alarm, assistant, c_extensions (reference), foundation_models, keyboard, objc_util, shortcuts, storekit, translation

High-Signal Routing

User intent Module / bridge
Pick or save photos photos; inline UI → appui.PhotoPicker
Take photo in AppUI form appui.CameraPicker; processing → photos
Current location / map location; inline map → appui.MapView
Local notification notification (permission key is notifications)
Network fetch network
Live socket websocket
Clipboard clipboard
Share sheet in AppUI appui.ShareLink (topic share has no import)
File picker in AppUI appui.FileImporter (topic file_picker has no import)
Embedded AppUI video appui.PlayerController + appui.VideoPlayer
Custom music queue player music_player
Script-only media playback avplayer
On-device ML coreml, vision, vision_helper, foundation_models

Full key-by-key routing: references.md.

Hard Stops

  • Do not guess APIs from UIKit, Swift, browser, or Pythonista memory
  • Do not use permission.status("notification"); use notifications
  • Do not prompt permissions, scan hardware, or schedule notifications at import time or from AppUI body()
  • Do not store secrets in storage
  • Do not import CPython sqlite3 directly in MiniApps; use database, which is backed by the host Swift SQLite bridge
  • Do not use avplayer for AppUI embedded video controls
  • Do not pass music provider IDs or unresolved search rows to music_player.prepare, prefetch_next, or set_queue(..., preload_count=...); resolve them to real audio url values first
  • Do not hide denied, cancelled, or offline outcomes
  • Do not import c_extensions as runtime code; it is reference-only

Persistence Rules

Data Use
User settings, small JSON state storage
Queryable records / caches database
Tokens, passwords, API keys keychain

Repair Hints

  • Inert native button → move call into named callback; surface result in State or output
  • Wrong module → re-check references.md and schema kind
  • Offline failures → network.is_connected, network.connection_type before expensive work
  • Missing authorization → module authorization_status / request_access, else permission.status / permission.request
  • Slow music next-track → resolve and cache playback URLs in the MiniApp/data layer, then use music_player.set_queue(..., preload_count=3) and music_player.prefetch_next(3) for host-side AVPlayer preparation

Examples

  • examples/device_snapshot/ — device + permission + storage with AppUI shell in comments