pythonhere 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

pythonhere/magic_here/prompts/android-media.md

@@ -0,0 +1,130 @@
+## Android Media And Files
+
+Use this section when the user asks to browse, display, scan, filter, or build a
+gallery from Android photos, videos, downloads, `/sdcard`, DCIM, Pictures,
+Movies, Music, or other shared-storage paths.
+
+Permissions and storage access:
+
+- Always check actual runtime permission state before assuming media or storage access exists.
+- For Android 13+ media-library access, use granular media permissions such as
+  `android.permission.READ_MEDIA_IMAGES` and/or
+  `android.permission.READ_MEDIA_VIDEO`.
+- For older Android versions, `READ_EXTERNAL_STORAGE` may still be relevant.
+- Do not rely on `WRITE_EXTERNAL_STORAGE` for reading photos on modern Android.
+- Do not call `check_permission("android.permission.MANAGE_EXTERNAL_STORAGE")`.
+  It is a special app-access setting, not a normal runtime permission.
+- On Android 11+ broad all-files access can be checked with
+  `Environment.isExternalStorageManager()`, but a false result does not by
+  itself prove every media path is unreadable. Probe the requested path and
+  report both facts.
+- Do not assume `MANAGE_EXTERNAL_STORAGE` is available just because it is present
+  in the manifest. The user usually must enable “All files access” in system
+  settings, and Play policy restricts this permission.
+- Prefer privacy-friendly media access through MediaStore or the system photo
+  picker unless the user specifically asks for direct filesystem browsing.
+- Store the error/status and show errors.
+
+Path vs MediaStore access:
+
+- For a concrete path such as `/sdcard/DCIM/Camera`, first probe that path
+  directly before deciding the app lacks access.
+- For media-library/gallery access, prefer MediaStore queries.
+- Do not depend on the MediaStore `_data` column. It can be missing, deprecated,
+  inaccessible, or point to a file path the app cannot decode directly.
+- Prefer querying `_id`, building a `content://` URI with
+  `ContentUris.withAppendedId(...)`, and reading through
+  `context.getContentResolver().openInputStream(uri)`.
+- Decode MediaStore images from a valid Android `Uri` or input stream, not from
+  guessed filesystem paths.
+- If direct path access is used as a fallback, treat failure to read/decode as a
+  normal state and continue.
+
+MediaStore querying:
+
+- Always handle `cursor is None`.
+- Always check `cursor.getCount()` and show an empty-state UI when it is zero.
+- Use `moveToFirst()` safely before reading rows.
+- Always close the cursor in `finally`.
+- Avoid `while cursor.isAfterLast() is False`; prefer clearer logic such as:
+  `if cursor.moveToFirst(): ... while not cursor.isAfterLast(): ...`.
+- Log counts separately:
+  - rows found
+  - thumbnails attempted
+  - thumbnails decoded
+  - thumbnails failed
+  - permission/access state
+
+HEIC and thumbnails:
+
+- Kivy `Image` may not load `.heic` directly on Android.
+- Use Android image decoding APIs such as `android.graphics.BitmapFactory` or
+  `android.graphics.ImageDecoder` for HEIC thumbnails when available.
+- Import nested Android classes with `$`. For bitmap decoding options, define
+  `BitmapFactoryOptions = autoclass("android.graphics.BitmapFactory$Options")`
+  and use `BitmapFactoryOptions()`. Do not access it as `BitmapFactory.Options()`.
+- With `ImageDecoder` and a Java `File`, prefer:
+  `source = ImageDecoder.createSource(java_file)`.
+- Do not call:
+  `ImageDecoder.createSource(context.getContentResolver(), java_file)`,
+  because the `ContentResolver` overload expects a `Uri`, not a `File`.
+- If using a `ContentResolver` with `ImageDecoder`, pass a valid Android `Uri`,
+  not a filesystem path or Java `File`.
+- Avoid `ImageDecoder.decodeBitmap(source, python_lambda)` unless a correct Java
+  listener interface is implemented. Through Pyjnius, prefer:
+  `bitmap = ImageDecoder.decodeBitmap(source)`,
+  then scale/compress the decoded bitmap.
+- Import nested Android classes with `$`. For bitmap compression, define:
+  `CompressFormat = autoclass("android.graphics.Bitmap$CompressFormat")`
+  and use `CompressFormat.JPEG` or `CompressFormat.PNG`.
+- Do not access compression format as `Bitmap.CompressFormat`.
+- Do not assume Kivy `Image.source` accepts `data:image/...;base64,...` URIs.
+  Prefer writing thumbnails to small temporary files in the app cache directory
+  and setting `Image.source` to those file paths.
+- Use `context.getCacheDir().getAbsolutePath()` for thumbnail cache files.
+- Avoid writing into `/sdcard` unless the user asks for exported files.
+- Keep Android bitmap dimensions as plain Python `int` pixel values.
+- Do not pass Kivy `dp(...)` float values directly to Android bitmap APIs such
+  as `Bitmap.createScaledBitmap(...)`.
+- Use separate constants for UI size and decode size, for example:
+  `THUMB_UI_DP = dp(120)` for widgets and `THUMB_PX = 240` for Android bitmap
+  scaling.
+- Recycle Android `Bitmap` objects after thumbnail compression when possible.
+
+Generated-code defaults:
+
+- For “show my gallery/photos” code, default to:
+  MediaStore query → `_id` → content URI → openInputStream/decode → cache
+  thumbnail file → Kivy Image source = cache file path.
+- Avoid defaulting to:
+  MediaStore `_data` → raw filesystem path → `BitmapFactory.decodeFile(...)`.
+- Include a visible debug/status label during development.
+- Include enough logging to distinguish:
+  permission not granted,
+  MediaStore returned no rows,
+  rows found but decode failed,
+  thumbnails decoded but widget display failed.
+
+Android 14+ partial photo/video access:
+
+- On Android 14+ (API 34+), photo/video access may be partial because the user
+  selected only some media. Generated gallery code must report whether access
+  appears full, partial, denied, or unknown when permission information is
+  available.
+- If only partial access is available, continue with MediaStore and show the
+  accessible subset instead of treating the result as a failure.
+- When the user wants to choose media rather than browse the whole library,
+  prefer a system picker/user-selection flow over broad storage/media
+  permissions.
+- Keep the debug/status label explicit: distinguish `permission_denied`,
+  `partial_media_access`, `mediastore_empty`, `decode_failed`, and
+  `display_ready`.
+
+Query defaults:
+
+- For general gallery requests, query images first unless the user asked for
+  videos or audio too. Avoid scanning every media type by default.
+- Limit initial thumbnail queries to a reasonable count such as 50-100 items,
+  store full metadata in a global, and render a small preview first.
+- Do not assume an empty MediaStore result means there are no photos on the
+  device; report permission/access state and query filters too.

pythonhere/magic_here/prompts/android-packages.md

@@ -0,0 +1,69 @@
+## Android Package Inventory
+
+Use this addon when the user asks to list, inspect, filter, summarize, or export
+installed Android apps, packages, APK files, package labels, versions, system-app
+status, or requested permissions for installed packages.
+
+PackageManager rules:
+
+- Use `org.kivy.android.PythonActivity.mActivity`.
+- Import `org.kivy.android.PythonService` inside the fallback block, not before
+  it is needed, because some apps do not package service support.
+- Get a `PackageManager` from the Android context.
+- Use `PackageManager.getInstalledPackages(...)` with `GET_PERMISSIONS`.
+- In Pyjnius, import Android nested classes with `$`, not Python attribute
+  access. For SDK checks, define
+  `VERSION = autoclass("android.os.Build$VERSION")` and use
+  `VERSION.SDK_INT`. Do not use `Build.VERSION.SDK_INT`.
+- On Android API 33+, call `PackageInfoFlags.of(...)`.
+- On older Android versions, pass integer flags directly.
+- In Pyjnius, the Android API 33 flags class must be imported as:
+  `PackageInfoFlags = autoclass("android.content.pm.PackageManager$PackageInfoFlags")`.
+  Then call `PackageInfoFlags.of(flags)`. Do not call
+  `PackageManager.PackageInfoFlags.of(...)`.
+- Use `android.content.pm.ApplicationInfo.FLAG_SYSTEM` and
+  `FLAG_UPDATED_SYSTEM_APP` for system app detection.
+- Do not use `android.content.pm.ActivityInfo` for installed application flags.
+- Use `ApplicationInfo.sourceDir` and `splitSourceDirs` with `java.io.File` for
+  APK file sizes. Report `None` when a path is unavailable.
+- Store APK size details separately, for example `base_apk_size_bytes`,
+  `split_apk_sizes_bytes`, and `total_apk_size_bytes`.
+- Use `PackageInfo.requestedPermissions` plus
+  `PackageInfo.requestedPermissionsFlags`.
+- A requested permission is granted when the matching flag has
+  `PackageInfo.REQUESTED_PERMISSION_GRANTED` set.
+- Do not use `PackageManager.PERMISSION_GRANTED` or
+  `ActivityInfo.REQUESTED_PERMISSION_GRANTED` for requested permission flags.
+- Import every Android class referenced in the code with `autoclass`.
+  If code uses `PackageInfo.REQUESTED_PERMISSION_GRANTED`, it must first define
+  `PackageInfo = autoclass("android.content.pm.PackageInfo")`.
+- `requestedPermissions`, `requestedPermissionsFlags`, and `splitSourceDirs` are
+  Java arrays. In Pyjnius, handle them with `len(array)` and `array[index]`;
+  do not call `.size()` or `.get()` on them.
+- Keep per-app permission records as dictionaries with at least `name` and
+  `granted`.
+- Convert Java string-like fields such as package name, label, and version name
+  to Python strings or `None` before storing them.
+- Keep preview output simple. If you compute `perms_granted`, print
+  `perms_granted`; do not reference a different variable name.
+- Do not import `json`, `pathlib.Path`, or `pprint` unless the user explicitly
+  asks to export or pretty-print data.
+- Do not import `os` unless the user explicitly asks for filesystem or
+  environment inspection.
+- Do not import `cast`, `contextlib`, or other helpers unless the generated code
+  actually uses them.
+
+Android 11+ package visibility:
+
+- On Android 11+ (API 30+) package visibility filtering can make
+  `getInstalledPackages(...)` return a filtered set when the manifest does not
+  declare the needed package visibility queries or `QUERY_ALL_PACKAGES`.
+- Do not promise a complete inventory of all installed apps on Android 11+
+  unless the app's manifest/package visibility allows it.
+- Store and print a field such as `package_visibility_note` when results may be
+  filtered.
+- If the user asks why some apps are missing, explain that Android package
+  visibility is manifest/policy controlled and cannot be fixed from a
+  runtime-only snippet.
+- Do not request `QUERY_ALL_PACKAGES` at runtime; it is a manifest/policy
+  matter, not a dangerous runtime permission prompt.

pythonhere/magic_here/prompts/android-permissions.md

@@ -0,0 +1,195 @@
+## Android Permissions
+
+Use this section when need to check, request, or explain permissions for
+the running Android app.
+
+Critical rules:
+
+- Do not assume a runtime permission can be granted if it is missing from the
+  Android manifest. Runtime requests only work for permissions declared by the
+  app.
+- Do not use installed-package permission metadata to decide whether this app has
+  a runtime permission. Use runtime permission APIs for the current app.
+- Choose the Android access mechanism from the user's goal. Do not force every
+  access request through `request_permissions`.
+- Use fully qualified Android permission strings for all permission APIs, for
+  example `"android.permission.CAMERA"`. Do not pass short names such as
+  `"CAMERA"`, `"READ_EXTERNAL_STORAGE"`, or `"WRITE_EXTERNAL_STORAGE"` to
+  `check_permission`, `request_permissions`, or `context.checkSelfPermission`.
+- If storing display-friendly names, keep them separate from the full permission
+  strings used for Android API calls.
+- When the user asks to "request", "enable", "grant", or "get access", generated
+  code must perform the appropriate request action immediately when possible. Do
+  not tell the user to ask again for the Settings-opening step.
+- Do not call `raise SystemExit` or terminate the host app when context,
+  activity, or permission APIs are unavailable. Store an error result and print a
+  concise message instead.
+
+Decision model:
+
+- Dangerous runtime permissions: check with `check_permission(...)` or
+  `context.checkSelfPermission(...)`; request with
+  `android.permissions.request_permissions(...)` when the user asks to request.
+  Examples: camera, microphone, fine/coarse location, contacts, calendar,
+  nearby Bluetooth permissions, Android 13+ notifications.
+- Normal permissions: do not request at runtime. Report that they are install-
+  time permissions.
+- Signature/privileged permissions: do not request at runtime. Report that they
+  cannot be granted to ordinary apps unless the app is privileged or signed with
+  the platform key.
+- Special app-access permissions: do not request with
+  `request_permissions(...)`. Check with the dedicated Android API when one
+  exists, and open the relevant Settings screen only when the user asks to
+  request/open/enable access.
+- Storage and media access depends on Android API level and requested scope.
+  Do not treat "storage", "sdcard", "external storage", "photos", "media", or
+  "all files" as one generic permission.
+
+Preferred Python-for-Android API:
+
+- Prefer `from android.permissions import Permission, check_permission,
+  request_permissions` when the `android` package is available.
+- Use `check_permission(permission_name)` to check one permission for the current
+  app.
+- Use `request_permissions(permission_names, callback)` to request one or more
+  dangerous runtime permissions.
+- Pass full permission strings to these functions. Prefer constants from
+  `android.permissions.Permission` when they are available and correct for the
+  target API; otherwise use full strings like
+  `"android.permission.ACCESS_FINE_LOCATION"`.
+- The request callback should accept `(permissions, grants)` and store both the
+  raw arrays and a Python dictionary mapping permission name to granted boolean.
+- Do not rely on `print(...)` inside the permission request callback as the only
+  result. The callback may run after notebook output capture has ended. Store the
+  result globally and update visible UI when appropriate.
+- Do not convert grant values with `bool(grant)`. Android uses
+  `PackageManager.PERMISSION_GRANTED == 0` and
+  `PackageManager.PERMISSION_DENIED == -1`, so `bool(-1)` is wrong. Convert with
+  `grant == PackageManager.PERMISSION_GRANTED` when grant values are integers.
+- Keep a global reference to the callback result, for example
+  `android_permission_request_result`, so later cells can inspect it.
+
+Pyjnius fallback for checks:
+
+- Get a current context from `org.kivy.android.PythonActivity.mActivity` or, only
+  as a fallback, `org.kivy.android.PythonService.mService`.
+- Define `VERSION = autoclass("android.os.Build$VERSION")` and use
+  `VERSION.SDK_INT`. Do not use `Build.VERSION.SDK_INT`.
+- Define `PackageManager = autoclass("android.content.pm.PackageManager")`.
+- On API 23 and newer, call `context.checkSelfPermission(permission_name)` and
+  compare the result to `PackageManager.PERMISSION_GRANTED`.
+- For permission request callbacks, use the same
+  `PackageManager.PERMISSION_GRANTED` constant to normalize grant results.
+- On API levels below 23, runtime permission prompts do not exist. Treat declared
+  install-time permissions as already granted for runtime-check purposes, but
+  print that the result is pre-runtime-permission behavior.
+
+Requesting permissions:
+
+- For Kivy/Python-for-Android apps, use `android.permissions.request_permissions`
+  instead of calling `activity.requestPermissions(...)` directly.
+- If the `android.permissions` module is unavailable, do not invent a Pyjnius
+  subclass or callback receiver for `activity.requestPermissions(...)`. Use
+  Pyjnius only to check current permission state, then report that requesting
+  runtime permissions requires the Python-for-Android permission helper or app
+  integration.
+- Request only dangerous/runtime permissions. Normal permissions are granted at
+  install time and should be reported as not needing a runtime prompt.
+- Do not request special app-access permissions as if they were normal runtime
+  permissions. Examples: `MANAGE_EXTERNAL_STORAGE`, notification listener
+  access, accessibility service access, overlay permission, battery optimization
+  exemption, usage access, and exact alarm access. If the user asked only to
+  check, report that they require a Settings screen flow. If the user asked to
+  request/enable/get access, open the correct Settings screen immediately when a
+  foreground activity is available.
+- Android 13+ notification permission is
+  `android.permission.POST_NOTIFICATIONS`; request it only on API 33 and newer.
+- If the activity is unavailable, do not attempt a permission request from a
+  service-only context. Print that a foreground activity is required.
+
+Special app-access flows:
+
+- If the user asks to request or enable a special app-access permission, open the
+  most specific Settings screen available for this app. Use `Intent`,
+  `Settings`, and `Uri.parse(f"package:{context.getPackageName()}")` where the
+  action supports an app-specific URI.
+- Build Settings intents conservatively: create `intent = Intent(action)` and
+  then call `intent.setData(Uri.parse(f"package:{package_name}"))` for
+  app-specific Settings actions. This is more reliable through Pyjnius than
+  relying on overloaded Java constructors.
+- Always store whether the Settings screen was opened, the action used, and the
+  current access state before opening Settings.
+- Do not claim Settings access was granted immediately after opening Settings.
+  The user must return from Settings; tell them to rerun the check afterward.
+- If `activity` is unavailable, do not call `startActivity`. Report that a
+  foreground activity is required to open Settings.
+
+Storage and media access:
+
+- For Android 13+ (API 33+), media permissions are split:
+  `READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`, and `READ_MEDIA_AUDIO`. Use these
+  only for media-library access, not for arbitrary `/sdcard` file access.
+- For Android 10-12 (API 29-32), `READ_EXTERNAL_STORAGE` may allow media/shared
+  storage reads, but scoped storage still limits arbitrary file access. Do not
+  promise full `/sdcard` traversal from this permission.
+- `WRITE_EXTERNAL_STORAGE` is ignored or heavily limited on modern Android. Do
+  not rely on it for Android 10+ shared-storage writes.
+- When generating runtime storage permission requests, request
+  `android.permission.WRITE_EXTERNAL_STORAGE` only for API 28 and lower. For API
+  29, do not request `WRITE_EXTERNAL_STORAGE` as a solution for broad storage
+  writes; explain the scoped-storage limitation instead.
+- For Android 11+ (API 30+), broad "all files" access is the special access
+  `MANAGE_EXTERNAL_STORAGE`. Check it with
+  `Environment.isExternalStorageManager()`.
+- To request Android 11+ all-files access, open Settings; do not call
+  `request_permissions(["android.permission.MANAGE_EXTERNAL_STORAGE"], ...)`.
+  Prefer `Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION` with
+  `Uri.parse(f"package:{context.getPackageName()}")`, and fall back to
+  `Settings.ACTION_MANAGE_ALL_FILES_ACCESS_PERMISSION` if the app-specific
+  action fails.
+- For a broad `/sdcard` access request on Android 11+, do not additionally
+  request `READ_EXTERNAL_STORAGE` or `WRITE_EXTERNAL_STORAGE` as the primary
+  solution. Those permissions do not grant broad all-files access.
+- For Android versions below 11, use runtime storage permissions only when they
+  match the user's requested scope, and explain that behavior differs by API
+  level and manifest settings.
+- For creating or picking user-selected files, prefer Android's document/media
+  picker or Storage Access Framework when the user does not need broad all-files
+  access.
+
+Output shape:
+
+- For permission checks, use a global such as `android_permission_status`.
+- For permission requests, use a global such as
+  `android_permission_request_result`.
+- Print each permission with a short status such as `granted`, `denied`,
+  `not_requested_pre_23`, `normal_permission_no_runtime_prompt`, or
+  `requires_settings_flow`.
+- For special Settings flows, include fields such as `access_name`,
+  `currently_granted`, `settings_opened`, `settings_action`, and
+  `rerun_check_after_return`.
+
+Android 14+ selected media access:
+
+- On Android 14+ (API 34+), users may grant partial access to selected
+  photos/videos. Treat this as a valid limited-access state, not a simple
+  denial.
+- For media-gallery code on Android 14+, consider
+  `android.permission.READ_MEDIA_VISUAL_USER_SELECTED` alongside
+  `READ_MEDIA_IMAGES` and/or `READ_MEDIA_VIDEO` when the user wants to manage or
+  reselect partial media access.
+- If the user only wants to pick one or a few files/photos, prefer a
+  picker/user-selection flow instead of broad media permissions.
+- If partial media access is detected, explain through code comments or status
+  text that MediaStore results may include only the selected items.
+
+Notification and special-access reminders:
+
+- `android.permission.POST_NOTIFICATIONS` is a dangerous runtime permission only
+  on API 33+; below API 33, do not request it at runtime.
+- Exact alarm, overlay, accessibility, notification listener, usage access,
+  battery optimization exemption, and all-files access are special settings
+  flows, not normal runtime permissions.
+- For Settings flows, open the specific settings screen only when the user asked
+  to request, enable, or open access; otherwise only report the current state and
+  the needed flow.

pythonhere/magic_here/prompts/android-runtime.md

@@ -0,0 +1,34 @@
+## Android Runtime
+
+The generated code runs inside the Android app's existing Python process.
+Assume Python-for-Android/Kivy unless the user says otherwise.
+
+Critical rules:
+
+- Do not use `adb`.
+- Do not use `subprocess`, shell commands, or host-side Android tools.
+- Do not use legacy SL4A-style Android helper APIs. PythonHere is a
+  Kivy/Python-for-Android app, not an SL4A runtime.
+- Do not write files unless the user explicitly asks for a file export.
+- Prefer Android framework APIs through `jnius` over parsing command output.
+- Use the already-running activity or service instead of starting one.
+- If the code needs Android context, prefer
+  `org.kivy.android.PythonActivity.mActivity`.
+- Import `org.kivy.android.PythonService` only inside a fallback block, because
+  some apps do not package service support.
+- Import every Android class referenced in the code with `autoclass`.
+- Import Android nested classes with `$`, not Python attribute access.
+- For SDK checks, define `VERSION = autoclass("android.os.Build$VERSION")` and
+  use `VERSION.SDK_INT`. Do not use `Build.VERSION.SDK_INT`.
+- Convert Java string-like fields to Python strings or `None` before storing
+  them.
+- Java arrays are Python-indexable in Pyjnius. Use `len(array)` and
+  `array[index]`; do not call `.size()` or `.get()` unless the object is a Java
+  `List`.
+- Do not import `json`, `pathlib.Path`, `pprint`, `os`, `cast`, `contextlib`, or
+  other helpers unless the generated code actually uses them.
+
+HTTPS requests:
+- Always use certifi, `context = ssl.create_default_context(cafile=certifi.where())`
+- Never use urlopen() directly for https:// URLs.
+- Never disable SSL verification.