From 07fb09268392b9a886f7467e7926de11af4a2068 Mon Sep 17 00:00:00 2001 From: Maksum867 Date: Sat, 14 Nov 2026 20:28:18 +0000 Subject: [PATCH] PyMobile 0.15.0 The audit's two blockers are closed, plus everything that was cheap enough to finish in the same release. Every item below was reproduced first, fixed in the code, and is held by a test that fails without the change. Publishing (A10, A1) - `build --native --bundle` writes an `.aab` beside the APK, from the same manifest, dex, assets and native libraries, and validates it with bundletool (`validate` + `build-apks --mode=universal`). Three packaging defects only bundletool could see were fixed on the way: the manifest was copied as binary APK bytes instead of a proto XmlNode, `base/res/` was fed the compiler's `.flat` intermediates, and native libraries were looked for in the wrong directory (so a bundle carried none at all). - Default `target_sdk` is 36 and `setup-sdk` installs `platforms;android-36`, the level Play requires from 31 August 2026. The new-project template still said 35, so a fresh project would have been rejected after all of this. - `find_toolchain()` compiles against `SDK_PLATFORM` rather than `target_sdk`, so the compiled level and the declared level cannot disagree. - A destroyed Activity no longer takes the interpreter with it: `onDestroy` sends a `__lifecycle__`/`stop` event, `Screen.on_stop()` runs, widget state is kept, and the next window resumes the same app with `Screen.on_start()`. Input that arrives after the stop is dropped. On the device (A2, A3, A4, A5, A9, A18, A19) - The root container applies system-bar, cutout and IME insets itself; `adjustResize` and an `app:insets` event cover the keyboard. - Images are decoded on a worker thread, scaled to the view, EXIF-rotated, and a decode that loses the race against a newer source is discarded. - `supportsRtl` and start/end margins, so Arabic and Hebrew mirror. - The startup screen follows the system theme, and a light/dark switch reaches Python as `app:system-theme` (`App(follow_system_theme=True)` follows it). - The back callback is registered only while there is a screen to go back to; on the root screen the platform's own "leave the app" runs again. - Three deprecated calls replaced; a remote `Image` source warns instead of drawing an empty box. Packaging and security (A17, S7) - `abis = [...]` now really packages every requested architecture in one APK; the second one used to be dropped without a word. - `[network.pins]` pins a domain to the certificates you list, which also stops the app trusting the device's user-installed roots. Storage correctness found by CI - A store that failed to load stayed failed only while the object happened to be alive: the backend registry is weak, so a pinned failure could be collected and the next open quietly retried. Failed states are now held for the process, which is what the docstring always promised. - The "1000 puts are quick" test asserted a wall-clock budget and failed on shared and Windows runners while the code was fine. It now counts storage writes (the same number everywhere) with a generous ceiling that only a quadratic regression trips, and the batching promise got its own test. Contributor and beginner experience (C5, C6, C8, N3, K11) - An Android CI job builds a signed APK and an `.aab` on every push and asserts the manifest declares target 36 and `supportsRtl`. Its first run caught a pinned action SHA that does not exist. - `docs/TUTORIAL.md` and `docs/BEGINNER-MISTAKES.md`; the tutorial's imports and every documented command are checked by tests, so a rename breaks CI instead of a newcomer's first hour. There is no `examples/` tree: the tutorial is the example. - `Storage` and `ModelStore` describe their migration keys the same way, and each error message points at the other store. Also: `--minimal-stdlib` drops what a phone cannot use (709 -> 514 packaged files), the bundled dex is rebuilt and its source hashes re-recorded. Not in this release, and not pretended otherwise: extension points (A11), AndroidX/Material (A12), RecyclerView (A13), incremental frames (A14), `.so` under `lib/` (A6) and `.pyc` in the APK (A7) need rebuilding the runtime or redesigning a subsystem; S1 depends on that same NDK rebuild. None of the Android behaviour above has been observed on a physical device here - the evidence is javac against android-36, bundletool on a real bundle, and tests. --- .github/ISSUE_TEMPLATE/config.yml | 7 + .github/ISSUE_TEMPLATE/good_first_issue.yml | 67 ++ .github/dependabot.yml | 30 + .github/workflows/publish.yml | 6 +- .github/workflows/quality.yml | 70 +- CHANGELOG.md | 344 +++++- README.md | 372 ++++++- docs/BEGINNER-MISTAKES.md | 131 +++ docs/CONTRIBUTING.md | 191 +++- docs/TUTORIAL.md | 236 +++++ pymobile/__init__.py | 11 +- pymobile/cli.py | 127 +-- pymobile/cli_build.py | 136 +++ pymobile/cli_errors.py | 65 ++ pymobile/cli_parser.py | 24 + pymobile/cli_preview.py | 4 +- pymobile/cli_tools.py | 45 +- pymobile/compiler/backends/native.py | 149 ++- pymobile/compiler/bundle.py | 249 +++++ pymobile/compiler/collector.py | 39 + pymobile/compiler/icon.py | 120 ++- pymobile/compiler/manifest.py | 73 +- pymobile/compiler/pipeline.py | 296 +++++- pymobile/compiler/precheck.py | 88 +- pymobile/compiler/rebuild_dex.py | 1 + pymobile/compiler/scaffold.py | 4 +- pymobile/compiler/sdk_installer.py | 17 +- pymobile/compiler/size_report.py | 1 + pymobile/compiler/toolchain.py | 14 +- pymobile/compiler/widgets.py | 101 +- pymobile/core/api/audio.py | 8 +- pymobile/core/api/notifications.py | 8 +- pymobile/core/api/storage.py | 201 +++- pymobile/core/api/typed_storage.py | 324 +++++- pymobile/core/app.py | 288 +++++- pymobile/core/bridge/android.py | 91 +- pymobile/core/bridge/base.py | 70 +- pymobile/core/bridge/gui.py | 6 + pymobile/core/bridge/jni.py | 23 +- pymobile/core/bridge/stub.py | 55 + pymobile/core/config.py | 109 +- pymobile/core/driver.py | 27 +- pymobile/core/i18n.py | 26 +- pymobile/core/jobs.py | 119 ++- pymobile/core/net/cache.py | 8 +- pymobile/core/net/http.py | 780 ++++++++++++-- pymobile/core/plugins.py | 2 +- pymobile/core/ui/__init__.py | 8 +- pymobile/core/ui/_mockup_chrome.py | 3 + pymobile/core/ui/_mockup_context.py | 4 +- pymobile/core/ui/_mockup_fonts.py | 86 +- pymobile/core/ui/_mockup_layout.py | 8 +- pymobile/core/ui/_mockup_paint.py | 232 ++++- pymobile/core/ui/_mockup_widgets.py | 63 +- pymobile/core/ui/audit.py | 17 +- pymobile/core/ui/canvas.py | 7 + pymobile/core/ui/charts.py | 6 + pymobile/core/ui/components.py | 276 ++++- pymobile/core/ui/contract.py | 2 + pymobile/core/ui/controls.py | 37 + pymobile/core/ui/dialogs.py | 8 + pymobile/core/ui/drawing.py | 269 +++++ pymobile/core/ui/extra_widgets.py | 3 + pymobile/core/ui/extras_preview.py | 58 ++ pymobile/core/ui/gui.py | 979 ++++++++++++------ pymobile/core/ui/layout.py | 7 + pymobile/core/ui/list.py | 11 +- pymobile/core/ui/navigation.py | 6 +- pymobile/core/ui/patterns.py | 58 ++ pymobile/core/ui/pickers.py | 9 +- pymobile/core/ui/preview.py | 15 +- pymobile/core/ui/registry.py | 14 +- pymobile/core/ui/screen.py | 101 +- pymobile/core/ui/state.py | 349 +++++++ pymobile/core/ui/style.py | 290 +++++- pymobile/core/ui/web.py | 874 +++++++++++----- pymobile/core/ui/widget.py | 150 ++- pymobile/core/validation.py | 10 +- pymobile/log.py | 1 + .../resources/android/java/AdvancedViews.java | 5 +- .../android/java/DeviceServices.java | 129 +++ .../resources/android/java/MainActivity.java | 224 +++- .../resources/android/java/MediaServices.java | 7 +- pymobile/resources/android/java/Native.java | 20 + .../resources/android/java/PythonRuntime.java | 26 + .../resources/android/java/ViewBuilder.java | 16 +- .../android/java/ViewContainers.java | 16 +- .../resources/android/java/ViewControls.java | 148 ++- .../resources/android/java/ViewInputs.java | 83 +- .../resources/android/java/ViewStyles.java | 413 +++++++- .../resources/android/java/ViewUpdates.java | 66 +- pymobile/resources/android/jni/pymobile_jni.c | 107 ++ .../android/prebuilt/arm64-v8a/classes.dex | Bin 141092 -> 160584 bytes .../prebuilt/arm64-v8a/classes.sources.json | 26 +- .../android/prebuilt/arm64-v8a/libpymobile.so | Bin 46568 -> 48976 bytes .../android/prebuilt/x86_64/libpymobile.so | Bin 45000 -> 47304 bytes .../templates/pymobile.toml.template | 4 +- pymobile/testing/plugin.py | 5 +- pymobile/testing/png_snapshots.py | 4 +- ...y => test_accessibility_audit_findings.py} | 10 +- ...test_adaptive_icon_and_packaged_secrets.py | 210 ++++ pymobile/tests/test_animations.py | 24 +- pymobile/tests/test_app_bundle_output.py | 242 +++++ ... => test_app_current_and_widget_parent.py} | 6 +- ...wser5.py => test_browser_avatar_photos.py} | 2 +- ...=> test_browser_image_fit_and_contrast.py} | 2 +- ...> test_browser_theme_dialogs_and_focus.py} | 2 +- .../tests/test_build_notification_warning.py | 2 +- .../test_build_warnings_and_artifact_names.py | 70 ++ ...ng.py => test_button_and_text_painting.py} | 2 +- ...s.py => test_cache_assets_and_launcher.py} | 40 +- pymobile/tests/test_certificate_pins.py | 115 ++ ...test_chart_geometry_and_picker_preview.py} | 2 +- .../test_checkbox_and_segmented_options.py | 49 + pymobile/tests/test_child_type_errors.py | 47 + pymobile/tests/test_cli.py | 2 +- .../tests/test_cli_user_error_reporting.py | 96 ++ pymobile/tests/test_compiler.py | 16 +- ...es.py => test_dev_preview_and_wire_ids.py} | 2 +- pymobile/tests/test_developer_tools.py | 1 - pymobile/tests/test_device_cli.py | 61 +- .../tests/test_device_system_contracts.py | 289 ++++++ pymobile/tests/test_devtools.py | 4 +- ...=> test_doctor_and_generated_templates.py} | 2 +- .../test_documentation_matches_the_api.py | 79 ++ pymobile/tests/test_driver_and_navigation.py | 5 +- pymobile/tests/test_http.py | 6 +- .../test_http_connections_and_encoding.py | 250 +++++ pymobile/tests/test_i18n.py | 4 +- pymobile/tests/test_icon_set_coverage.py | 19 + pymobile/tests/test_init_templates.py | 5 +- pymobile/tests/test_job_worker_pool.py | 122 +++ ...=> test_launcher_permissions_and_audio.py} | 46 +- pymobile/tests/test_link_url_schemes.py | 23 + ...y => test_manifest_signing_and_dialogs.py} | 7 +- pymobile/tests/test_model_store_queries.py | 203 ++++ pymobile/tests/test_more_features.py | 1 + pymobile/tests/test_native.py | 54 +- ..._p_fixes.py => test_native_build_gates.py} | 4 +- ...al5.py => test_pillow_and_tk_rendering.py} | 8 +- pymobile/tests/test_platform_gaps.py | 10 +- ...est_png_preview_measurement_and_glyphs.py} | 13 +- ...i_audit.py => test_prebuilt_bridge_api.py} | 24 +- pymobile/tests/test_precheck.py | 47 +- pymobile/tests/test_preview_host_check.py | 47 + pymobile/tests/test_project_diagnostics.py | 39 + ...test_public_api_and_registry_contracts.py} | 2 +- ...ssions.py => test_public_api_contracts.py} | 14 +- pymobile/tests/test_reactive_values.py | 110 ++ ...=> test_rebuild_mechanics_and_previews.py} | 54 +- ...dit.py => test_release_artifact_hashes.py} | 2 +- ...renderer_parity_between_python_and_java.py | 123 +++ .../tests/test_screen_state_and_titles.py | 23 + .../tests/test_secrets_and_log_redaction.py | 177 ++++ ...> test_sequence_children_in_containers.py} | 2 +- pymobile/tests/test_shell_widgets.py | 18 +- ...y => test_storage_migrations_and_check.py} | 2 +- pymobile/tests/test_storage_write_batching.py | 109 ++ .../tests/test_style_fields_and_previews.py | 186 ++++ ... test_tables_images_and_preview_chrome.py} | 2 +- pymobile/tests/test_testing_plugin.py | 8 +- pymobile/tests/test_text_input_keyboard.py | 70 ++ ...> test_theme_contrast_and_translations.py} | 2 +- ...py => test_threads_jobs_and_widget_api.py} | 20 +- ... test_typed_find_and_locale_formatting.py} | 13 +- pymobile/tests/test_ui.py | 8 +- ...test_virtualised_list_plugins_and_jobs.py} | 3 +- ... => test_widget_and_storage_edge_cases.py} | 6 +- ...est_widget_events_and_legacy_arguments.py} | 2 +- .../test_widget_state_across_rebuilds.py | 58 ++ pymobile/tests/test_window_lifecycle_state.py | 141 +++ pymobile/tests/test_wrap_and_segments.py | 8 +- pyproject.toml | 4 +- 173 files changed, 12301 insertions(+), 1603 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/good_first_issue.yml create mode 100644 .github/dependabot.yml create mode 100644 docs/BEGINNER-MISTAKES.md create mode 100644 docs/TUTORIAL.md create mode 100644 pymobile/cli_build.py create mode 100644 pymobile/cli_errors.py create mode 100644 pymobile/compiler/bundle.py create mode 100644 pymobile/core/ui/state.py rename pymobile/tests/{test_ui_audit.py => test_accessibility_audit_findings.py} (95%) create mode 100644 pymobile/tests/test_adaptive_icon_and_packaged_secrets.py create mode 100644 pymobile/tests/test_app_bundle_output.py rename pymobile/tests/{test_known_issues_closed.py => test_app_current_and_widget_parent.py} (97%) rename pymobile/tests/{test_audit_browser5.py => test_browser_avatar_photos.py} (97%) rename pymobile/tests/{test_audit_browser4.py => test_browser_image_fit_and_contrast.py} (98%) rename pymobile/tests/{test_audit_browser3.py => test_browser_theme_dialogs_and_focus.py} (99%) create mode 100644 pymobile/tests/test_build_warnings_and_artifact_names.py rename pymobile/tests/{test_audit_rendering.py => test_button_and_text_painting.py} (98%) rename pymobile/tests/{test_audit_platform_fixes.py => test_cache_assets_and_launcher.py} (96%) create mode 100644 pymobile/tests/test_certificate_pins.py rename pymobile/tests/{test_audit_visual3.py => test_chart_geometry_and_picker_preview.py} (99%) create mode 100644 pymobile/tests/test_checkbox_and_segmented_options.py create mode 100644 pymobile/tests/test_child_type_errors.py create mode 100644 pymobile/tests/test_cli_user_error_reporting.py rename pymobile/tests/{test_report_p_fixes.py => test_dev_preview_and_wire_ids.py} (98%) create mode 100644 pymobile/tests/test_device_system_contracts.py rename pymobile/tests/{test_doctor_onboarding_regressions.py => test_doctor_and_generated_templates.py} (98%) create mode 100644 pymobile/tests/test_documentation_matches_the_api.py create mode 100644 pymobile/tests/test_http_connections_and_encoding.py create mode 100644 pymobile/tests/test_icon_set_coverage.py create mode 100644 pymobile/tests/test_job_worker_pool.py rename pymobile/tests/{test_handoff_findings.py => test_launcher_permissions_and_audio.py} (93%) create mode 100644 pymobile/tests/test_link_url_schemes.py rename pymobile/tests/{test_audit_fixes.py => test_manifest_signing_and_dialogs.py} (98%) create mode 100644 pymobile/tests/test_model_store_queries.py rename pymobile/tests/{test_remaining_p_fixes.py => test_native_build_gates.py} (98%) rename pymobile/tests/{test_audit_final5.py => test_pillow_and_tk_rendering.py} (97%) rename pymobile/tests/{test_preview_render.py => test_png_preview_measurement_and_glyphs.py} (87%) rename pymobile/tests/{test_prebuilt_api_audit.py => test_prebuilt_bridge_api.py} (76%) create mode 100644 pymobile/tests/test_preview_host_check.py rename pymobile/tests/{test_audit_api.py => test_public_api_and_registry_contracts.py} (99%) rename pymobile/tests/{test_regressions.py => test_public_api_contracts.py} (98%) create mode 100644 pymobile/tests/test_reactive_values.py rename pymobile/tests/{test_stale_ui_and_preview_fixes.py => test_rebuild_mechanics_and_previews.py} (91%) rename pymobile/tests/{test_release_audit.py => test_release_artifact_hashes.py} (95%) create mode 100644 pymobile/tests/test_renderer_parity_between_python_and_java.py create mode 100644 pymobile/tests/test_secrets_and_log_redaction.py rename pymobile/tests/{test_sequence_children_regressions.py => test_sequence_children_in_containers.py} (96%) rename pymobile/tests/{test_review_2026_11_05.py => test_storage_migrations_and_check.py} (98%) create mode 100644 pymobile/tests/test_storage_write_batching.py create mode 100644 pymobile/tests/test_style_fields_and_previews.py rename pymobile/tests/{test_audit_native4.py => test_tables_images_and_preview_chrome.py} (99%) create mode 100644 pymobile/tests/test_text_input_keyboard.py rename pymobile/tests/{test_recent_framework_regressions.py => test_theme_contrast_and_translations.py} (99%) rename pymobile/tests/{test_audit_fixes_eh.py => test_threads_jobs_and_widget_api.py} (97%) rename pymobile/tests/{test_features_080.py => test_typed_find_and_locale_formatting.py} (98%) rename pymobile/tests/{test_platform_features.py => test_virtualised_list_plugins_and_jobs.py} (98%) rename pymobile/tests/{test_audit_review_fixes.py => test_widget_and_storage_edge_cases.py} (99%) rename pymobile/tests/{test_api_ergonomics_regressions.py => test_widget_events_and_legacy_arguments.py} (98%) create mode 100644 pymobile/tests/test_widget_state_across_rebuilds.py create mode 100644 pymobile/tests/test_window_lifecycle_state.py diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 0086358..2084c6e 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1 +1,8 @@ blank_issues_enabled: true +contact_links: + - name: Security report (private) + url: https://github.com/Maksum867/PyMobile/blob/main/docs/SECURITY.md + about: Never open a public issue for a vulnerability; follow the Security Policy. + - name: Contributing guide + url: https://github.com/Maksum867/PyMobile/blob/main/docs/CONTRIBUTING.md#first-contribution-in-ten-minutes + about: Where a first patch goes, which checks to run, and what review looks for. diff --git a/.github/ISSUE_TEMPLATE/good_first_issue.yml b/.github/ISSUE_TEMPLATE/good_first_issue.yml new file mode 100644 index 0000000..30ce463 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/good_first_issue.yml @@ -0,0 +1,67 @@ +name: Good first contribution +description: A small, self-contained task that does not need Android or an SDK +title: "[Good first issue]: " +labels: [good first issue, help wanted, documentation] +body: + - type: markdown + attributes: + value: | + This form is for tasks that can be finished without an Android device, an + SDK or deep knowledge of the renderers. If you are new to the project, + read [Contributing](../blob/main/docs/CONTRIBUTING.md#first-contribution-in-ten-minutes) + first: it names the files, the commands and what a review looks for. + + Claim a task by commenting on it, so two people do not write the same + fix. Nothing here needs permission from a maintainer to start. + - type: dropdown + id: kind + attributes: + label: What kind of task is it + options: + - Documentation (README, docs/, docstring, example) + - Test (a behaviour that should be pinned down) + - Small bug in a preview (web, Tk, text) + - Error message or hint that could be clearer + - Template or scaffold example + - Translation or wording + validations: + required: true + - type: textarea + id: problem + attributes: + label: What is wrong or missing today + description: Quote the current text or the current output if you can. + validations: + required: true + - type: textarea + id: expected + attributes: + label: What "done" looks like + description: One or two sentences. A docstring, a test name, the new message. + validations: + required: true + - type: input + id: files + attributes: + label: The files involved + description: Best guess is fine; a maintainer will confirm before you start. + placeholder: pymobile/core/ui/components.py, README.md + - type: dropdown + id: skills + attributes: + label: What it needs + options: + - Python only + - Documentation only + - Python and a browser (web preview) + - Python and a display (Tk preview) + - Java (needs the SDK, not a first task) + validations: + required: true + - type: markdown + attributes: + value: | + **Checks before opening a pull request:** `python -m pytest`, + `python -m ruff check pymobile`, `python -m mypy pymobile`. If a check + fails for a reason unrelated to your change, say so in the pull request + instead of hiding it. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..e5b594d --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,30 @@ +version: 2 + +# Actions pinned by SHA in `.github/workflows/` are updated by the +# `github-actions` group; the comment next to each pin names the release it +# came from, so a diff shows "v4.1.7 → v4.2.1" and not a bare hash. +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + day: monday + groups: + github-actions: + patterns: ["*"] + commit-message: + prefix: "ci" + labels: ["dependencies", "ci"] + + # Runtime and test dependencies. `[dev]` extras carry pytest, ruff and mypy, + # so a broken release of one of them arrives as a PR instead of as a red + # build on main. + - package-ecosystem: pip + directory: / + schedule: + interval: weekly + day: monday + open-pull-requests-limit: 5 + commit-message: + prefix: "deps" + labels: ["dependencies"] diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 1aa47ec..be979f6 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -15,8 +15,8 @@ jobs: runs-on: ubuntu-latest environment: pypi steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0 with: python-version: "3.13" - run: python -m pip install --upgrade pip build twine @@ -31,7 +31,7 @@ jobs: # Never push an artifact whose metadata PyPI would reject anyway. - run: python -m twine check --strict dist/* - name: Publish to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 + uses: pypa/gh-action-pypi-publish@aef6c9b6e301dc803e1bc9133e9ce67ae9b0906b # v1.14.3 with: # A version can be published by hand before the release is cut; do # not fail the workflow over files that are already on PyPI. diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index 66bf03b..982c9c1 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -16,8 +16,8 @@ jobs: matrix: python: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"] steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0 with: python-version: ${{ matrix.python }} cache: pip @@ -34,8 +34,8 @@ jobs: name: Windows Python 3.14 (venv) runs-on: windows-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0 with: python-version: "3.14" - run: python -m venv .windows-venv @@ -57,8 +57,8 @@ jobs: matrix: python: ["3.15"] steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 + - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0 with: python-version: ${{ matrix.python }} allow-prereleases: true @@ -75,7 +75,7 @@ jobs: - if: hashFiles('tools/release_audit.py') != '' run: python tools/release_audit.py dist --output release-audit.json - name: Upload package audit - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 with: name: package-audit-py${{ matrix.python }} path: | @@ -86,11 +86,63 @@ jobs: - name: Upload Android diagnostics if: always() - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 with: name: android-device-smoke-diagnostics path: | device-logcat.txt device-logcat-full.txt - examples/device-smoke/build/*.apk if-no-files-found: warn + + android-build: + # C6: nothing used to build for Android in CI, so a change to the Java + # renderer, the manifest or the resource pipeline was only noticed by + # whoever ran `build --native` by hand. This produces a real signed APK and + # a real `.aab` on every push, and validates the bundle with bundletool. + name: Android APK + AAB + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + - uses: actions/setup-java@d1374f8ac74474200d16ef8ecee22c7ae7a51880 # v6.3.0 + with: + distribution: temurin + java-version: "17" + - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0 + with: + python-version: "3.14" + cache: pip + - name: Install the package and the Android SDK + run: | + python -m pip install --upgrade pip + python -m pip install -e ".[dev]" + python -m pymobile setup-sdk + # bundletool is what proves an .aab is uploadable; validate is not + # something the ZIP layout can stand in for. + curl -sSLo "$HOME/bundletool.jar" \ + https://github.com/google/bundletool/releases/download/1.18.1/bundletool-all-1.18.1.jar + echo "PYMOBILE_BUNDLETOOL=$HOME/bundletool.jar" >> "$GITHUB_ENV" + - name: Build an app with the Java renderer + run: | + python -m pymobile init --name CiApp -t list /tmp/ci-app + cd /tmp/ci-app + python -m pymobile check + python -m pymobile build --native --bundle --verbose + # The artifact name comes from the project name (`CiApp` -> ciapp), + # so glob it instead of guessing: a hard-coded name broke this job + # while the build itself had succeeded. + ls -l apk/ + python -m pymobile size apk/*.apk + - name: The APK must declare the level Play requires + run: | + cd /tmp/ci-app + java -jar "$PYMOBILE_BUNDLETOOL" dump manifest --bundle apk/*.aab \ + | tee manifest.txt + grep -q 'targetSdkVersion="36"' manifest.txt + grep -q 'supportsRtl="true"' manifest.txt + - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0 + with: + name: android-artifacts + path: | + /tmp/ci-app/apk/*.apk + /tmp/ci-app/apk/*.aab + if-no-files-found: error diff --git a/CHANGELOG.md b/CHANGELOG.md index 91d1411..f752df1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,252 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [semantic versioning](https://semver.org/). +## [0.15.0] — 2026-11-14 + +### Added + +- **Google Play is reachable now.** `build --native --bundle` writes an `.aab` + next to the APK and validates it with bundletool, and the default + `target_sdk` is 36 — the level Play requires for new apps and updates from + 31 August 2026. Without either, an app built with PyMobile could not be + uploaded at all. +- **Certificate pinning:** `[network.pins]` in `pymobile.toml` pins a domain to + the certificates you list, which also stops the app trusting the *device's* + user-installed roots — the usual way a corporate proxy or a "Wi-Fi inspector" + app reads HTTPS traffic. Only the domains you name are pinned; everything else + keeps the system trust store. A malformed pin is refused when the file is + read, not when the app starts on a phone. +- **Several ABIs in one APK:** `abis = ["arm64-v8a", "x86_64"]` now really + packages both. Before, only the first was built and the second was silently + dropped, so the same file could not run on an emulator; the build now says + what it put in and how much bigger that made it. +- **A tutorial and a beginner page:** `docs/TUTORIAL.md` goes from an empty + project to an installable APK in fifteen minutes, ending with a working note + list, and `docs/BEGINNER-MISTAKES.md` covers the five mistakes everyone makes + first. Both are checked by tests, so a renamed widget breaks CI instead of a + newcomer's first hour. +- **Android in CI:** every push now builds a signed APK and an `.aab`, validates + the bundle with bundletool and asserts the manifest declares + `targetSdkVersion="36"` and `supportsRtl`. A change to the Java renderer, the + manifest or the resource pipeline used to reach `main` unbuilt. +- **System theme, keyboard and back on device:** the window now reports what + the system did instead of only what the app asked for. A light/dark switch + arrives as a `theme` event (`app.on("app:system-theme", …)`, or pass + `follow_system_theme=True` to `App` to switch palette automatically), the + keyboard height arrives as `app:insets`, and the startup screen follows the + system theme instead of flashing white in dark mode. +- **Android bundle:** `build --native --bundle` writes an `.aab` next to the + APK, which is the only artifact Google Play accepts for new apps and updates. + The bundle is assembled from the same manifest, `classes.dex`, assets and + native libraries the APK used (so the two cannot drift), and + `bundletool validate` plus `build-apks --mode=universal` run on it whenever a + JDK and `~/.andro/bundletool.jar` (or `PYMOBILE_BUNDLETOOL`) are available — + the build then names the universal APK to install before uploading. No + bundletool: the file is still written, and the warning says it was not + verified instead of failing a release pipeline on a machine without Java. +- **App state across a destroyed window:** the Activity no longer takes the + interpreter with it. `onDestroy` hands Python a `__lifecycle__`/`stop` event, + `Screen.on_stop()` runs, the tracked widget state (a field's text, a switch, + a dropdown) is written to the app store, and the next `onCreate` resumes the + **same** interpreter with `Screen.on_start()` — every screen, counter, job and + timer still there. A finished app or a task the system removes still ends + Python. `App.save_state()` and `App.restore_state()` are public for the + application's own data. +- **Styling:** `Style` grew from 18 fields to 29. `border=Border(...)` draws one + to four edges inside the widget, `gradient=Gradient(...)` fills the surface + with two or more stops in eight directions, and `opacity` fades a widget and + its children. Typography gained `line_height`, `letter_spacing`, + `font_family`, `text_transform`, `text_overflow` and `max_lines` (`max_lines` + implies an ellipsis), plus `underline` and `strikethrough`. Every field is + rendered by the web preview, the PNG mockup, the Tk GUI and the Java views. +- **State:** `Value` and `Computed` are exported from `pymobile`. A value + notifies its subscribers only when it actually changes, supports `bind`, + `bind_get`, `subscribe`, `update`, `toggle` and arithmetic, and a computed + value recalculates as soon as any source changes. A self-referential computed + returns its previous value instead of recursing. +- **Text input:** `TextInput(keyboard=..., ime_action=..., on_submit=...)`. + `keyboard` covers text, email, phone, number, decimal, url, password, search + and multiline; `ime_action` covers done, go, next, search, send, previous and + none, and requires `on_submit`. The web preview renders the matching `type` + and `inputmode` and submits on Enter. +- **Animations:** `visibility_animation` accepts `fade_scale`, `fade`, `scale` + and `slide`, and screens gained the `fade_through`, `slide_up` and `slide_down` + transitions. +- **Links:** `Link` accepts only `http`, `https`, `mailto`, `tel` and relative + paths. Other schemes raise `ValueError`. +- **Previews:** the loopback preview refuses requests whose `Host` header is not + a loopback name, unless `allow_hosts=(...)` or `--allow-host` names it, and it + always requires its token when it is bound to `0.0.0.0`. +- **Icons:** `drawing.ICON_NAMES` grew from 22 to 72, and every name has shapes + and a text-preview glyph. +- **Icons:** an adaptive icon ships next to the square one — a blurred + background layer, the artwork inside the 66/108 safe zone, a monochrome layer + Android 13+ tints to the theme, and `mipmap-anydpi-v26/ic_launcher.xml` (plus + `ic_launcher_round.xml`). Launchers that mask icons used to shrink the square + into a white tile. The manifest now points at `@mipmap/ic_launcher`; the + legacy squares answer to the same name, so Android 7 is unchanged. +- **Debugging:** `build --native --debug` marks the APK `android:debuggable`, + which is what `adb shell run-as`, Layout Inspector and the Android Studio + debugger refuse to attach without. It is refused together with `--keystore` + (a debuggable artifact must never be the one a store ships) and is part of + the cache key, so a debug APK is never reused for a normal build. +- **Contributing:** `docs/CONTRIBUTING.md` opens with "First contribution in ten + minutes" (checkout, the one command that runs the suite, where a change goes, + what review looks for), a table of good first tasks and a five-step checklist + for adding a widget that separates the steps needing no Android tooling from + the Java one. A `Good first contribution` issue form and the repository's + contact links were added with it. +- **Test:** `pymobile/tests/test_renderer_parity_between_python_and_java.py` + compares the capability table, the web and Tk preview tables and + `ViewBuilder.java`, and checks that every native call the framework makes has + a Java entry point. A widget type the phone would silently drop now fails CI + instead of shipping. +- **Docs:** every public function and method has a docstring. The CLI's + user-error reporting moved to `pymobile/cli_errors.py` and its `build` command + to `pymobile/cli_build.py`, so `pymobile/cli.py` (844 lines) stays inside the + 1000-line guard its own test suite enforces; `pymobile.cli.cmd_build` and + `pymobile.cli.BuildPipeline` remain the names to use or replace. + +### Changed + +- **`--minimal-stdlib` is worth using now:** it drops tkinter, idlelib, + ensurepip, lib2to3, asyncio, multiprocessing and the rest of the modules a + phone app cannot need — 709 → 514 packaged files. The default is unchanged, so + an existing project keeps every import it had; try it, run + `pymobile check`, and compare `pymobile size`. +- **Android layout:** the manifest sets `supportsRtl`, and every margin is + applied as start/end, so Arabic and Hebrew screens mirror instead of keeping + Western spacing. +- **Android target:** the default `target_sdk` is 36 and `setup-sdk` installs + `platforms;android-36`, because Google Play requires API 36 for new apps and + updates from 31 August 2026. The toolchain now compiles against that same + platform (`toolchain.find_toolchain()`), instead of the previous split where + the manifest declared one level and the classes were built against another. + A project that keeps `target_sdk = 35` still builds and is still warned about. +- **Supply chain:** every GitHub Action in `.github/workflows/` is pinned to a + commit SHA with the release in a comment (`# v4.1.7`), and a Dependabot + configuration updates the pins and the Python dependencies weekly. A tag is a + moving target; a repository that trusts one hands its token to whoever owns + the action. +- **Storage:** `Storage(deferred=True)` batches writes — one file write per + burst instead of one per `set` (1 ms per write on a store with 5000 keys, + 12.9 s for 4000 writes). `save()`, `flush()`, `transaction()` and interpreter + exit all write immediately; the default still writes on every change. +- **ModelStore:** `find`, `count` and `get_by` filter on stored records with a + dict, a `Q` expression (`&`, `|`, `~`) or a predicate, with `order_by`, + `limit` and `offset`. An id index brings 1000 `put` calls from 5.2 s to + about 1.3 s, and a store that outgrows one JSON array logs a warning. +- **HTTP:** connections are kept alive and pooled per host instead of opening + a socket (and a TLS handshake) per request; `close()`/`with` release them and + `App.stop()` closes `app.http`. +- **HTTP:** requests can be gzipped (`compress=True`) and sent as + `multipart/form-data` (`files=`). +- **Jobs and async HTTP:** one-shot work runs on a bounded worker pool + (`max_workers`, twice the CPU count by default) instead of a thread per job; + repeating jobs keep their own thread. Worker threads start on first use. +- **Previews:** the two giant renderers are split by widget family. The browser + renderer's `_render_html_node` (524 lines, 38 branches) is now a 76-line + dispatcher over one `_html_*` helper per family (`_html_list`, `_html_flow`, + `_html_text_field`, ...) chosen through a `_HTML_RENDERERS` table, and the Tk + renderer's `GuiPreview._build` (547 lines, 34 branches) is a 50-line + dispatcher over one `_build_*` method per family (`_TK_BUILDERS`). A new + widget type is one helper plus one table entry, and both previews still draw + exactly the same markup and widget trees as before. + +### Added + +- **HTTP:** `stream=True` with `iter_content()` downloads a body in chunks + without holding it in memory, and still follows redirects. +- **HTTP:** `timeout_budget` bounds a whole call — retries and backoff included + — where `timeout` bounds one attempt (`timeout=2, retries=3` used to take + 8.4 s). +- **Secrets:** `app.save_secret()`, `app.load_secret()` and + `app.delete_secret()` keep a value encrypted with an Android keystore key + (AES-GCM) instead of in the plain JSON store. +- **Links:** `Bridge.open_url()` accepts only `http`, `https`, `mailto` and + `tel`; other schemes raise `ValueError` instead of reaching `Intent.parseUri`. +- **Logging:** `redact_url()` masks credential query parameters, and the HTTP + client uses it, so a token in a URL no longer reaches the debug log. + +### Fixed + +- A back gesture on the root screen did nothing: the callback was registered for + the whole lifetime of the window, so the system's own "leave the app" never + ran and the gesture was swallowed. It is registered only while the app has a + screen to go back to (the frame's `chrome.can_go_back`). +- Images were decoded on the UI thread at full size. A camera JPEG is 12–48 MP, + which stalled a frame and, past a certain megapixel count, was an + `OutOfMemoryError` rather than a stutter. Decoding now runs on a worker + thread with `inSampleSize` computed from the view, applies the EXIF rotation, + and drops a result that lost the race against a newer source. +- An edge-to-edge window (the default from Android 15) drew content under the + status and navigation bars and let the keyboard cover the focused field; the + root container now applies the system-bar, cutout and IME insets, and + `adjustResize` shrinks the window for the keyboard. +- `Image(source="https://…")` was accepted everywhere and then drawn as an empty + box on the phone; a native build now warns once per source that the device + renderer loads local files only. +- Three deprecated Android calls are gone: `setAudioStreamType` → + `setAudioAttributes`, `scaledDensity` → `density × fontScale`, and the + legacy `getSystemWindowInset*` reads now sit behind a single helper that uses + typed insets from API 30. +- The two stores describe their `migrations=` keys in the same words and the + error messages point at each other. The keys were never actually different — + both are "the stored version this step upgrades" — but the `ModelStore` + docstring said the opposite, which is worse than a real mismatch. +- A window destroyed for a reason unrelated to the user leaving — back on the + root screen then re-open, a configuration change outside `configChanges`, a + low-memory UI restart — used to restart the app from `main.py` and lose + everything typed, counted or navigated. The interpreter now stays alive and + the new window adopts it; input that arrives after the stop is dropped rather + than handled by an app that has left the screen. +- Credential files stay out of the APK: `.netrc`, `.npmrc`, `.pypirc`, + `credentials.*`/`secrets.*`, `id_rsa*`, `*.pem`, `*.p12`, `*.pfx`, `*.ovpn` + and the contents of a `secret/` folder next to `secrets/`. The build lists + every file it kept out and why, instead of packaging it — the 3.1 audit found + a plain `secret/notes.txt` inside an APK. +- A response that arrives compressed despite the request is decoded, so + `response.text` is text rather than gzip bytes. +- A truncated body reads as `NetworkError` ("Could not read") instead of + leaking `IncompleteRead`. +- `pymobile run` reports a mistake in the app's own code with the file and the + line (`main.py:6`) and a hint, instead of "unexpected error" and a request to + re-run with `--verbose`; `pymobile check` prints the same location. +- A `Checkbox` with a label is no longer reported as missing an accessibility + label, and the text preview shows the label instead of dropping it. +- `SegmentedButtons` accepts the same option shapes as `Dropdown` and + `RadioButtons`, including a mapping and a list of single-item mappings. +- Widgets created in `build()` keep what the user typed across `Screen.rebuild()`: + `TextInput`, `Checkbox`, `Switch`, `Slider`, `Dropdown`, `RadioButton` and + `SegmentedButtons` restore their state by widget id. +- A screen whose `__init__` forgot `super().__init__()` says so, with the three + lines that fix it, instead of `'Home' object has no attribute '_root'`. An + ordinary missing attribute on a set-up screen still raises the plain + `AttributeError('titel')`. +- A non-widget child names the real mistake: `Column(Label("a"), "text")` is a + `TypeError` about a string inside a `Column`, with the widget to write + instead, and no longer an `AttributeError` about `_parent` three frames + later. Nested lists, `None` (usually a conditional expression) and a factory + passed without parentheses each get their own sentence; a bad list inside a + list keeps the older `children must be Widget instances` wording. +- `pymobile check` reports a handler written with parentheses + (`on_press=self.on_tap()`, `on_click=...`) at its file, line and column: + the call runs once while the tree is built, so the button did nothing when + tapped and nothing said why. `lambda`, `partial` and plain method references + are untouched. +- `pymobile doctor` measures free space where the SDK is installed + (`PYMOBILE_SDK_HOME`, `~/.andro` by default) instead of the project folder, + so a small home directory is reported before the download fails, and the + hint names the variable that moves the install. +- A structural build writes `demo-0.1.0-debug.apk` and a native build keeps + `demo-0.1.0.apk`. They used to share one name, so a quick structural build + silently left a non-installable file where `pymobile install` looked for the + APK, and the install failed with a signature error that never named the + cause. +- A `target_sdk` newer than the platform `setup-sdk` installs (`android-35`) + now warns during the build: the APK still compiles against 35, so the newer + APIs are not available and the behaviour switches for it do not apply. + ## [0.14.0] — 2026-11-11 ### Added @@ -51,7 +297,7 @@ the project uses [semantic versioning](https://semver.org/). `classes.sources.json` records the new source hashes. - The Android renderer list in the native build includes `SignaturePadRenderer.java`. - `pymobile` exports the new widgets from the package root. -- The version is 0.14.0 in `pyproject.toml`, in `pymobile.__version__` and in the +- The version is in `pyproject.toml`, in `pymobile.__version__` and in the documentation. ### Fixed @@ -302,9 +548,9 @@ All four are built from existing widgets, so they need no Android-side change. ### Added -- **Audit regression tests.** `pymobile/tests/test_handoff_findings.py` pins +- **Audit regression tests.** `pymobile/tests/test_launcher_permissions_and_audio.py` pins each of the fixes above with a reproducer, and - `pymobile/tests/test_prebuilt_api_audit.py` compares the shipped bridge + `pymobile/tests/test_prebuilt_bridge_api.py` compares the shipped bridge binaries against the `module_methods` table of `pymobile_jni.c`, failing CI when a prebuilt trails the source — the drift that hid the 21 missing native methods. @@ -956,7 +1202,7 @@ All four are built from existing widgets, so they need no Android-side change. - Regression tests for all of the above: Cyrillic-plus-digit slugs, digit-leading packages, digit-residue APK names, warning-free builds of scaffolded projects, and `exclude` patterns silencing the "not packaged" warning - (`test_compiler.py`, `test_config.py`, `test_audit_platform_fixes.py`). + (`test_compiler.py`, `test_config.py`, `test_cache_assets_and_launcher.py`). ## [0.9.1] — 2026-10-03 @@ -970,17 +1216,16 @@ All four are built from existing widgets, so they need no Android-side change. or the `X-PMB-Token` header), only `/`, `/state` and `/event` are routed, `POST /event` requires `application/json` and at most 64 KiB, unknown writes answer 403/404/413/415, and the responses carry `X-Frame-Options: DENY`. - (PM-28) - **`X-API-Key` (and every other credential header) was forwarded across origins** when a response redirected elsewhere. Credentials are now dropped whenever the origin changes, and may only be sent to hosts listed in the new `forward_credentials_hosts`; extra header names can be named through `credential_headers=`, and a bare string there is a `TypeError` instead of a - silently misread iterable of characters. (PM-05) + silently misread iterable of characters. - **Signing passwords no longer appear in the process list.** `apksigner` is invoked with `--ks-pass env:…` / `--key-pass env:…` instead of literal arguments, and a release keystore without a password is a hard error rather - than a silent fallback to the debug key. (PM-17) + than a silent fallback to the debug key. ### Fixed — build and packaging @@ -990,10 +1235,10 @@ All four are built from existing widgets, so they need no Android-side change. now covers the build mode, the signer (`::`), the framework inputs and the configuration digest; the cache entry records the mode and signer it belongs to and is only reused when they match the request. - No password ever reaches the cache file. (PM-17) + No password ever reaches the cache file. - **`BuildResult.native` was `False` for artifacts that came from the cache**, so a native build reused from the cache was reported as a structural - preview. The cache now stores that flag along with the entry. (PM-18) + preview. The cache now stores that flag along with the entry. - **A custom entry point disagreed with the packaged launcher.** `MainActivity` and the JNI runner hard-coded `main.py` while the builder packaged whatever `entrypoint` said, and `--optimize` (bytecode) made it worse. The single @@ -1001,31 +1246,30 @@ All four are built from existing widgets, so they need no Android-side change. `entrypoint_type=py|pyc`), which the launcher reads; the JNI runner falls back to the `.pyc`, and paths are passed as arguments rather than spliced into code. An older launcher dex without those bytes gets a generated shim - instead of a hard-coded name. (PM-24) + instead of a hard-coded name. - **The prebuilt bridges were linked for 4 KB pages** (`p_align = 0x1000`), which Android 15+ refuses to map. Both `libpymobile.so` were rebuilt with `-Wl,-z,max-page-size=16384` (PT_LOAD aligned to `0x4000`); the build checks it with `_check_page_alignment()`, and `zipalign` now uses `-p 4 -P 16` on - build-tools 35+ with an `-f 16384` fallback below that. (PM-26) + build-tools 35+ with an `-f 16384` fallback below that. - **Reinstalling a new build with the same `versionCode` kept the old Python code.** Android will reinstall over an equal version code without touching the app's data, so `assets/app/main.py` from the previous build stayed in place. `pymobile.properties` now carries `payload=` and the runtime stamps the extracted payload with `-`, so a changed payload is re-extracted even when the version code is not bumped. - (PM-29) - **The bundled launcher icon was not part of the build fingerprint**, so replacing it changed nothing in the cache key: a project without its own icon could keep an "up to date" APK still carrying the old icon. The default icon - is now a framework input like the dex and the bridge. (PM-17 family) + is now a framework input like the dex and the bridge. - **Assets could disappear silently.** The packaged extension set is fixed in the collector, so an app reading `assets/data.csv` shipped an APK without the file and only found out on the device. `asset_suffixes = [".csv", …]` extends - the set, and the build warns about the extensions it left out. (PM-20) + the set, and the build warns about the extensions it left out. - **`JAVA_HOME` pointing at a macOS JDK bundle was rejected**, because the JDK lives in `Contents/Home`. One `normalise_java_home()` now serves `JAVA_HOME`, bundled distributions, the `~/.android` discovery and `which javac`, and - requires a real `bin/javac`. (PM-19) + requires a real `bin/javac`. ### Fixed — application lifecycle and UI @@ -1033,61 +1277,59 @@ All four are built from existing widgets, so they need no Android-side change. one.** Each rendered tree now carries the generation of the screen it was built from and wire ids are `":"`, so late taps are dropped instead of being applied to whatever widget now owns that id. The public - `id` in `Screen.to_dict()` stays unqualified. (PM-14) + `id` in `Screen.to_dict()` stays unqualified. - **A `disabled` text field accepted changes.** Both `TextInput` and `MultiLineTextInput` (and with them the search field) took text from the desktop backend and the web preview while disabled. The gate now lives in `_ui_set_value()` and drops interactive events for disabled widgets in the dispatcher; assigning `value` from Python still works, which is how a - program updates a read-only field. (PM-15) + program updates a read-only field. - **A reused plain subtree stopped reacting after `refresh()`**: the rebuilt tree linked its own containers but the adopted branch kept its old parents. - `Screen._adopt()` restores the links from the structure. (PM-11) + `Screen._adopt()` restores the links from the structure. - **An exception in a user hook aborted the rest of the cleanup.** A raising `on_unmount` left later screens undisposed; `dispose()`/`discard()` now run - under `try`/`finally` and every screen is processed. (PM-12) + under `try`/`finally` and every screen is processed. - **Duplicate explicit ids were only caught on the first build.** Adding a widget with an id that already exists (from a rebuild, a dialog, a reused container) silently produced two owners. `Container.add()` now runs `_check_new_ids()` and raises `PyMobileError`, leaving the tree untouched. - (PM-13) - **`activate_all` remembered only the most recently registered app**; it is now a `dict[str, WeakSet[App]]`, so plugin hot-reloads reach every live app - without keeping dead ones alive. (PM-16) + without keeping dead ones alive. - **`stop()` before the first `run()` skipped `jobs.shutdown()`**, leaving the - executor's threads behind. (PM-09) + executor's threads behind. - **Leaving the event loop did not finish the `App`**: `running` stayed `True`, so a later `stop()` was a no-op. `App` tracks `_stopped` and always runs - `stop()` in `finally`. (PM-10) + `stop()` in `finally`. ### Fixed — HTTP, storage and jobs - **`HttpClient(cache=Storage(...))` built a second `Storage` over the same file**, so settings and cache overwrote each other. `HttpCache(storage=…)` now reuses the instance, and passing `path` *and* `storage` raises - `ValueError`. (PM-01) + `ValueError`. - **`transaction()` did not roll the disk back** when the body called `save()`: the write went out immediately and survived the rollback. Saves inside a - transaction are deferred to the commit. (PM-02) + transaction are deferred to the commit. - **`Storage.set()` left the value in memory when the disk write failed**, serving a value that would vanish on restart; the in-memory copy is now - rolled back too. (PM-03) + rolled back too. - **A cached response lost its charset**: a `iso-8859-1` page came back as - UTF-8 garbage. The encoding travels with the cached entry. (PM-04) + UTF-8 garbage. The encoding travels with the cached entry. - **`cancel()` did not stop a callback that was already queued for delivery**: `HttpFuture` and `JobHandle` re-check cancellation when the callback runs. - (PM-06) - **`then()` handled an exception differently before and after completion** (raised vs logged). One policy now: the failure is logged and reported - through the future, never thrown into an unrelated caller. (PM-07) + through the future, never thrown into an unrelated caller. - **Duplicate named repeating jobs lost their tracking**, so they could not be cancelled any more. `JobManager._track()` keeps one live job per name and - cancels the previous one with a warning. (PM-08) + cancels the previous one with a warning. - **`--no-ssl` broke even offline apps**: `core/net/http.py` imported `ssl` at module import, so a build without OpenSSL raised before doing anything. The import is lazy, `NetworkError` points at the flag, and the APK ships without `libssl`/`libcrypto` while the CA bundle is written to - `assets/python/etc/ssl/cert.pem` for the parts that do need TLS. (PM-23) + `assets/python/etc/ssl/cert.pem` for the parts that do need TLS. ### Fixed — Android runtime and JNI @@ -1097,17 +1339,17 @@ All four are built from existing widgets, so they need no Android-side change. bridge now converts UTF-16 ↔ UTF-8 itself (`jstring_to_utf8` / `utf8_to_jstring`, invalid sequences become U+FFFD) in both directions, the event queue carries byte lengths and `Py_BuildValue("(s#s#s#)")` passes them - to Python, so a string may contain NUL. (PM-25) + to Python, so a string may contain NUL. - **A startup error was reported as success.** A failing entry point returned 0 from the JNI runner, so the process looked healthy and the user saw an empty screen with no error. `run_entry_point()` keeps the code of `SystemExit`, turns any other exception into exit code 1 with a traceback in logcat, and `MainActivity` shows an error placeholder instead of the empty - first screen. (PM-27) + first screen. - **`started = True` survived a failed runtime preparation**, so a retry after a failed extraction or import did nothing. `PythonRuntime` is a state machine (`IDLE`/`PREPARING`/`RUNNING`/`FAILED`) that can be retried after a - recoverable failure. (PM-30) + recoverable failure. - **`py_next_event` could report "no more events" on a spurious wake**: the condition wait was wrapped in `if`, not `while`, so a wake-up without a queued event ended the loop. It is a predicate loop now, and `ETIMEDOUT` @@ -1120,21 +1362,20 @@ All four are built from existing widgets, so they need no Android-side change. - The README counter example reset its state inside `build()`, which the framework itself calls on every refresh — the counter went back to zero. - State lives in `__init__` and `build()` only reads it. (PM-21) + State lives in `__init__` and `build()` only reads it. - The README suggested mutating a `Style` in place, which is a frozen dataclass and raises `FrozenInstanceError`; the example now uses - `dataclasses.replace()`. (PM-22) + `dataclasses.replace()`. ### Added -- `asset_suffixes` in `pymobile.toml` — extra file extensions to package - (PM-20), with a warning that names the extensions that were skipped. +- `asset_suffixes` in `pymobile.toml` — extra file extensions to package, with a warning that names the extensions that were skipped. - `pymobile run --web --host HOST` — explicit opt-in for exposing the preview - beyond loopback, with a warning and a session token (PM-28). + beyond loopback, with a warning and a session token. - `WebPreview(host=…, port=…, token=…)`, `HttpClient(credential_headers=…, - forward_credentials_hosts=…)`, `Storage`/`HttpCache` sharing (PM-05, - PM-01, PM-28). -- Regression tests: `pymobile/tests/test_audit_platform_fixes.py` (disabled + forward_credentials_hosts=…)`, and one `Storage` that an `HttpCache` can + share instead of keeping a second copy of the same file. +- Regression tests: `pymobile/tests/test_cache_assets_and_launcher.py` (disabled inputs, cache identity, build metadata, asset suffixes, launcher and JNI sources, shipped artifacts, web-preview security, JDK discovery) and `pymobile/tests/test_jni_utf8.py`, a host harness that compiles the real @@ -1146,21 +1387,22 @@ All four are built from existing widgets, so they need no Android-side change. phone glyph with a `>_` prompt and the wordmark) instead of the stock Android robot. It is still only the fallback: `icon = "assets/icon.png"` in `pymobile.toml` overrides it, and `pymobile build --icon logo.png` per run. -- `App.stop()` is now idempotent and always runs after the loop (PM-09, - PM-10); `BuildResult.native` describes the artifact rather than the code - path (PM-18); `Screen.to_dict()` keeps the public ids it documented (PM-14). +- `App.stop()` is now idempotent and always runs after the loop; + `BuildResult.native` describes the artifact rather than the code path; + `Screen.to_dict()` keeps the public ids it documented. - The single build cache file stores metadata (mode, signer, icon, payload) - alongside the fingerprint (PM-17, PM-18, PM-29). + alongside the fingerprint, so a cached rebuild cannot pick the wrong key or + the wrong icon. - `pymobile.properties` inside the APK gained `payload=…` next to - `entrypoint`, `entrypoint_type` and `optimize` (PM-24, PM-29). + `entrypoint`, `entrypoint_type` and `optimize`. - `zipalign` is called with `-P 16` where the build tools understand it and with the `16384` alignment argument otherwise; the fallback is silent apart - from a debug log (PM-26). + from a debug log. - A release build that names a keystore but no password now raises `PyMobileError` instead of quietly signing with the debug key; the per-app debug keystore keeps living in `~/.pymobile/keystores/-debug.jks` (`PYMOBILE_KEYSTORE_DIR` moves - it, which is what CI wants) (PM-17). + it, which is what CI wants). ## [0.9.0] — 2026-10-01 @@ -1215,7 +1457,7 @@ P.S. Today is the Python 3.15 release unchanged (the rules read the same variables it defines). - **`DatePicker.set_value()` and `TimePicker.set_value()`** no longer fire `on_change` while a tree is being built — they were the last two components - missing the `in_build_scope()` guard of BUG-25. `RadioGroup.select()` and + missing the `in_build_scope()` guard. `RadioGroup.select()` and `BottomNavigation.select()` had the same gap and got the guard too. - **`pymobile init`** writes a `main.py` that creates its widgets inside `build()` (state still lives in `__init__`), matching *Updating the screen*; @@ -2077,7 +2319,7 @@ two pieces of behaviour behind them are documented. `resources/android/prebuilt/arm64-v8a/libpymobile.so` out of git, so a fresh clone could not run `pymobile build --native`. The path is now excluded from the rule. -- **`pytest` failed at collection on a fresh clone.** `test_release_audit.py` +- **`pytest` failed at collection on a fresh clone.** `test_release_artifact_hashes.py` imported `tools.release_audit`, and `tools/` is gitignored; the import is now skipped when unavailable instead of breaking the whole run. diff --git a/README.md b/README.md index f96cb7b..db19744 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Write a declarative UI, run one command, install the APK on your phone. > ### ⚠️ Alpha software — known bugs, actively being fixed > -> PyMobile is at **0.14.x** and is still in alpha. It builds and signs real, +> PyMobile is at **0.15.x** and is still in alpha. It builds and signs real, > installable APKs today, but the API can change between minor releases and > there are known bugs. I am actively working on them: fixes ship in > every release — see the @@ -30,7 +30,7 @@ Write a declarative UI, run one command, install the APK on your phone. > open. > > Good fit for personal apps, internal tools, prototypes and learning. If you -> depend on it, pin an exact version (`pymobile-framework==0.14.0`) and read the +> depend on it, pin an exact version (`pymobile-framework==0.15.0`) and read the > changelog before upgrading. What may change, and how much notice you get, is > written down in the > [versioning and deprecation policy](#versioning-and-deprecation-policy). Bug @@ -82,7 +82,6 @@ the JDK for you. ## Table of contents -- [What's new in 0.14.0](#whats-new-in-0140) - [Why PyMobile](#why-pymobile) - [Build diagnostics and APK size](#build-diagnostics-and-apk-size) - [Third-party Python packages (experimental)](#third-party-python-packages-experimental) @@ -110,6 +109,7 @@ the JDK for you. - [Files, audio, the clipboard and sharing](#files-audio-the-clipboard-and-sharing) - [Permissions](#permissions) - [HTTP requests](#http-requests) +- [Secrets](#secrets) - [Languages](#languages) - [Events](#events) - [Timers](#timers) @@ -133,24 +133,6 @@ the JDK for you. --- -## What's new in 0.14.0 - -Version 0.14.0 adds widgets for QR codes, tags, countdowns, Markdown, drawing -and Bluetooth data, plus the Bluetooth permissions. The full list is in the -[changelog](https://github.com/Maksum867/PyMobile/blob/main/CHANGELOG.md#0140--2026-11-11). - -- **New widgets:** [`QRCode`](#qrcode), [`TagInput`](#taginput), - [`Countdown`](#countdown), [`MarkdownText`](#markdowntext) and - [`SignaturePad`](#signaturepad). -- **Bluetooth widgets:** [`SignalStrength`, `BatteryLevel`, `Radar` and - `ConnectionStatus`](#bluetooth-widgets). They show values your app provides; - the framework does not scan for devices yet. -- **Bluetooth permissions:** `BLUETOOTH`, `BLUETOOTH_ADMIN`, `BLUETOOTH_SCAN` and - `BLUETOOTH_CONNECT`. See [Bluetooth](#bluetooth) under Permissions. -- **Install the QR extra** with `pip install "pymobile-framework[qr]"`. - ---- - ## Why PyMobile | | | @@ -1372,6 +1354,60 @@ Style( CSS and `EdgeInsets.symmetric` read it in opposite orders, so write `EdgeInsets.symmetric(horizontal=16, vertical=8)` instead. +### Borders, gradients and opacity + +```python +Style( + border=Border(width=2, color="#C62828", sides="bottom"), # a rule under a row + gradient=Gradient("#3F51B5", "#1A237E", direction="to_bottom_right"), + opacity=0.6, # 0 invisible, 1 opaque + corner_radius=12, +) +``` + +`Border` draws **inside** the widget's box, the way Android's +`GradientDrawable.setStroke` does, so adding one never shifts a layout. +`Border(color="#E0E0E0")` is a hairline; `sides="top right"` restricts the +stroke to a subset. `Border(width=0)` removes it. + +`Gradient` takes a start and an end colour, an optional middle one +(`Gradient("#FFFFFF", "#3F51B5", "#E8EAF6")`), or the full control of +`stops=((0.0, "#FFFFFF"), (0.6, "#E8EAF6"), (1.0, "#3F51B5"))`. Stops must +reach 0 and 1 — a ramp that stops halfway is stretched, which hides the +mistake. `direction` is one of `to_bottom` (the default, and what Android draws +when told nothing), `to_top`, `to_left`, `to_right`, `to_bottom_right`, +`to_top_right`, `to_bottom_left`, `to_top_left`. When a style carries both a +`background` and a `gradient`, the gradient is what is drawn; the flat colour +is the fallback for renderers that cannot draw a ramp. + +`opacity` dims the widget **and its children**, like `View.setAlpha()` on the +device. `0` on a screen-sized container means "no background of my own", so a +themed parent shows through. + +### Typography + +```python +Style( + font_size=TextScale.body, + font_family="Georgia, serif", # or "serif", "monospace", "DejaVu Sans" + line_height=6, # extra dp between lines, not a multiplier + letter_spacing=0.5, # extra dp between letters (may be negative) + text_transform="uppercase", # or "lowercase", "capitalize" + max_lines=2, # implies text_overflow="ellipsis" + text_overflow="ellipsis", # or "clip" + underline=False, + strikethrough=False, +) +``` + +`line_height` is **dp, not a multiplier**: every other number in a `Style` is +dp, and a value of `1.4` read as a multiplier would be 1.4 dp. `font_family` +takes a font name or a comma-separated list; the phone uses the first name the +device actually has and falls back to its default face, the PNG mockup resolves +the same list against the fonts installed, and the desktop window checks Tk's +family list before using it. `text_transform` is applied when the text is drawn, +so the widget's `text` stays exactly what the app set. + ### Spacing between specific neighbours `spacing` on a container applies the same gap everywhere. When one gap must @@ -1903,6 +1939,21 @@ replays them over data you have since saved. A load or migration that fails blocks every later operation on that store with the same error instead of serving or rewriting the data it rejected. +**Batching writes.** Every `set` rewrites the whole JSON file — about 1 ms on a +store with 5000 keys, so 4000 writes cost 12.9 s. A store created with +`deferred=True` marks the state dirty and writes once, 50 ms later: + +```python +store = Storage("cache.json", deferred=True) +for row in rows: + store.set(row["id"], row) # one file write, not one per row +store.flush() # ... or save(), or leave the app: both write +``` + +`save()`, `flush()` and a `transaction()` block always write immediately, the +pending write is also flushed when the interpreter exits, and the default +(`deferred=False`) keeps the old behaviour of writing on every change. + Data persists across app restarts. On Android it uses the app's private files directory; on desktop `~/.pymobile/.json` with the dots replaced by dashes (`com.example.notes` → `com-example-notes.json`), so two projects open @@ -2001,6 +2052,26 @@ Missing migration steps, malformed records and data written by a newer app raise `ModelStoreError` rather than erasing the stored value. Keep each migration with the model version that introduces it, and test upgrades from stored data. +**Finding records.** `all()` and `get()` are not the only readers: `find`, +`count` and `get_by` filter on the stored records and decode only the page they +return. + +```python +from pymobile import Q + +tasks.find({"done": False}) # every field must match +tasks.find(Q("done", "==", False) & Q("priority", ">=", 2)) # and / or / ~ +tasks.find({"done": False}, order_by="priority", limit=20, offset=40) +tasks.find(lambda task: task.priority == 3) # a predicate on the model +tasks.count({"done": True}) # no decoding at all +tasks.get_by(title="Ship it") # first match or None +``` + +`Q` compares one field with `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`, `not in`, +`contains`, `startswith` or `endswith`. Writes keep an id index, so 1000 `put` +calls take about 1.3 s instead of 5.2 s; a store that outgrows a single JSON +array (about a megabyte) logs a warning suggesting `sqlite3`. + --- ## Background jobs @@ -2021,11 +2092,32 @@ handle.cancel() # stop when done `JobHandle` exposes `.done`, `.cancelled`, `.result`, `.error`. +Jobs run on a small pool of worker threads — twice the CPU count by default, +never one thread per job: 500 queued jobs used to mean 500 threads. Set the +limit with `JobManager(max_workers=4)`, or read it back as +`app.jobs.max_workers`. A repeating job keeps its own thread, so a slow interval +never parks a worker. + `then()` callbacks run on the UI side (see [Threads and the UI](#threads-and-the-ui)). If `on_success` raises, the error is logged with its traceback and passed to `on_error`; the job's own -`result` is kept. `cancel()` suppresses the callbacks; Python cannot interrupt a -function that is already running, so `done` turns true only when it returns. +`result` is kept. + +**Cancelling is a request, not an interruption.** `cancel()` stops the +callbacks (`on_success`, `then`) and marks the handle, but the function itself +runs to its last line — Python has no way to stop a thread mid-call, and +`JobHandle.cancel()` deliberately does not pretend otherwise. Two consequences +worth designing around: + +- a job that writes must check for cancellation at a safe point of its own + (`if handle.cancelled: return`) instead of assuming the write never happens; +- a cancelled job still holds its worker until it returns, so a job that can + block for minutes belongs on its own thread (`app.jobs.submit(..., repeating=True)` + is the wrong tool — use a dedicated `threading.Thread` the app stops itself). + +A screen that navigates away while a job runs keeps the job; if its +`on_success` touches widgets that no longer exist, guard it with +`if self.is_current:`. --- @@ -2507,9 +2599,10 @@ client.put("/items/1", json={"name": "Updated"}) client.delete("/items/1") ``` -`retries`, `backoff`, `cache`, `security`, `user_agent` and `base_url` are set -once on `HttpClient(...)`. A request accepts `json`, `data`, `headers`, `timeout` and -`retry_safe`; `get` also takes `params`. Passing a client option to a verb, as in +`retries`, `backoff`, `cache`, `security`, `user_agent`, `base_url`, +`timeout_budget`, `max_redirects` and `max_workers` are set once on +`HttpClient(...)`. A request accepts `json`, `data`, `files`, `compress`, +`headers`, `timeout`, `retry_safe` and `stream`; `get` also takes `params`. Passing a client option to a verb, as in `client.get("/items", retries=2)`, raises a `TypeError` that says where the option belongs. @@ -2517,6 +2610,47 @@ option belongs. retried automatically, because a retry could repeat a side effect. Pass `retry_safe=True` on one request to opt in. +`timeout` bounds **one attempt**; `timeout_budget` bounds the **whole call**, +retries and backoff included. `timeout=2, retries=3` used to take 8.4 s to +give up: + +```python +client = HttpClient(timeout=2, retries=3, timeout_budget=5) # five seconds, at most +``` + +**Connections are reused.** One socket (and one TLS handshake) serves every +request to the same host until the server or the client closes it; `close()` +drops the idle sockets and `with HttpClient() as client:` does it for you. +`App.stop()` closes `app.http`. + +**Compressed bodies are decoded.** The client asks for `gzip, deflate` and +unpacks the body when a server compresses anyway, so `response.text` is text — +a hand-set `Accept-Encoding: identity` no longer means raw gzip bytes. + +**Uploads.** `files=` builds a `multipart/form-data` body — the boundary, the +CRLFs and the terminating part are handled once, correctly: + +```python +client.post("/upload", + data={"title": "Holiday"}, + files={"photo": ("p.jpg", b"...", "image/jpeg")}) # or a Path +client.post("/events", json=big_payload, compress=True) # gzip the request +``` + +**Downloads.** `stream=True` returns as soon as the headers arrive and leaves +the body on the socket; `iter_content()` reads it in chunks and releases the +connection, so a 30 MB file is not held in memory three times over: + +```python +with client.get("/big.zip", stream=True) as response: + for chunk in response.iter_content(64 * 1024): + handle.write(chunk) +``` + +**Secrets.** A URL logged at debug level no longer carries its token: +`access_token`, `token`, `api_key`, `secret`, `password`, `sig` and friends are +masked as `***` (`redact_url()`), because a debug log ends up in logcat. + Synchronous verbs return a `Response`; `HttpFuture.get()` returns the same object for an asynchronous request: @@ -2577,6 +2711,29 @@ Remember to list `android.permission.INTERNET` in your config. --- +## Secrets + +An API token written to `Storage` sits in a plain JSON file inside the app's +data directory, and inside every backup of it. `app.save_secret()` keeps it +encrypted with a key the Android keystore holds, so only this app on this +device can read it back: + +```python +app.save_secret("api_token", token) # True when stored +token = app.load_secret("api_token") # None when absent +app.delete_secret("api_token") +``` + +On Android the value is sealed with AES-GCM; the key never leaves the keystore. +The desktop stub keeps secrets in memory for the run, which is the honest answer +to "there is no keystore here", and a bridge with no support raises +`NotImplementedError` instead of writing the secret in the clear. + +A secret read after a reinstall or a restored backup comes back as `None` — the +old key is gone — and the app asks the user to sign in again. + +--- + ## Languages The device language plus a small catalogue, which is usually all a mobile app @@ -2886,13 +3043,22 @@ fix: never drops the `build/**` rule, so the output directory (and the previous APK inside it) is not packaged. The default `apk/` is excluded for the same reason. `exclude_only = true` turns that off and the build then warns when it can see that `output_dir` would ship itself. The defaults are -exported as `pymobile.core.config.DEFAULT_EXCLUDE`. The 29 built-in patterns are: +exported as `pymobile.core.config.DEFAULT_EXCLUDE`. The 38 built-in patterns are: - caches and build output: `**/__pycache__/**`, `**/*.pyc`, `**/*.pyo`, `build/**`, `dist/**`, `apk/**`, `.venv/**`, `venv/**` - tests: `**/tests/**`, `tests/**`, `**/test_*.py` - version control and editor folders: `.git/**`, `.github/**`, `.idea/**`, `.vscode/**` - documentation: `*.md`, so a `README.md` in the project is not packaged -- secret-like files: `.env`, `.env.*`, `*.jks`, `*.keystore`, `*.pem`, `*.key`, `id_rsa`, `id_rsa.*`, `secrets/**`, `secrets.json`, `secrets.*.json`, `credentials.json`, `credentials.*.json` +- secret-like files: `.env`, `.env.*`, `*.jks`, `*.keystore`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.ovpn`, `id_rsa`, `id_rsa.*`, `secrets/**`, `secret/**`, `secrets.json`, `secrets.*.json`, `credentials.json`, `credentials.*.json`, `.aws/**`, `.ssh/**`, `token.json`, `tokens.json`, `auth.json` + +Two of those rules are backed by code, not only by the list above: a file that +looks like a credential (`.netrc`, `.npmrc`, `.pypirc`, `.git-credentials`, +`known_hosts`, `local.properties`, `id_rsa*`, `credentials.*`, `secrets.*`, any +`*.pem`/`*.key`/`*.p12`/`*.pfx`/`*.ovpn`) is skipped even if a project's own +`exclude` would have let it through, and the build lists what it kept out: +`! kept out of the APK as credentials: .netrc`. An APK is a public ZIP archive +— anything inside can be extracted, so a secret belongs in +`app.save_secret()`, not in the project folder. If your app really needs one of these files, set `exclude_only = true` and write the patterns you want yourself. @@ -2910,6 +3076,30 @@ print(config.name, config.package, config.effective_min_sdk) --- +## First fifteen minutes + +```bash +pip install pymobile +python -m pymobile init --name Counter my-counter +cd my-counter && python -m pymobile run +``` + +A window opens with the app that is now in `main.py`. No SDK, no device, no +Java. When you want an APK: + +```bash +python -m pymobile setup-sdk && python -m pymobile build --native +``` + +- **[Tutorial](docs/TUTORIAL.md)** — from an empty project to an installable APK, + one step at a time. +- **[The five mistakes everyone makes](docs/BEGINNER-MISTAKES.md)** — + `super().__init__()`, `on_press=self.save()`, a missing `refresh()`, a string + where a widget belongs, an API key in the APK. +- **[A complete app in one screen](docs/TUTORIAL.md#step-3-a-screen-is-a-class-with-a-build)** — + the tutorial builds a note list with a store, a screen that redraws and a + delete confirmation, step by step, so there is no folder to keep in sync. + ## Building an APK ### Startup validation @@ -2940,6 +3130,80 @@ overrides it; `None` uses the build-mode default. A failed check stops with a message such as `Startup check failed: The app rendered nothing.` and exit code 1 rather than a success message for a non-starting APK. +### What the phone tells your app + +Three system events reach Python while the app is running. All three are +dropped into `App.handle_ui_event`, so they work the same on every front end +that sends them, and both can be ignored. + +| Event | Sent when | Payload | +| --- | --- | --- | +| `app:system-theme` | the system switches light/dark (`uiMode` is in `configChanges`, so the activity survives and this is the only notification) | `"dark"` or `"light"` | +| `app:insets` | the keyboard opens or closes | the covered height in px, as a string | +| `app:locale` | the system language changes | BCP-47 tag | + +```python +app = App("Photos", follow_system_theme=True) # palette follows the system +app.on("app:insets", lambda event: self.scroll_to_field(int(event.source))) +``` + +Android specifics: the root container applies the system-bar, display-cutout +and IME insets itself, so content never sits under a bar or under the keyboard +(`SafeArea` is still there for the screens that want the space back). The +manifest sets `supportsRtl` and margins are start/end, so Arabic and Hebrew +mirror. Images are decoded on a worker thread, scaled to the view and rotated by +their EXIF orientation — a 48 MP camera photo no longer freezes a frame or +exhausts the heap. + +### Certificate pinning + +```toml +# pymobile.toml +[network.pins] +"api.example.com" = ["sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="] +``` + +A pinned domain trusts **only** the listed certificates — the device's +user-installed roots stop being accepted for it, which is what a corporate proxy, +a "Wi-Fi inspector" app or a malware profile relies on to read HTTPS traffic. +Domains you do not list keep the system trust store, and cleartext stays denied. + +A pin is the base64 SHA-256 of the certificate's SubjectPublicKeyInfo. Print one +from the live server (and pin **two**, a current and a backup key, or a routine +certificate rotation locks every installed app out): + +```bash +openssl s_client -connect api.example.com:443 -servername api.example.com None: + self.app.save_state() # framework state + on_stop hooks + + def on_start(self) -> None: + self.app.restore_state() # after a restart in a new process +``` + +`on_stop` runs when the window goes away, `on_start` when a new window adopts +the screen; in between the app is alive but no longer takes input. Widget state +(a field's text, a switch, a dropdown) is written to +`app.storage`, under the `pymobile` namespace and keyed by widget id, so a +process that does die and comes back shows the half-typed form instead of an +empty one. Nothing here is a substitute for `Storage` — it covers what the +window itself held, not your domain data. + ### Build commands ```bash @@ -2953,15 +3217,46 @@ pymobile build --native --minimal-stdlib # drop desktop-only stdlib pymobile build --check-startup # also validate a structural build pymobile build --native --no-ssl # drop OpenSSL (no HTTPS) pymobile build --native --abi x86_64 # for the emulator +pymobile build --native # honours abis = [...] in the config +``` + +`abis = ["arm64-v8a", "x86_64"]` puts both architectures in one APK: it installs +everywhere, and it is the size of both together. `--abi` still builds one, which +is what you want for a device you know. + +`--debug` marks the native APK `android:debuggable`, so `adb shell run-as`, +Layout Inspector and the Android Studio debugger can attach to it; it is +refused together with `--keystore`, and it changes the artifact name's mode, so +a debug APK is never reused for a release build. + +```bash +pymobile build --native --bundle # APK + the .aab Google Play needs ``` +`--bundle` writes `apk/my-app-1.0.0.aab` beside the APK from the same manifest, +dex, assets and native libraries, then checks it with bundletool: `validate` +reads the whole bundle, and `build-apks --mode=universal` produces +`my-app-1.0.0-universal.apks`, an APK you can install to see exactly what a Play +install would deliver. Both steps need a JDK and `bundletool-all.jar` +(download it from [google/bundletool](https://github.com/google/bundletool/releases) +into `~/.andro/bundletool.jar`, or set `PYMOBILE_BUNDLETOOL`). Without them the +`.aab` is still written and the build says it was **not** verified — never +upload that one blind. + +Uploading: Play requires `targetSdkVersion` 36 for new apps and updates from +31 August 2026, which is also PyMobile's default, and `setup-sdk` installs +`platforms;android-36` so the classes are compiled against the level the +manifest declares. + > Without `--native` you get a lightweight structural package used for quick -> checks. **It does not install on a device.** +> checks. **It does not install on a device.** It is written to +> `apk/my-app-1.0.0-debug.apk`, so it never overwrites — and is never mistaken +> for — the installable `apk/my-app-1.0.0.apk` of a native build. After startup validation, a build with unchanged inputs can reuse its APK: ``` -✓ up to date: my-app-1.0.0.apk (16.2 MB) +✓ up to date: my-app-1.0.0.apk (16.4 MB) ``` The cache tracks application sources, configuration, icons, project-local Java @@ -3061,7 +3356,7 @@ only the `.apk`. ### Size -A hello-world APK is **16.2 MB** in 0.14.0, down from 21.6 MB in 0.2.0 and 16.6 MB in 0.3.0. The official +A hello-world APK is **16.4 MB** in 0.15.0, down from 21.6 MB in 0.2.0 and 16.6 MB in 0.3.0. The official CPython Android runtime ships every support library twice — `libcrypto.so` and `libcrypto_python.so` are byte-identical, and only the `_python` names are actually linked — so 5 MB of each APK was the same three libraries repeated. @@ -3226,7 +3521,7 @@ close the window. from pymobile import get_diagnostics info = get_diagnostics() -# {"framework_version": "0.14.0", "platform": "android", +# {"framework_version": "0.15.0", "platform": "android", # "python": "3.14.0", "log_level": "debug", "handlers": [...]} ``` @@ -3780,7 +4075,12 @@ build error, never a silent fallback to an older dex. The renderer implements For full control, implement `Widget` yourself and register the type; or use `pymobile widget-java TYPE` to print the older in-framework `ViewBuilder.java` -branch guide. `pymobile widget add` is the recommended project-local path; the +branch guide. Building a widget *into* the framework touches five places (the +widget, the capability table, the web and Tk previews, the ASCII/PNG previews +and the Java renderer); [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md#adding-a-widget-the-whole-list) +lists them one by one, and +`pymobile/tests/test_renderer_parity_between_python_and_java.py` fails, naming +the missing piece, when one is skipped. `pymobile widget add` is the recommended project-local path; the branch guide is for framework contributors who intentionally change the shared renderer. @@ -4094,7 +4394,7 @@ mypy pymobile # strict type checking | Area | Implementation | | --- | --- | -| CLI | `cli.py` facade/shared helpers; `cli_parser.py` grammar; `cli_preview.py` preview/dev/watch/audit; `cli_device.py` adb/emulator/install | +| CLI | `cli.py` facade/shared helpers; `cli_parser.py` grammar; `cli_build.py` build; `cli_preview.py` preview/dev/watch/audit; `cli_device.py` adb/emulator/install; `cli_errors.py` user-code error locations | | Mockup | `mockup.py` facade; `_mockup_colors`, `_mockup_fonts`, `_mockup_paint`, `_mockup_layout`, `_mockup_widgets`, `_mockup_chrome`; typed `_mockup_context` contract | | Android renderer | `ViewBuilder.java` facade/state owner; `ViewContainers`, `ViewControls`, `ViewInputs`, `ViewLists`, `ViewGestures`, `ViewStyles`, `ViewOverlays`, `ViewUpdates`; `FlowViews` wrapping layout | @@ -4122,7 +4422,7 @@ With the SDK/JDK available, also exercise source-built and prebuilt APKs, cache reuse and v2/v3 signatures (POSIX shell): ```bash -PYMOBILE_NATIVE_TESTS=1 python -m pytest pymobile/tests/test_remaining_p_fixes.py +PYMOBILE_NATIVE_TESTS=1 python -m pytest pymobile/tests/test_native_build_gates.py ``` For an actual release, follow [maintenance/release gates](https://github.com/Maksum867/PyMobile/blob/main/docs/CONTRIBUTING.md), @@ -4147,7 +4447,7 @@ pymobile build --native --clean When `pymobile_jni.c` changes, the prebuilt bridges must be rebuilt and committed together with it: -`pytest pymobile/tests/test_prebuilt_api_audit.py` compares the method tables +`pytest pymobile/tests/test_prebuilt_bridge_api.py` compares the method tables of the shipped binaries against the C source and fails when a prebuilt trails it (the drift that once left audio, clipboard, pickers, sharing and recording out of the wheel). diff --git a/docs/BEGINNER-MISTAKES.md b/docs/BEGINNER-MISTAKES.md new file mode 100644 index 0000000..7a239bd --- /dev/null +++ b/docs/BEGINNER-MISTAKES.md @@ -0,0 +1,131 @@ +# The five mistakes everyone makes in the first hour + +Each of these is a real message from a real app. PyMobile tries to name the +mistake instead of showing you a Python internals traceback — this page is the +long version of those messages. + +--- + +## 1. Forgetting `super().__init__()` + +```python +class Home(Screen): + def __init__(self): + self.title = "Home" # ✗ Screen.__init__ never ran +``` + +You get: + +``` +RuntimeError: Home.__init__ did not call super().__init__() + hint: add `super().__init__()` as the first line of Home.__init__ +``` + +**Fix.** Always the first line: + +```python +class Home(Screen): + def __init__(self): + super().__init__() # ✓ + self.title = "Home" +``` + +Same for a widget you subclass. If a class has no `__init__` of its own, there is +nothing to fix. + +--- + +## 2. Calling the handler instead of passing it + +```python +Button("Save", on_press=self.save()) # ✗ runs save() now, then passes None +Button("Save", on_press=self.save) # ✓ +``` + +The symptom: the action happens once, when the screen is built (often during +startup, before anything is on screen), and the button then does nothing at all. + +The build warns about this — `on_press=self.save()` means "the handler ran once +at build time". If `save()` needs an argument, use a lambda: + +```python +Button("Delete", on_press=lambda: self.delete(item)) +``` + +--- + +## 3. Changing state and expecting the screen to notice + +```python +def add(self): + self.count += 1 # ✗ the window still shows the old number +``` + +PyMobile does not compare your attributes on a timer. You say when to redraw: + +```python +def add(self): + self.count += 1 + self.refresh() # ✓ +``` + +If several things change together, change them all, then call `refresh()` once. + +For values you want to watch automatically, use `Value`: + +```python +from pymobile import Value + +self.count = Value(0) +Label(self.count).bind() # re-renders on every change +self.count.set(self.count.get() + 1) +``` + +--- + +## 4. A string where a widget belongs + +```python +Column("Total: 3") # ✗ a str is not a widget +Column(Label("Total: 3")) # ✓ +``` + +You get: + +``` +WidgetTypeError: Column children must be widgets, got str ("Total: 3") + hint: wrap text in Label("…") +``` + +The same goes for a `None` from a function that forgot to return a widget. + +--- + +## 5. Putting an API key in the app + +```python +API_KEY = "sk-live-…" # ✗ shipped inside the APK, readable by anyone +``` + +An APK is a ZIP file. `python -m pymobile build` ships `.py` (or `.pyc`, which is +no better) and anyone can unzip it and read every string in it. Anything the +build excludes from the APK — `.env`, `*.jks`, `credentials.json` — is mostly +there to stop you doing this by accident, not to keep a secret. + +What works: + +- **A token the user created** — `app.save_secret("token", value)` keeps it + encrypted with a key the Android keystore holds. +- **A secret the app needs to call a service** — put it on a small relay you + control and have the app call that. There is no client-side hiding. + +--- + +## Where to look next + +- `python -m pymobile check` — the same mistakes, found before you run anything. +- `python -m pymobile check-ui` — accessibility gaps and layouts that overflow a + narrow screen. +- [TUTORIAL.md](TUTORIAL.md) — the fifteen-minute walkthrough these mistakes come + from. +- `python -m pymobile doctor` — the environment, when a *build* is what fails. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ffcde32..da6131a 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -31,6 +31,121 @@ settings and appointments require the owner. Contributors who change renderer Java, packaging or release behaviour should also read the release gates below. +### Adding a widget to the previews + +The browser preview and the Tk window draw a widget in two places, each split +by widget family: + +- `pymobile/core/ui/web.py` — a `_html_` helper per family, picked + through the `_HTML_RENDERERS` table. A helper that draws several kinds keeps + one `if kind == ...` guard per kind, so the dispatcher can share it. +- `pymobile/core/ui/gui.py` — a `_build_` method per family, picked + through `_TK_BUILDERS`. It returns `True` when it drew the node and `False` + when the node belongs to another guard in the same helper. + +Both take a small `_RenderContext`/`_BuildContext` instead of a dozen +parameters, so adding a field does not touch every helper. + +### Adding a widget: the whole list + +A widget type reaches five places. `pymobile/tests/test_renderer_parity_between_python_and_java.py` +fails, with the missing name, when one of them is forgotten — that test is the +CI half that does not need an SDK. + +| Step | File | What to add | +| --- | --- | --- | +| 1. The widget | `core/ui/components.py`, `controls.py`, `layout.py` or `patterns.py` | the class, its validated properties and `props()` | +| 2. The capability row | `core/ui/registry.py`, `WIDGET_CAPABILITIES` | `WidgetCapability("Name", web=True, gui=True)` — `android=` stays `False` until step 5 lands | +| 3. The previews | `core/ui/web.py`, `core/ui/gui.py`, `core/ui/extras_preview.py` | one helper plus one `_HTML_RENDERERS` / `_TK_BUILDERS` entry | +| 4. The text and PNG previews | `core/ui/preview.py`, `core/ui/extras_preview.py` | the ASCII form and, if it draws, `extra_mockup` | +| 5. The phone | `resources/android/java/ViewBuilder.java` (and a `View*.java` file) | `case "Name":`, then `python -m pymobile.compiler.rebuild_dex` and `--check`; needs javac, d8 and `android.jar`, not an NDK | +| 6. The evidence | `pymobile/tests/`, `CHANGELOG.md` | a test named for the behaviour, and one line under the release | + +Steps 1–4 and 6 need no Android tooling at all; that is a complete, reviewable +pull request on its own, with the capability row declaring `android=False` and +`pymobile run` warning that the phone will draw a placeholder. Step 5 turns the +same change into native parity, and is where the rebuild commands from the +release gates apply. + +## Where to start, and where to ask + +Three doors, in the order most people use them: + +| You have | Go to | +| --- | --- | +| a question ("how do I …") | GitHub **Discussions → Q&A**. Issues are for things that are wrong, discussions are for things that are unclear. | +| a small fix, no Android needed | the [`good first issue`](../../issues?q=is%3Aissue+label%3A%22good+first+issue%22) label. Each one names the file and the test. | +| a bug you can reproduce | the **Bug report** form; it asks for `python -m pymobile doctor` output, which saves a round trip. | + +Nothing here needs permission before you start. Comment on an issue you are +taking so two people do not write the same patch, and open the pull request when +it is green rather than when it is perfect — review is faster than a perfect +patch written in the dark. + +New to the project *and* to Python? Read +[TUTORIAL.md](TUTORIAL.md) first (fifteen minutes, no SDK) and +[BEGINNER-MISTAKES.md](BEGINNER-MISTAKES.md) second. Every snippet in both is +checked by tests — the imports against the real package and the commands +against the real CLI — so neither can quietly rot. + +## First contribution in ten minutes + +The first useful change does not need an Android device, an SDK, or an +understanding of the renderers. This is the shortest path from a clean checkout +to a merged patch. + +1. **Pick something small.** The issues labelled `good first issue` are written + for exactly this: a docstring, a clearer error message, one test that pins a + behaviour down. Comment on the issue so nobody duplicates the fix. +2. **Get the checkout running.** + ```sh + git clone https://github.com/Maksum867/PyMobile.git + cd PyMobile + python -m venv .venv + . .venv/bin/activate # Windows: .venv\Scripts\activate + python -m pip install -e ".[dev]" + python -m pytest -q # the whole suite, about 90 s + ``` + Tk previews and PNG snapshots skip themselves when there is no display or no + Pillow; a skipped test is not a passed test. +3. **Find where the change goes.** Most tasks touch one of: + - `pymobile/core/ui/components.py`, `controls.py`, `layout.py` — a widget and + the props it serialises; + - `pymobile/core/ui/patterns.py` — a composed widget (card, form, calendar); + - `pymobile/core/ui/web.py` and `gui.py` — the browser and Tk previews, one + `_html_*` / `_build_*` helper per widget family (see below); + - `pymobile/core/bridge/` — what the framework asks the phone for; + - `pymobile/cli*.py` — one module per command family (`cli_build.py` build, + `cli_preview.py` preview/dev/watch, `cli_device.py` adb/emulator/install); + `cli.py` holds the shared helpers and a replaceable pass-through per + command; + - `README.md` and `docs/` — behaviour that has changed. +4. **Write the test first.** `pymobile/tests/` has one file per behaviour, and + the name says what is checked (`test_http_connections_and_encoding.py`, not + `test_audit_round_5.py`). Copy the closest file, run it alone + (`python -m pytest pymobile/tests/your_file.py -q`), then run the full suite. +5. **Open the pull request.** Describe the problem, the change and the exact + commands you ran. A maintainer reviews for correctness first, style second; + a review question is not a rejection. + +Things that make a patch easy to accept: the smallest diff that fixes the +problem, a test that fails before the fix and passes after it, a CHANGELOG line +for anything a user can notice, and no unrelated reformatting. Things that make +it hard: a whole-file reformat, a new dependency, or a change to +`resources/android/prebuilt/` without the rebuild commands from the release +gates. + +### Where a good first task usually lives + +| Task | Files | Checks | +| --- | --- | --- | +| An error message that does not say what to do | the raising module, `pymobile/tests/` | `pytest`, `ruff`, `mypy` | +| A docstring on a public function | the module, `pymobile/` | `ruff`, `mypy` | +| A README paragraph that is out of date | `README.md`, `CHANGELOG.md` | read it as a newcomer | +| A web-preview look that is wrong | `core/ui/web.py`, `core/ui/extras_preview.py` | `pymobile preview --web` | +| A Tk preview that is wrong | `core/ui/gui.py` | `pymobile run --gui` (needs a display) | +| A widget the phone draws wrongly | `resources/android/java/View*.java` | **not** a first task: needs the SDK and a device | + ## Compatibility and adoption - Treat 0.x as alpha. Consumers should pin an exact version and validate upgrades @@ -64,7 +179,7 @@ also read the release gates below. It is a consistency check, not a cryptographic authenticity or device test. 4. Run real SDK builds and signature/prebuilt/cache regressions: ```sh - PYMOBILE_NATIVE_TESTS=1 python -m pytest pymobile/tests/test_remaining_p_fixes.py + PYMOBILE_NATIVE_TESTS=1 python -m pytest pymobile/tests/test_native_build_gates.py ``` Set ANDROID_HOME/JAVA_HOME as needed. Standard native builds validate startup; do not use `--skip-startup-check` merely to make release gates green. @@ -93,8 +208,15 @@ also read the release gates below. only if that file exists in the checkout; it is not a required release gate. The Android diagnostics upload is best-effort (`if-no-files-found: warn`) and warns instead of failing when no device artifacts were produced. +- Every third-party action is pinned to a commit SHA, with the release it came + from in a trailing comment (`# v4.1.7`). A tag is a moving target: whoever + owns the action can repoint it and run new code with this repository's + token. Dependabot proposes the SHA bumps weekly, one grouped PR, so keeping + the pins current costs a review rather than a rewrite. Verify a new SHA + against the upstream repository (`git ls-remote --tags https://github.com/…`) + before merging — the comment is a note, not proof. -## Maintainer continuity (owner actions) +## Maintainer continuity (owner actions — skip on your first patch) - Nominate and obtain consent from a second reviewer with Android/runtime knowledge. Update CODEOWNERS only with real, consenting collaborators; do not @@ -109,7 +231,7 @@ also read the release gates below. schedule. State actual support commitments publicly; do not imply an SLA that no maintainer has agreed to provide. -## Publication boundary +## Publication boundary (owner actions — skip on your first patch) Local patches cannot appoint upstream maintainers, create upstream issues without access, configure protections or update the live PyPI page. The files @@ -159,7 +281,7 @@ Run checks from the repository root. During development, run a focused test firs then the full suite before requesting review: ```sh -python -m pytest pymobile/tests/test_remaining_p_fixes.py +python -m pytest pymobile/tests/test_native_build_gates.py python -m pytest python -m ruff check pymobile python -m mypy pymobile @@ -190,6 +312,33 @@ tracebacks. Review their output before sharing: paths, identifiers or applicatio logs can contain private information. Test UI changes with [`check-ui`](ACCESSIBILITY.md#automated-audit) and, when relevant, on Android. +### Errors that name the mistake + +A user does not read the framework source. Every error the framework raises on +purpose must name the thing the user wrote, and say what to write instead: + +- Name the user's own syntax, not a private attribute. `Column(Label("a"), + "text")` used to fail with `'str' object has no attribute '_parent'`; it now + says the string is not a child and shows `Column(Label('text'))`. A screen + whose `__init__` forgot `super().__init__()` says so, with the lines that fix + it, instead of `'Home' object has no attribute '_root'`. +- Prefer the shape the user typed. A handler written with parentheses + (`on_press=self.on_tap()`) is a static mistake: `pymobile check` reports it at + its line and column, because the call runs once while the tree is built and + the button then silently does nothing. +- Keep a sentence per cause. `None` in a container is usually a conditional + expression, a bare function is usually a factory missing its parentheses, a + list inside a list is flattened one level only — say which one it is. +- Do not change the exception type callers catch. New child validation raises a + plain `TypeError`, and `WidgetTypeError` stays about `find()`/`get()`; an + existing test's expected wording (`children must be Widget instances`) is kept + where it was already part of the contract. +- Add the regression test to the file that already covers that behaviour + (`test_child_type_errors.py` for children, `test_precheck.py` for `check`, + `test_build_warnings_and_artifact_names.py` for what a build writes and + warns about) and quote the sentence the user sees, so a later refactor cannot + quietly undo it. + ## Renderer and packaging changes - Check how the serialized widget tree, event handling, state updates and @@ -201,6 +350,40 @@ logs can contain private information. Test UI changes with - A Java renderer change needs the rebuilt dex and its provenance manifest to agree with the sources; use the rebuild and check commands in the release gates. The manifest detects drift, not malicious substitution. +- The APK name carries the build mode: `build --native` writes + `app-0.1.0.apk`, a structural `build` writes `app-0.1.0-debug.apk` (plus the + ABI for a non-arm64 target). A non-installable artifact must never occupy the + name `pymobile install` looks for — that produced a signature error instead of + the real cause. +- Anything that ships inside the APK is public: credential-looking files are + filtered in `collector.is_credential_file()` and listed in the build + warnings, so a new "copy everything" path must call it too. Debug switches go + into the manifest only for `--debug` (`ManifestBuilder(debuggable=True)`), + never by default, and must be part of `build_mode()` so the cache cannot + hand a debug artifact to a release build. +- The window lifecycle is a wire contract: `MainActivity.onDestroy` sends + `dispatchEvent("", "__lifecycle__", "stop")` and `onCreate` sends + `"resume"`; `App._lifecycle()` handles both. Do not add a new JNI entry point + for this — `libpymobile.so` ships prebuilt and rebuilding it needs an NDK, so + `dispatchEvent` (the one call every released bridge has) carries the event. + Anything queued behind a stop is dropped, and `App.save_state()` must stay + cheap: it runs on the UI thread during teardown. +- `--bundle` builds the `.aab` from the same artifacts as the APK and verifies + it with bundletool. A change to the manifest, the resource pipeline or the + asset layout must be checked with a real `build --native --bundle` and + `bundletool validate`, not only with the ZIP-layout unit tests; the bundle + layout (`base/manifest`, `base/dex`, `base/res`, `base/lib/`) is + stricter than an APK's. `toolchain.find_toolchain()` follows + `sdk_installer.SDK_PLATFORM` — never `target_sdk` — because the manifest + level and the compiled level must agree. +- The adaptive icon is generated, not committed: `icon.write_adaptive_icon()` + writes the three layers plus `mipmap-anydpi-v26`, and the manifest addresses + `@mipmap/ic_launcher`. A renamed resource must be renamed in all three + places (icon, manifest, the notification fallback in `core/bridge/jni.py`). +- `target_sdk` above the platform installed by `setup-sdk` + (`sdk_installer.SDK_PLATFORM`, currently `android-35`) cannot be compiled + against; the build warns about it. Raising `SDK_PLATFORM` means changing + `MINIMAL_PACKAGES` and verifying a real native build. - JNI rebuilding is separate from rebuilding the renderer dex and requires the NDK. For work that needs it, see the [native build guide](../README.md#building-an-apk). Record SDK/JDK/NDK and device details and avoid claiming an unrun native check. diff --git a/docs/TUTORIAL.md b/docs/TUTORIAL.md new file mode 100644 index 0000000..ab24478 --- /dev/null +++ b/docs/TUTORIAL.md @@ -0,0 +1,236 @@ +# Your first PyMobile app, step by step + +Fifteen minutes, no Android device, no Java. You will end with a running desktop +preview and an installable APK. + +Every command is a shell command. Every code block is a whole file — copy it in +and it runs. + +--- + +## 0. What you need + +```bash +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install pymobile +python -m pymobile --version # 0.15.0 +``` + +Nothing else, for now. The SDK comes in step 6; the desktop preview runs without +it. + +--- + +## 1. Create a project + +```bash +python -m pymobile init --name Counter my-counter +cd my-counter +``` + +You get: + +``` +my-counter/ +├── main.py ← your app +├── pymobile.toml ← settings (name, permissions, target Android level) +├── assets/ ← images, fonts, data files +└── README.md +``` + +`main.py` already runs. Look at it before changing anything. + +--- + +## 2. Run it on your computer + +```bash +python -m pymobile run +``` + +A window opens. This is the **same widget code** the phone will run — not a mock. +While it is open, editing `main.py` re-renders the window (hot reload). + +Prefer a browser? `python -m pymobile preview` prints a local URL. + +--- + +## 3. A screen is a class with a `build()` + +Replace the contents of `main.py` with this: + +```python +from pymobile import App, Button, Column, Label, Screen + + +class Home(Screen): + def __init__(self) -> None: + super().__init__() + self.count = 0 + + def build(self) -> Column: + return Column( + Label(f"Count: {self.count}"), + Button("Add one", on_press=self.add), + ) + + def add(self) -> None: + self.count += 1 + self.refresh() # rebuild this screen + + +app = App("Counter") +app.run(Home()) +``` + +Three things are worth stopping on: + +- **`super().__init__()`** — without it you get a message that says exactly + that, not a crash deep inside the framework. +- **`on_press=self.add`, not `self.add()`** — with the parentheses the handler + runs once, now, and the button does nothing. PyMobile warns about this. +- **`self.refresh()`** — you say when to redraw. There is no hidden diffing of + your variables. + +If the window does not update, you forgot the `refresh()`. + +--- + +## 4. Add a second screen and go back + +Screens are pushed on a stack. The system back gesture (and the browser back +button) pops it. + +```python +from pymobile import App, Button, Column, Label, Screen, TextInput + + +class Welcome(Screen): + def build(self) -> Column: + return Column( + Label("What should we call you?"), + Button("Continue", on_press=self.go), + ) + + def go(self) -> None: + self.app.push(NameScreen()) + + +class NameScreen(Screen): + def __init__(self) -> None: + super().__init__() + self.name = TextInput(id="name", placeholder="your name") + + def build(self) -> Column: + return Column( + self.name, + Button("Save", on_press=self.save), + ) + + def save(self) -> None: + self.app.storage.set("name", self.name.value) + self.app.pop() + + +app = App("Hello") +app.run(Welcome()) +``` + +`self.app.storage` is a small JSON store that survives the app being closed. +`self.app.push()` / `self.app.pop()` change screens; `self.app.reset(screen)` +replaces the whole stack. + +--- + +## 5. Save data that must not be lost + +```python +app = App("Notes") +app.storage.set("theme", "dark") # any JSON-serialisable value +theme = app.storage.get("theme", "light") +``` + +For a list of records (notes, tasks, messages) use `ModelStore`, which adds +ids, queries and migrations instead of one big dictionary: + +```python +from dataclasses import dataclass +from pymobile import ModelStore + + +@dataclass +class Note: + id: str + text: str + + +notes = ModelStore(app.storage, Note, key="notes") +notes.put(Note(id="1", text="buy milk")) +for note in notes.find(lambda n: "milk" in n.text): + print(note.text) +``` + +Secrets (a token, a password) do not go in either — use +`app.save_secret("token", value)`, which stores them encrypted with a key the +Android keystore holds. + +--- + +## 6. Build a real APK + +```bash +python -m pymobile doctor # what is missing, if anything +python -m pymobile setup-sdk # downloads the Android SDK (~1 GB, once) +python -m pymobile build --native +``` + +Result: + +``` +✓ built my-counter-0.1.0.apk — 16.4 MB, installable +``` + +Then, with a phone plugged in over USB (developer mode on): + +```bash +python -m pymobile install +``` + +`adb logcat -s pymobile` shows your `print()` output and tracebacks. + +Uploading to Google Play needs an `.aab` instead of an APK: + +```bash +python -m pymobile build --native --bundle +``` + +That writes both, and checks the bundle with bundletool. + +--- + +## 7. When something goes wrong + +| Symptom | Cause | Fix | +| --- | --- | --- | +| `'Home' object has no attribute '_root'` | missing `super().__init__()` | add it as the first line of `__init__` | +| Button does nothing | `on_press=self.tap()` | drop the parentheses | +| Screen does not update | nothing called `refresh()` | call it after changing state | +| `WidgetTypeError` | a string where a widget belongs | wrap it: `Label("text")` | +| `python -m pymobile run` prints a traceback | see the file and line it names | `python -m pymobile check` runs the same check without launching | +| APK installs, then closes at once | the startup check would have caught it | `python -m pymobile build --native -v` and read the first error | + +The three most common beginner mistakes have their own page: +[BEGINNER-MISTAKES.md](BEGINNER-MISTAKES.md). + +--- + +## Where to go next + +- **Every widget** — `python -m pymobile preview --text` prints a screen as + text, and `python -m pymobile preview --png screen.png` draws it as a picture, + so you can check a layout without a phone. +- **The whole app in one file** — steps 3–5 above are the complete program; keep + them together and you have a note list that survives a restart. +- **The reference** — the README's widget and API sections. +- **Stuck?** — open a discussion with the output of `python -m pymobile doctor`. diff --git a/pymobile/__init__.py b/pymobile/__init__.py index 1b41577..91df8c3 100644 --- a/pymobile/__init__.py +++ b/pymobile/__init__.py @@ -18,7 +18,7 @@ def build(self): from __future__ import annotations -__version__ = "0.14.0" +__version__ = "0.15.0" __author__ = "MAKSYM KHLYSTUN" __license__ = "MIT" @@ -67,6 +67,7 @@ def build(self): Banner, BarChart, BatteryLevel, + Border, BottomNavigation, BottomSheet, Button, @@ -81,6 +82,7 @@ def build(self): Color, ColorPicker, Column, + Computed, ConfirmDialog, ConnectionStatus, Container, @@ -99,6 +101,7 @@ def build(self): FloatingActionButton, Form, FormField, + Gradient, Grid, Icon, IconButton, @@ -154,6 +157,7 @@ def build(self): TreeNode, TreeView, UiIssue, + Value, Widget, Wrap, audit_ui, @@ -233,7 +237,6 @@ def build(self): "Polygon", "Rect", "Shape", - "__version__", # application "App", @@ -334,6 +337,10 @@ def build(self): "Color", "Align", "EdgeInsets", + "Border", + "Value", + "Computed", + "Gradient", "Divider", "Expanded", "Flexible", diff --git a/pymobile/cli.py b/pymobile/cli.py index 3fe11c0..9637a0d 100644 --- a/pymobile/cli.py +++ b/pymobile/cli.py @@ -24,13 +24,17 @@ from typing import Any, TextIO from . import __version__ as __version__ +from .cli_errors import _describe_user_error, _user_code_location # noqa: F401 from .cli_tools import cmd_complete, cmd_completion, cmd_init, cmd_schema + +# Re-exported for callers and tests that replace the pipeline; cli_build reads +# it from this module at call time. from .compiler.pipeline import BuildPipeline from .core.config import ProjectConfig, load_config from .errors import PyMobileError from .log import configure, get_logger, supports_color -__all__ = ["main", "build_parser"] +__all__ = ["main", "build_parser", "BuildPipeline"] _log = get_logger("cli") @@ -140,114 +144,11 @@ def _warn_if_output_is_ignored(config: ProjectConfig) -> None: _out.hint("use `--output apk` (the default) or remove the ignore rule") -def cmd_build(args: argparse.Namespace) -> int: - """Compile the project into an APK.""" - config = _load(args) - if args.icon: - config.icon = args.icon - if args.output: - config.output_dir = args.output - if getattr(args, "optimize", False): - config.optimize = True - if getattr(args, "no_optimize", False): - config.optimize = False - if getattr(args, "minimal_stdlib", False): - config.minimal_stdlib = True - if getattr(args, "no_ssl", False): - config.no_ssl = True - if getattr(args, "abi", None): - # One APK per ABI: arm64-v8a for phones, x86_64 for the emulator. - config.abis = [args.abi] - config.validate() - - if args.clean: - _clean(config) - - if getattr(args, "ks_pass", None) or getattr(args, "key_pass", None): - _out.warn( - "passwords on the command line end up in shell history and `ps`; " - "prefer PYMOBILE_KS_PASS / PYMOBILE_KEY_PASS" - ) +def cmd_build(*args: Any, **kwargs: Any) -> Any: + """Compatibility entry point; the implementation is in cli_build.""" + from . import cli_build - _warn_if_output_is_ignored(config) - native = getattr(args, "native", False) - if native and not getattr(args, "no_check", False) and _has_files(config.root): - from .compiler.precheck import check_project, format_finding - - findings = check_project(config.root, run_app=False) - if findings: - for finding in findings: - print(format_finding(finding, config.root)) - _out.error( - f"{len(findings)} problem(s) found; the build was stopped. " - "Fix them, or pass --no-check to build anyway." - ) - return 1 - if native: - _out.info("native build: this may take a few minutes on the first run") - else: - _out.warn( - "This is a structural build — not installable on a device. " - f"Use --native for a real APK (requires Android SDK: {_invocation()} setup-sdk)" - ) - pipeline = BuildPipeline( - config, - use_cache=not args.no_cache and not args.clean, - native=native, - check_startup=getattr(args, "check_startup", None), - on_stage=lambda stage: _out.info(f"{stage}…") if args.verbose else None, - keystore=Path(args.keystore) if getattr(args, "keystore", None) else None, - keystore_password=getattr(args, "ks_pass", None), - key_alias=getattr(args, "key_alias", None), - key_password=getattr(args, "key_pass", None), - ) - try: - result = pipeline.run() - except Exception as exc: - from .compiler.startup import StartupCheckError - from .compiler.toolchain import ToolchainError - from .compiler.widgets import MissingRendererError - - if isinstance(exc, ToolchainError): - hint = getattr(exc, "hint", None) or "" - if "setup-sdk" not in hint: - hint = (f"{hint} " if hint else "") + ( - f"Run `{_invocation()} setup-sdk` to install it automatically." - ) - raise type(exc)(str(exc), hint=hint.strip()) from exc - if native and not isinstance(exc, (MissingRendererError, StartupCheckError)): - from .errors import PyMobileError as _PyErr - - if isinstance(exc, _PyErr) and exc.hint and "setup-sdk" not in exc.hint: - exc.hint = f"{exc.hint} (for native: {_invocation()} setup-sdk)" - elif isinstance(exc, _PyErr) and not exc.hint: - exc.hint = f"Run `{_invocation()} setup-sdk` to install the Android SDK." - raise - - for warning in result.warnings: - _out.warn(warning) - - if result.cached: - size = ( - f"{result.size / (1024 * 1024):.1f} MB" - if result.size >= 1024 * 1024 - else f"{result.size_kb:.1f} KB" - ) - _out.ok(f"up to date: {result.apk.name} ({size})") - _out.hint("use --clean to force a full rebuild") - return 0 - - _out.ok(result.summary()) - _out.field("apk", result.apk) - _out.field("icon", "default" if result.icon_is_default else config.icon) - if result.native: - _out.field("install", f"{_invocation()} install {result.apk}") - if config.abis and config.abis[0] == "x86_64": - _out.hint("x86_64 build: for the Android Studio emulator, not for a phone") - if args.verbose: - for timing in result.timings: - _out.field(timing.name, f"{timing.seconds * 1000:.0f} ms") - return 0 + return cli_build.cmd_build(*args, **kwargs) def cmd_run(args: argparse.Namespace) -> int: @@ -490,7 +391,15 @@ def _execute(config: ProjectConfig, entry: Path) -> dict[str, object]: if str(config.source_path) not in sys.path: sys.path.insert(0, str(config.source_path)) namespace: dict[str, object] = {"__name__": "__main__", "__file__": str(entry)} - exec(compile(entry.read_text(encoding="utf-8"), str(entry), "exec"), namespace) + try: + exec(compile(entry.read_text(encoding="utf-8"), str(entry), "exec"), namespace) + except PyMobileError: + raise + except Exception as exc: + # A plain NameError used to reach main()'s catch-all and print + # "unexpected error" with no file and no line, while `pymobile check` + # named both. Same information, same place. + raise _describe_user_error(exc, entry) from exc from .core.app import App diff --git a/pymobile/cli_build.py b/pymobile/cli_build.py new file mode 100644 index 0000000..2a20996 --- /dev/null +++ b/pymobile/cli_build.py @@ -0,0 +1,136 @@ +"""The build command: compile a project into an APK. + +`cli.cmd_build` is a lazy pass-through to this module, so an application (or a +test) can replace the command without changing the parser. Everything the body +shares with the rest of the CLI — configuration loading, console output, the +clean step — is read from `pymobile.cli` at call time. +""" + +from __future__ import annotations + +import argparse +from pathlib import Path + +from . import cli +from .compiler.pipeline import BuildPipeline as _Pipeline + + +def cmd_build(args: argparse.Namespace) -> int: + """Compile the project into an APK.""" + config = cli._load(args) + if args.icon: + config.icon = args.icon + if args.output: + config.output_dir = args.output + if getattr(args, "optimize", False): + config.optimize = True + if getattr(args, "no_optimize", False): + config.optimize = False + if getattr(args, "minimal_stdlib", False): + config.minimal_stdlib = True + if getattr(args, "no_ssl", False): + config.no_ssl = True + if getattr(args, "abi", None): + # One APK per ABI: arm64-v8a for phones, x86_64 for the emulator. + config.abis = [args.abi] + config.validate() + + if args.clean: + cli._clean(config) + + if getattr(args, "ks_pass", None) or getattr(args, "key_pass", None): + cli._out.warn( + "passwords on the command line end up in shell history and `ps`; " + "prefer PYMOBILE_KS_PASS / PYMOBILE_KEY_PASS" + ) + + cli._warn_if_output_is_ignored(config) + native = getattr(args, "native", False) + if getattr(args, "bundle", False): + # An app bundle is a container around a compiled APK; asking for one + # against a structural build only produced a confusing error later. + native = True + if getattr(args, "debug", False) and not native: + cli._out.error("`--debug` only applies to a native APK (`build --native --debug`)") + return 2 + if native and not getattr(args, "no_check", False) and cli._has_files(config.root): + from .compiler.precheck import check_project, format_finding + + findings = check_project(config.root, run_app=False) + if findings: + for finding in findings: + print(format_finding(finding, config.root)) + cli._out.error( + f"{len(findings)} problem(s) found; the build was stopped. " + "Fix them, or pass --no-check to build anyway." + ) + return 1 + if native: + cli._out.info("native build: this may take a few minutes on the first run") + else: + cli._out.warn( + "This is a structural build — not installable on a device. " + f"Use --native for a real APK (requires Android SDK: {cli._invocation()} setup-sdk)" + ) + # Read from cli, so a caller (or a test) that replaces cli.BuildPipeline wins. + build_pipeline: type[_Pipeline] = cli.BuildPipeline + pipeline = build_pipeline( + config, + use_cache=not args.no_cache and not args.clean, + native=native, + check_startup=getattr(args, "check_startup", None), + on_stage=lambda stage: cli._out.info(f"{stage}…") if args.verbose else None, + keystore=Path(args.keystore) if getattr(args, "keystore", None) else None, + keystore_password=getattr(args, "ks_pass", None), + key_alias=getattr(args, "key_alias", None), + key_password=getattr(args, "key_pass", None), + debug=getattr(args, "debug", False), + bundle=getattr(args, "bundle", False), + ) + try: + result = pipeline.run() + except Exception as exc: + from .compiler.startup import StartupCheckError + from .compiler.toolchain import ToolchainError + from .compiler.widgets import MissingRendererError + + if isinstance(exc, ToolchainError): + hint = getattr(exc, "hint", None) or "" + if "setup-sdk" not in hint: + hint = (f"{hint} " if hint else "") + ( + f"Run `{cli._invocation()} setup-sdk` to install it automatically." + ) + raise type(exc)(str(exc), hint=hint.strip()) from exc + if native and not isinstance(exc, (MissingRendererError, StartupCheckError)): + from .errors import PyMobileError as _PyErr + + if isinstance(exc, _PyErr) and exc.hint and "setup-sdk" not in exc.hint: + exc.hint = f"{exc.hint} (for native: {cli._invocation()} setup-sdk)" + elif isinstance(exc, _PyErr) and not exc.hint: + exc.hint = f"Run `{cli._invocation()} setup-sdk` to install the Android SDK." + raise + + for warning in result.warnings: + cli._out.warn(warning) + + if result.cached: + size = ( + f"{result.size / (1024 * 1024):.1f} MB" + if result.size >= 1024 * 1024 + else f"{result.size_kb:.1f} KB" + ) + cli._out.ok(f"up to date: {result.apk.name} ({size})") + cli._out.hint("use --clean to force a full rebuild") + return 0 + + cli._out.ok(result.summary()) + cli._out.field("apk", result.apk) + cli._out.field("icon", "default" if result.icon_is_default else config.icon) + if result.native: + cli._out.field("install", f"{cli._invocation()} install {result.apk}") + if config.abis and config.abis[0] == "x86_64": + cli._out.hint("x86_64 build: for the Android Studio emulator, not for a phone") + if args.verbose: + for timing in result.timings: + cli._out.field(timing.name, f"{timing.seconds * 1000:.0f} ms") + return 0 diff --git a/pymobile/cli_errors.py b/pymobile/cli_errors.py new file mode 100644 index 0000000..bdecb40 --- /dev/null +++ b/pymobile/cli_errors.py @@ -0,0 +1,65 @@ +"""Turning an exception from the app's own code into a message with a location. + +The CLI runs the developer's entry point, so the most useful part of a +traceback is the frame that belongs to *their* file. Keeping this separate from +the command dispatch also keeps :mod:`pymobile.cli` small enough for the +file-size guard in the test suite. +""" + +from __future__ import annotations + +from pathlib import Path + +from .errors import PyMobileError + + +def _user_code_location(exc: BaseException, entry: Path) -> str | None: + """``main.py:12`` for the innermost frame that belongs to the app. + + A traceback from user code spends most of its frames inside the framework; + the one that answers "where?" is the deepest frame whose file is the app's + own. Syntax errors carry their own position. + """ + if isinstance(exc, SyntaxError) and exc.filename: + line = exc.lineno or 0 + return f"{Path(exc.filename).name}:{line}" if line else Path(exc.filename).name + location: str | None = None + traceback_ = exc.__traceback__ + while traceback_ is not None: + frame = traceback_.tb_frame + filename = frame.f_code.co_filename + if not filename.startswith("<"): + path = Path(filename) + if entry.parent in path.parents or path == entry: + location = f"{path.name}:{traceback_.tb_lineno}" + traceback_ = traceback_.tb_next + return location + + +def _describe_user_error(exc: BaseException, entry: Path) -> PyMobileError: + """Turn a raw exception from the app's code into a message with a location.""" + location = _user_code_location(exc, entry) + where = f" ({location})" if location else "" + detail = f"{type(exc).__name__}: {exc}" if str(exc) else type(exc).__name__ + hint = ( + "This is a bug in your code, not in the framework: read the line named " + "above, or re-run with --verbose for the full traceback." + ) + if isinstance(exc, NameError) and getattr(exc, "name", None): + hint = ( + f"{exc.name!r} is not defined at that point: check the spelling, and " + "that the import or assignment runs before this line." + ) + elif isinstance(exc, AttributeError): + hint = ( + "That attribute does not exist. A common cause is a missing " + "super().__init__() in the screen's __init__." + ) + elif isinstance(exc, SyntaxError): + hint = "Python could not parse the file; the caret in --verbose points at it." + error = PyMobileError(f"{detail}{where}", hint=hint) + # The line the message already names, kept as an attribute so a caller that + # formats findings of its own (``pymobile check``) does not have to parse + # the text back out. + error.line = int(location.rsplit(":", 1)[-1]) if location else None # type: ignore[attr-defined] + return error diff --git a/pymobile/cli_parser.py b/pymobile/cli_parser.py index 07fb75d..b4209d0 100644 --- a/pymobile/cli_parser.py +++ b/pymobile/cli_parser.py @@ -146,6 +146,18 @@ def build_parser( help="explicitly bypass the native startup check for Android-only startup; " "prints an unverified-launch warning", ) + build.add_argument( + "--bundle", + action="store_true", + help="also write the .aab Google Play requires (implies --native); verified " + "with bundletool when a JDK and bundletool.jar are available", + ) + build.add_argument( + "--debug", + action="store_true", + help="mark a native APK debuggable (adb run-as, Layout Inspector, Android Studio " + "debugger); never combine it with a release keystore", + ) build.add_argument("--clean", action="store_true", help="rebuild from scratch") build.add_argument("--no-cache", action="store_true", help="ignore the incremental cache") build.add_argument("--optimize", action="store_true", help="ship bytecode instead of sources") @@ -234,6 +246,18 @@ def build_parser( "or a proxy rewrites the origin" ), ) + run.add_argument( + "--allow-host", + metavar="HOST", + action="append", + default=[], + help=( + "with --web: also accept this Host name on a preview without a " + "token (repeatable). Only a reverse proxy needs it: by default a " + "local preview answers to localhost, 127.0.0.1 and [::1] only, " + "which is what blocks DNS-rebinding pages" + ), + ) run.add_argument( "--embed", action="store_true", diff --git a/pymobile/cli_preview.py b/pymobile/cli_preview.py index 6d0c1b9..5563be7 100644 --- a/pymobile/cli_preview.py +++ b/pymobile/cli_preview.py @@ -372,8 +372,8 @@ def cmd_preview(args: argparse.Namespace) -> int: cli._out.ok(f"wrote the text preview to {path}") elif args.png: width, height = cli._parse_size(getattr(args, "size", None)) - # П-05: surface size validation as an expected error instead of the - # generic "unexpected error: width must be at least 120 dp". + # Surface size validation as an expected error instead of the generic + # "unexpected error: width must be at least 120 dp". if width < 120: raise PyMobileError( "width must be at least 120 dp", diff --git a/pymobile/cli_tools.py b/pymobile/cli_tools.py index fdc468b..e5dc5ce 100644 --- a/pymobile/cli_tools.py +++ b/pymobile/cli_tools.py @@ -103,6 +103,41 @@ def cmd_complete(args: argparse.Namespace) -> int: return 0 +def _check_install_space() -> None: + """Report free space where the SDK gets installed, not where the project lives. + + ``build --native`` writes the SDK, build-tools and the Gradle caches into + ``PYMOBILE_SDK_HOME`` (``~/.andro`` by default) — a few GiB. The check used + to measure ``config.root``, so a project on a large disk and a home + directory on a small one passed the check and then failed mid-download with + ``No space left on device``; the reverse — a small project disk under a big + home — produced a warning that could not be acted on. + """ + _out = cli._out + from .compiler import sdk_installer + from .compiler.toolchain import _sdk_root + + install = sdk_installer.default_sdk_home() + try: + probe = install + while not probe.exists() and probe != probe.parent: + probe = probe.parent + free = shutil.disk_usage(probe).free + except OSError as exc: + _out.warn(f"could not check disk space for {install}: {exc}") + return + sdk = _sdk_root() + where = f"{install}" + (f" (SDK at {sdk})" if sdk and sdk.is_relative_to(install) else "") + if free < 1024**3: + _out.warn(f"only {free / 1024**3:.1f} GiB free in {where}; native setup needs ~1 GiB") + _out.hint( + "Point PYMOBILE_SDK_HOME at a larger disk, or free space, " + f"then run `{cli._invocation()} setup-sdk`." + ) + else: + _out.ok(f"disk space: {free / 1024**3:.1f} GiB free in {where}") + + def cmd_doctor(args: argparse.Namespace) -> int: """Check the environment and configuration.""" _out, _load, _invocation = cli._out, cli._load, cli._invocation @@ -160,15 +195,7 @@ def cmd_doctor(args: argparse.Namespace) -> int: _out.warn("Desktop preview: not ready — the entry point is missing") _out.info("Native APK — project and toolchain checks") - try: - free = shutil.disk_usage(config.root).free - if free < 1024**3: - _out.warn(f"only {free / 1024**3:.1f} GiB free; native setup needs ~1 GiB") - _out.hint("Free disk space or choose another setup location with setup-sdk --path.") - else: - _out.ok(f"disk space: {free / 1024**3:.1f} GiB free") - except OSError as exc: - _out.warn(f"could not check disk space: {exc}") + _check_install_space() from .compiler.toolchain import ToolchainError, find_toolchain diff --git a/pymobile/compiler/backends/native.py b/pymobile/compiler/backends/native.py index d03d807..8f82241 100644 --- a/pymobile/compiler/backends/native.py +++ b/pymobile/compiler/backends/native.py @@ -30,7 +30,8 @@ from ...errors import PyMobileError, ResourceError from ...log import get_logger from ...resources import resource_path -from ..manifest import build_manifest +from ..icon import round_icon_xml, write_adaptive_icon +from ..manifest import build_manifest, network_security_config from ..packager import FIXED_TIMESTAMP from ..toolchain import Toolchain @@ -169,6 +170,7 @@ def debug_keystore_path(package: str) -> Path: folder = Path(base).expanduser() if base else Path.home() / ".pymobile" / "keystores" return folder / f"{package}-debug.jks" + #: Parts of the standard library that are never needed on a phone. #: #: ``config-*`` is matched by prefix rather than by name: the directory is @@ -209,6 +211,26 @@ def debug_keystore_path(package: str) -> Path: "pydoc.py", "this.py", "antigravity.py", + # An app on a phone has no terminal, no GUI toolkit and no use for the + # developer tooling around tkinter/idlelib. Shipping them was most of what + # made a minimal build only 0.5 MB smaller than a full one. + "tkinter", + "idlelib", + "turtledemo", + "ensurepip", + "lib2to3", + "asyncio", + "concurrent", + "multiprocessing", + "cgi.py", + "pipes.py", + "smtplib.py", + "ftplib.py", + "telnetlib.py", + "imaplib.py", + "poplib.py", + "nntplib.py", + "distutils", ) #: Dropped by ``--no-ssl`` alongside the OpenSSL shared libraries. @@ -281,6 +303,7 @@ def format_javac_failure( directory when the overlay is what failed), and the most common causes are named explicitly. """ + def relative(name: str) -> str: """Drop the scratch-directory prefix; a build path is noise to a user.""" if root is None: @@ -298,9 +321,7 @@ def relative(name: str) -> str: errors = [line for line in diagnostics if ": error:" in line] count = len(errors) summary = ( - f"javac reported {count} error{'s' if count != 1 else ''}" - if count - else "javac failed" + f"javac reported {count} error{'s' if count != 1 else ''}" if count else "javac failed" ) shown = (errors or diagnostics)[:6] more = "" @@ -384,10 +405,13 @@ def __init__( key_alias: str | None = None, key_password: str | None = None, abi: str = "arm64-v8a", + debuggable: bool = False, ) -> None: self.config = config self.toolchain = toolchain self.python_runtime = python_runtime + #: ``android:debuggable="true"`` — ``build --native --debug`` only. + self.debuggable = debuggable self.app_name = _literal_app_name(config.entrypoint_path) or config.name #: True when the caller supplied a keystore path (release signing). self._release_keystore = keystore is not None @@ -415,6 +439,9 @@ def __init__( #: Assets that are generated rather than copied from a file: #: ``assets/pymobile.properties`` and the entry-point bootstrap. self._extra_assets: dict[str, bytes] = {} + #: Assets written by the last :meth:`collect_assets` call (read by the + #: ``--bundle`` stage). + self.last_assets: dict[str, Path] = {} #: Entry point as declared in pymobile.toml, and how it was packaged. self._entrypoint = "main.py" self._entrypoint_type = "py" @@ -423,13 +450,28 @@ def __init__( self._payload_digest = "" # -- 0. entry point ---------------------------------------------------- + @property + def entrypoint_name(self) -> str: + """The entry point recorded for the launcher (see ``set_entrypoint``).""" + return self._entrypoint + + @property + def entrypoint_type(self) -> str: + """``py`` or ``pyc``: how the entry point was packaged.""" + return self._entrypoint_type + + @property + def payload_digest(self) -> str: + """The payload digest the launcher compares to decide re-extraction.""" + return self._payload_digest + def set_payload_digest(self, digest: str) -> None: """Record the build fingerprint the launcher uses as an install stamp. ``PythonRuntime`` extracts its Python payload once per versionCode. ``edit → build → adb install -r`` keeps versionCode at 1, so the APK was replaced and the old application files stayed on disk behind a - successful reinstall (PM-29). The digest makes the stamp change + successful reinstall. The digest makes the stamp change whenever the packaged content does. """ self._payload_digest = digest[:32] @@ -659,8 +701,7 @@ def compile_java(self, workdir: Path) -> Path: # the prefix keeps the stage name in the message. raise PyMobileError( f"could not compile the project Java overlay: {error}", - hint=error.hint - or "Check the Java sources in the project's java/ directory.", + hint=error.hint or "Check the Java sources in the project's java/ directory.", ) from error detail = f" {error.hint}" if error.hint else "" self.warnings.append(f"falling back to the prebuilt dex:{detail}") @@ -745,23 +786,23 @@ def _compile_java_from_source(self, workdir: Path) -> Path: _run( [ self.toolchain.javac, - "-source", - "8", - "-target", - "8", - # Sources may contain non-ASCII UI strings; javac defaults to - # the platform encoding, which is often US-ASCII in containers. - "-encoding", - "UTF-8", - "-nowarn", - "-bootclasspath", - self.toolchain.platform_jar, - "-classpath", - self.toolchain.platform_jar, - "-d", - classes, - *sorted(src.rglob("*.java")), - ], + "-source", + "8", + "-target", + "8", + # Sources may contain non-ASCII UI strings; javac defaults to + # the platform encoding, which is often US-ASCII in containers. + "-encoding", + "UTF-8", + "-nowarn", + "-bootclasspath", + self.toolchain.platform_jar, + "-classpath", + self.toolchain.platform_jar, + "-d", + classes, + *sorted(src.rglob("*.java")), + ], step="javac", java_home=self.toolchain.java_home, ) @@ -773,9 +814,7 @@ def _compile_java_from_source(self, workdir: Path) -> Path: summary, hint = format_javac_failure( error.hint or str(error), overlay=is_overlay, root=src ) - source = ( - "the project's java/ overlay" if is_overlay else "the launcher sources" - ) + source = "the project's java/ overlay" if is_overlay else "the launcher sources" raise PyMobileError(f"{summary} while compiling {source}", hint=hint) from error # Feed d8 a single jar rather than every .class path: it keeps the @@ -811,12 +850,22 @@ def link_resources(self, workdir: Path, icons: dict[str, Path]) -> Path: """Compile resources and link the base APK with a binary manifest.""" res = workdir / "res" for density, icon in icons.items(): - target = res / f"mipmap-{density}" / "icon.png" + target = res / f"mipmap-{density}" / "ic_launcher.png" target.parent.mkdir(parents=True, exist_ok=True) # The icon stage may already have written straight into res/. if icon.resolve() != target.resolve(): shutil.copy2(icon, target) + # Adaptive icon (Android 8+): legacy squares alone are shrunk into a + # white tile by launchers that mask icons, and Android 13+ has nothing + # to tint without a monochrome layer. + source = next(iter(icons.values()), None) + if source is not None: + write_adaptive_icon(source, res) + anydpi = res / "mipmap-anydpi-v26" + anydpi.mkdir(parents=True, exist_ok=True) + (anydpi / "ic_launcher_round.xml").write_text(round_icon_xml(), encoding="utf-8") + values = res / "values" values.mkdir(parents=True, exist_ok=True) (values / "strings.xml").write_text( @@ -827,6 +876,13 @@ def link_resources(self, workdir: Path, icons: dict[str, Path]) -> Path: encoding="utf-8", ) + if self.config.network_pins: + xml_dir = res / "xml" + xml_dir.mkdir(parents=True, exist_ok=True) + (xml_dir / "network_security_config.xml").write_text( + network_security_config(self.config.network_pins), encoding="utf-8" + ) + flat = workdir / "flat" flat.mkdir(parents=True, exist_ok=True) _run([self.toolchain.aapt2, "compile", "--dir", res, "-o", flat], step="aapt2 compile") @@ -837,6 +893,7 @@ def link_resources(self, workdir: Path, icons: dict[str, Path]) -> Path: self.config, activity="org.pymobile.app.MainActivity", app_name=self.app_name, + debuggable=self.debuggable, ), encoding="utf-8", ) @@ -881,7 +938,12 @@ def _is_excluded(self, relative: Path) -> bool: return False def collect_assets(self, sources: list[tuple[str, Path]]) -> dict[str, Path]: - """Map archive paths to files for the stdlib and the application.""" + """Map archive paths to files for the stdlib and the application. + + The map is also kept on the backend (``last_assets``) because the + ``--bundle`` stage writes the same files into ``base/assets/`` and must + not walk the runtime a second time. + """ assets: dict[str, Path] = {} stdlib = self.python_runtime / "lib" / "python3.14" @@ -921,6 +983,9 @@ def collect_assets(self, sources: list[tuple[str, Path]]) -> dict[str, Path]: shim = self._entrypoint_shim(sources) if shim is not None: self._extra_assets["assets/app/main.py"] = shim + # The bundle stage writes exactly these files into base/assets/; keeping + # the map here avoids walking the stdlib a second time. + self.last_assets = dict(assets) return assets def _entrypoint_shim(self, sources: list[tuple[str, Path]]) -> bytes | None: @@ -947,9 +1012,7 @@ def _entrypoint_shim(self, sources: list[tuple[str, Path]]) -> bytes | None: "will not be used until the launcher is rebuilt from its Java sources." ) return None - _log.debug( - "adding a main.py bootstrap for the declared entry point %s", self._entrypoint - ) + _log.debug("adding a main.py bootstrap for the declared entry point %s", self._entrypoint) return ( self._LAUNCHER_SHIM % { @@ -1004,13 +1067,19 @@ def entry(name: str, *, stored: bool = False, mode: int | None = None) -> zipfil data, ) archive.writestr(entry("classes.dex"), dex.read_bytes()) - for library in sorted(native_dir.glob("*.so")): + # ``native_dir`` is either one ABI's directory (lib//) or the + # shared lib/ root when the pipeline built more than one ABI; the + # archive path keeps the ABI component either way. + for library in sorted(native_dir.rglob("*.so")): + relative = library.relative_to(native_dir) + name = ( + f"lib/{relative.as_posix()}" + if len(relative.parts) > 1 + else f"lib/{self.abi}/{library.name}" + ) # Native libraries must be stored uncompressed and page-aligned # so Android can load them directly from the APK. - archive.writestr( - entry(f"lib/{self.abi}/{library.name}", stored=True, mode=0o755), - library.read_bytes(), - ) + archive.writestr(entry(name, stored=True, mode=0o755), library.read_bytes()) for name, path in sorted(assets.items()): archive.writestr(entry(name), path.read_bytes()) for name, payload in sorted(self._extra_assets.items()): @@ -1274,8 +1343,10 @@ def _literal_app_name(entrypoint: Path) -> str | None: for node in ast.walk(tree): if not isinstance(node, ast.Call): continue - function = node.func.id if isinstance(node.func, ast.Name) else ( - node.func.attr if isinstance(node.func, ast.Attribute) else "" + function = ( + node.func.id + if isinstance(node.func, ast.Name) + else (node.func.attr if isinstance(node.func, ast.Attribute) else "") ) if function != "App": continue diff --git a/pymobile/compiler/bundle.py b/pymobile/compiler/bundle.py new file mode 100644 index 0000000..259d016 --- /dev/null +++ b/pymobile/compiler/bundle.py @@ -0,0 +1,249 @@ +"""Android App Bundle (``.aab``) output. + +Google Play stopped accepting APKs for new apps and updates: it wants an +``.aab`` and generates per-device APKs from it. PyMobile built APKs only, so a +finished, signed, installable app could not be uploaded at all. + +An app bundle is a ZIP with a fixed layout:: + + BundleConfig.pb protobuf settings (bundletool validates the rest) + base/manifest/AndroidManifest.xml + base/dex/classes.dex + base/assets/… every asset the APK carries under assets/ + base/lib//… native libraries + base/res/… compiled resources (the aapt2 output) + base/resources.pb resource table + BUNDLE-METADATA/… optional + +The files themselves are the ones a native build already produces; this module +only arranges them in that layout, writes the ``BundleConfig.pb`` aapt2 does not +emit by itself, and then runs ``bundletool build-apks --mode=universal`` to prove +the bundle is valid and installable — the only check that matters to a store +upload. + +The protobuf for ``BundleConfig`` is encoded by hand (a handful of fields, no +runtime dependency on ``protobuf``); ``bundletool validate`` is what proves the +encoding is right, and the test suite runs it when a JDK is available. +""" + +from __future__ import annotations + +import json +import shutil +import subprocess +from dataclasses import dataclass +from pathlib import Path + +from ..errors import PyMobileError +from ..log import get_logger + +__all__ = ["BundleResult", "build_bundle", "write_bundle_config", "COMPRESSION_SUFFIXES"] + +_log = get_logger("compiler.bundle") + +#: Suffixes bundletool requires to stay uncompressed in the bundle, because the +#: platform maps them and reads them directly (native libraries and the dex). +COMPRESSION_SUFFIXES = (".so", ".dex") + + +@dataclass(frozen=True, slots=True) +class BundleResult: + """The written ``.aab`` and what went into it.""" + + path: Path + size: int + entries: int + universal_apk: Path | None = None + + +def _varint(value: int) -> bytes: + """Protocol-buffers base-128 varint.""" + out = bytearray() + while True: + byte = value & 0x7F + value >>= 7 + if value: + out.append(byte | 0x80) + else: + out.append(byte) + return bytes(out) + + +def _field_bytes(number: int, payload: bytes) -> bytes: + """A length-delimited field (wire type 2).""" + return _varint((number << 3) | 2) + _varint(len(payload)) + payload + + +def _field_varint(number: int, value: int) -> bytes: + """A varint field (wire type 0).""" + return _varint(number << 3) + _varint(value) + + +def write_bundle_config(*, version_code: int = 1) -> bytes: + """Encode ``BundleConfig.pb``. + + ``BundleConfig`` field 1 is ``bundletool`` (a message holding the version + that wrote the bundle), field 2 ``optimizations`` (empty: no splits are + configured), and ``compression`` (field 3) lists the suffixes that must stay + uncompressed. ``version_code`` is not part of ``BundleConfig`` — it lives in + the manifest — and is accepted so a caller cannot silently drop it. + """ + del version_code # the manifest carries it; kept for a stable signature + bundletool = _field_bytes(1, _field_bytes(1, b"1.18.1")) + _field_bytes(2, b"0.15.0") + compression = b"".join( + _field_bytes(1, suffix.encode("ascii")) for suffix in COMPRESSION_SUFFIXES + ) + # field 4 is `uncompress_native_libraries`; 5 `master_resources`; both are + # left unset: the defaults are what a store expects. + body = _field_bytes(1, bundletool) + _field_bytes(3, compression) + _field_varint(6, 1) + return body + + +def _copy_tree(source: Path, target: Path) -> int: + """Copy every file under ``source`` into ``target``; return the count.""" + if not source.is_dir(): + return 0 + count = 0 + for path in sorted(source.rglob("*")): + if not path.is_file(): + continue + destination = target / path.relative_to(source) + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(path, destination) + count += 1 + return count + + +def _run_bundletool(java: Path, bundletool: Path, *args: str) -> str: + """Run a bundletool command and return its stdout.""" + result = subprocess.run( + [str(java), "-jar", str(bundletool), *args], + capture_output=True, + text=True, + check=False, + ) + if result.returncode != 0: + detail = (result.stderr or result.stdout).strip().splitlines()[-6:] + raise PyMobileError( + "bundletool rejected the app bundle", + hint="\n".join(detail) or "run with --verbose for the whole output", + ) + return result.stdout + + +def build_bundle( + output: Path, + *, + manifest: Path, + dex: Path, + assets: Path, + libraries: Path | None = None, + resources: Path | None = None, + resource_table: Path | None = None, +) -> BundleResult: + """Arrange a native build's artifacts into an ``.aab``. + + ``manifest`` is the *binary* manifest aapt2 produced (not the XML source): + a bundle stores the same compiled form an APK does. + """ + import zipfile + + output.parent.mkdir(parents=True, exist_ok=True) + temporary = output.with_suffix(output.suffix + ".tmp") + entries = 0 + try: + with zipfile.ZipFile(temporary, "w", compression=zipfile.ZIP_DEFLATED) as archive: + + def write(name: str, data: bytes, *, store: bool = False) -> None: + nonlocal entries + info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0)) + info.compress_type = zipfile.ZIP_STORED if store else zipfile.ZIP_DEFLATED + info.external_attr = 0o644 << 16 + archive.writestr(info, data) + entries += 1 + + write("BundleConfig.pb", write_bundle_config(), store=False) + write("base/manifest/AndroidManifest.xml", manifest.read_bytes()) + write("base/dex/classes.dex", dex.read_bytes(), store=True) + + if resource_table is not None and resource_table.is_file(): + write("base/resources.pb", resource_table.read_bytes()) + + if assets.is_dir(): + for path in sorted(assets.rglob("*")): + if not path.is_file(): + continue + name = "base/assets/" + path.relative_to(assets).as_posix() + store = path.suffix.lower() in COMPRESSION_SUFFIXES + write(name, path.read_bytes(), store=store) + + if libraries is not None and libraries.is_dir(): + for path in sorted(libraries.rglob("*")): + if not path.is_file(): + continue + relative = path.relative_to(libraries) + # A bundle keeps native code in base/lib//, exactly + # where the platform loads it from inside the APK. + write(f"base/lib/{relative.as_posix()}", path.read_bytes(), store=True) + + if resources is not None and resources.is_dir(): + for path in sorted(resources.rglob("*")): + if not path.is_file(): + continue + write( + "base/" + path.relative_to(resources).as_posix(), + path.read_bytes(), + store=path.suffix.lower() in COMPRESSION_SUFFIXES, + ) + + temporary.replace(output) + finally: + temporary.unlink(missing_ok=True) + + size = output.stat().st_size + _log.debug("wrote %s (%d entries, %d bytes)", output.name, entries, size) + return BundleResult(path=output, size=size, entries=entries) + + +def validate_bundle( + bundle: Path, *, java: Path, bundletool: Path, universal: Path | None = None +) -> Path | None: + """Ask bundletool whether the bundle is acceptable, and build a universal APK. + + Returns the universal APK when requested. ``bundletool build-apks`` reads + the whole bundle — the protobuf, the manifest, every split — so a bundle + that satisfies it is one Play can accept; a plain ``zipfile`` check proves + only that the ZIP is not corrupt. + """ + _run_bundletool(java, bundletool, "validate", "--bundle", str(bundle)) + if universal is None: + return None + universal.parent.mkdir(parents=True, exist_ok=True) + _run_bundletool( + java, + bundletool, + "build-apks", + "--bundle", + str(bundle), + "--output", + str(universal), + "--mode=universal", + "--overwrite", + ) + return universal + + +def bundletool_path(candidates: list[Path]) -> Path | None: + """The first ``bundletool*.jar`` that exists among ``candidates``.""" + for candidate in candidates: + if candidate.is_file(): + return candidate + return None + + +def describe(bundle: BundleResult) -> str: + """One-line summary for the CLI.""" + return json.dumps( + {"aab": str(bundle.path), "size": bundle.size, "entries": bundle.entries}, + ensure_ascii=False, + ) diff --git a/pymobile/compiler/collector.py b/pymobile/compiler/collector.py index dd76468..6b89cdd 100644 --- a/pymobile/compiler/collector.py +++ b/pymobile/compiler/collector.py @@ -148,6 +148,39 @@ def _is_excluded(relative: Path, patterns: Sequence[str]) -> bool: return False +#: File names that are credentials often enough to keep out of an APK even +#: when the project does not exclude them: a shell profile, a cloud key, a +#: local editor secret. The default `exclude` covers the common patterns; this +#: is the last line for the ones a user is unlikely to think about. +_CREDENTIAL_NAMES = frozenset( + { + ".netrc", + ".npmrc", + ".pypirc", + ".git-credentials", + ".htpasswd", + "known_hosts", + "local.properties", + } +) + +#: Suffixes that hold a private key or a packaged certificate. +_CREDENTIAL_SUFFIXES = frozenset({".p12", ".pfx", ".ovpn", ".key", ".pem"}) + + +def is_credential_file(path: Path) -> bool: + """Whether ``path`` looks like a credential that must not ship in an APK.""" + name = path.name.lower() + return ( + name in _CREDENTIAL_NAMES + or name.startswith("credentials.") + or name.startswith("secrets.") + or name.startswith("id_rsa") + or name.startswith("id_ed25519") + or path.suffix.lower() in _CREDENTIAL_SUFFIXES + ) + + def collect_sources( source_dir: Path, entrypoint: Path, @@ -158,6 +191,10 @@ def collect_sources( """Walk ``source_dir`` and return the set of files to package. ``include_suffixes`` defaults to Python sources plus common asset types. + Credential-looking files (``.netrc``, ``credentials.json``, ``*.pem``) and + the contents of ``secret/``-style folders are skipped outright, so an APK + never carries a token just because the project did not think to exclude + one; the build reports each skipped file in its warnings. """ source_dir = source_dir.resolve() if not source_dir.is_dir(): @@ -188,6 +225,8 @@ def collect_sources( continue if _is_excluded(relative, exclude): continue + if is_credential_file(relative): + continue collected.append(path) if entrypoint not in collected: diff --git a/pymobile/compiler/icon.py b/pymobile/compiler/icon.py index 14371be..9dd765c 100644 --- a/pymobile/compiler/icon.py +++ b/pymobile/compiler/icon.py @@ -4,6 +4,10 @@ * a custom icon given in the config is validated and resized to every density; * when none is set, the packaged default Android-style icon is used; +* an **adaptive** icon (``mipmap-anydpi-v26``: a background layer, a foreground + layer and a monochrome layer) is written next to the legacy squares, so + Android 8+ masks the icon to the launcher's shape instead of shrinking a + square into a white tile, and Android 13+ can tint the monochrome one; * Pillow is optional — without it a valid single-density icon is still emitted, so a build never fails just because an image library is missing. """ @@ -18,7 +22,7 @@ from ..log import get_logger from ..resources import default_icon_path -__all__ = ["IconSet", "prepare_icons", "DENSITIES"] +__all__ = ["IconSet", "prepare_icons", "DENSITIES", "ADAPTIVE_DENSITIES", "write_adaptive_icon"] _log = get_logger("compiler.icon") @@ -31,6 +35,17 @@ "xxxhdpi": 192, } +#: Edge length of each adaptive layer. The launcher shows the middle 72 of the +#: 108 units and may mask it to any shape, so the artwork is drawn at that size +#: and the safe zone keeps the visible part inside a circle of 66 units. +ADAPTIVE_DENSITIES: dict[str, int] = { + "mdpi": 108, + "hdpi": 162, + "xhdpi": 216, + "xxhdpi": 324, + "xxxhdpi": 432, +} + _SUPPORTED_SUFFIXES = {".png", ".jpg", ".jpeg", ".webp"} @@ -66,7 +81,7 @@ def _validate_source(icon: Path) -> None: def prepare_icons(icon: Path | None, output_dir: Path) -> IconSet: - """Write ``icon.png`` into ``mipmap-*`` folders under ``output_dir``. + """Write ``ic_launcher.png`` into ``mipmap-*`` folders under ``output_dir``. Falls back to the bundled default when ``icon`` is ``None``. """ @@ -101,7 +116,7 @@ def _resize_all(source: Path, output_dir: Path) -> dict[str, Path] | None: for density, size in DENSITIES.items(): target_dir = output_dir / f"mipmap-{density}" target_dir.mkdir(parents=True, exist_ok=True) - target = target_dir / "icon.png" + target = target_dir / "ic_launcher.png" rgba.resize((size, size), resample).save(target, format="PNG", optimize=True) files[density] = target return files @@ -113,7 +128,104 @@ def _copy_all(source: Path, output_dir: Path) -> dict[str, Path]: for density in DENSITIES: target_dir = output_dir / f"mipmap-{density}" target_dir.mkdir(parents=True, exist_ok=True) - target = target_dir / "icon.png" + target = target_dir / "ic_launcher.png" shutil.copyfile(source, target) files[density] = target return files + + +def write_adaptive_icon(source: Path, res_dir: Path) -> list[Path]: + """Write an Android 8+ adaptive icon built from ``source``. + + Three layers are produced per density: + + * ``ic_launcher_background.png`` — ``source`` scaled to fill the canvas and + blurred, so a photo icon still reads as one colour behind the artwork; + * ``ic_launcher_foreground.png`` — ``source`` fitted inside the 66/108 safe + zone, so no launcher mask can clip it; + * ``ic_launcher_monochrome.png`` — the same shape in white on transparent, + which Android 13+ tints to the user's theme. + + ``mipmap-anydpi-v26/ic_launcher.xml`` ties them together; the legacy + ``mipmap-/icon.png`` files stay for Android 7, which ignores + ``-anydpi-v26``. Returns the files written, also when Pillow is missing + (then the foreground is a copy of ``source`` and the XML still works). + """ + written: list[Path] = [] + try: + from PIL import Image, ImageFilter + except ImportError: + Image = None # type: ignore[assignment] + + for density, size in ADAPTIVE_DENSITIES.items(): + folder = res_dir / f"mipmap-{density}" + folder.mkdir(parents=True, exist_ok=True) + if Image is None: + for name in ("ic_launcher_background.png", "ic_launcher_foreground.png"): + target = folder / name + shutil.copyfile(source, target) + written.append(target) + continue + + resample = getattr(Image, "Resampling", Image).LANCZOS + with Image.open(source) as opened: + rgba = opened.convert("RGBA") + + background = rgba.resize((size, size), resample) + background = background.filter(ImageFilter.GaussianBlur(radius=size / 24)) + background_path = folder / "ic_launcher_background.png" + background.convert("RGB").save(background_path, format="PNG", optimize=True) + written.append(background_path) + + safe = round(size * 66 / 108) + foreground = Image.new("RGBA", (size, size), (0, 0, 0, 0)) + scaled = rgba.copy() + scaled.thumbnail((safe, safe), resample) + foreground.alpha_composite( + scaled, + ((size - scaled.width) // 2, (size - scaled.height) // 2), + ) + foreground_path = folder / "ic_launcher_foreground.png" + foreground.save(foreground_path, format="PNG", optimize=True) + written.append(foreground_path) + + # A monochrome layer is an alpha mask: Android ignores its colours + # and tints whatever is opaque. + alpha = foreground.getchannel("A") + monochrome = Image.new("RGBA", (size, size), (255, 255, 255, 0)) + monochrome.putalpha(alpha) + monochrome_path = folder / "ic_launcher_monochrome.png" + monochrome.save(monochrome_path, format="PNG", optimize=True) + written.append(monochrome_path) + + anydpi = res_dir / "mipmap-anydpi-v26" + anydpi.mkdir(parents=True, exist_ok=True) + xml = anydpi / "ic_launcher.xml" + xml.write_text( + '\n' + '\n' + ' \n' + ' \n' + ' \n' + "\n", + encoding="utf-8", + ) + written.append(xml) + _log.debug("wrote %d adaptive icon layers", len(written)) + return written + + +def round_icon_xml() -> str: + """``mipmap-anydpi-v26/ic_launcher_round.xml`` — the same layers, round mask. + + Launchers that ask for ``android:roundIcon`` fall back to nothing when the + resource is absent, so a round-masked launcher drew the square legacy icon. + """ + return ( + '\n' + '\n' + ' \n' + ' \n' + ' \n' + "\n" + ) diff --git a/pymobile/compiler/manifest.py b/pymobile/compiler/manifest.py index 1cb99e4..1fc07a4 100644 --- a/pymobile/compiler/manifest.py +++ b/pymobile/compiler/manifest.py @@ -33,10 +33,15 @@ def __init__( *, activity: str = "org.kivy.android.PythonActivity", app_name: str | None = None, + debuggable: bool = False, ): self.config = config self.activity = activity self.app_name = app_name if app_name is not None else config.name + #: ``android:debuggable="true"``. Off unless the build asked for it: a + #: debuggable APK lets any holder of the (public, well-known) debug + #: certificate attach a debugger and run ``adb shell`` as the app. + self.debuggable = debuggable def _attr(self, element: ET.Element, name: str, value: str) -> None: """Set an ``android:`` namespaced attribute.""" @@ -63,7 +68,12 @@ def build_tree(self) -> ET.Element: application = ET.SubElement(manifest, "application") self._attr(application, "label", self.app_name) - self._attr(application, "icon", "@mipmap/icon") + # The adaptive icon file name. Android prefers `@mipmap/ic_launcher` + # whenever it is present (mipmap-anydpi-v26), and falls back to the + # legacy `icon.png` squares on Android 7 only through the same name — + # so the packaged legacy squares are written as `ic_launcher.png` too. + self._attr(application, "icon", "@mipmap/ic_launcher") + self._attr(application, "roundIcon", "@mipmap/ic_launcher_round") # Backups copy the private store (tokens, personal data) off the # device; opt in with `allow_backup = true`. self._attr(application, "allowBackup", "true" if config.allow_backup else "false") @@ -71,6 +81,25 @@ def build_tree(self) -> ET.Element: # Back gestures arrive through OnBackInvokedCallback (API 33+); # onBackPressed() is deprecated and ignored with predictive back. self._attr(application, "enableOnBackInvokedCallback", "true") + # Without this the framework never mirrors the layout for Arabic or + # Hebrew, however the margins are expressed (they are start/end now). + self._attr(application, "supportsRtl", "true") + # `adb shell run-as`, Layout Inspector and the Android Studio debugger + # all refuse to attach to a non-debuggable app — including one signed + # with the debug certificate, which is what a plain `build --native` + # produces. Opt in with `build --native --debug`. + if self.debuggable: + self._attr(application, "debuggable", "true") + + # -- certificate pinning (S7) -------------------------------------- + # Android honours only through a meta-data + # reference; the file itself is a resource, written by the native + # backend. Only the domains listed are pinned, everything else keeps + # the system trust store. + if config.network_pins: + meta = ET.SubElement(application, "meta-data") + self._attr(meta, "name", "android.security.networkSecurityConfig") + self._attr(meta, "resource", "@xml/network_security_config") activity = ET.SubElement(application, "activity") self._attr(activity, "name", self.activity) @@ -108,15 +137,55 @@ def to_xml(self, *, pretty: bool = True) -> str: return "\n".join(lines) + "\n" +def _xml_escape(text: str) -> str: + """Escape a value for an XML text node or attribute.""" + return ( + str(text) + .replace("&", "&") + .replace("<", "<") + .replace(">", ">") + .replace('"', """) + ) + + +def network_security_config(pins: dict[str, list[str]]) -> str: + """The ``res/xml/network_security_config.xml`` for a pinned build (S7). + + Each listed domain trusts *only* the given certificates. ``cleartextTraffic`` + stays denied, exactly as it is without a config, so this cannot accidentally + re-enable plain HTTP. + """ + lines = [ + '', + "", + ' ', + ] + for domain in sorted(pins): + lines.append(' ') + lines.append(f' {_xml_escape(domain)}') + lines.append(" ") + for pin in pins[domain]: + digest = pin[len("sha256/") :] if pin.startswith("sha256/") else pin + lines.append(f' {_xml_escape(digest)}') + lines.append(" ") + lines.append(" ") + lines.append("") + return "\n".join(lines) + "\n" + + def build_manifest( config: ProjectConfig, *, pretty: bool = True, activity: str = "org.kivy.android.PythonActivity", app_name: str | None = None, + debuggable: bool = False, ) -> str: """Convenience wrapper around :class:`ManifestBuilder`. ``activity`` selects the launcher class; the native backend passes its own. + ``debuggable`` adds ``android:debuggable="true"`` for a ``--debug`` build. """ - return ManifestBuilder(config, activity=activity, app_name=app_name).to_xml(pretty=pretty) + return ManifestBuilder( + config, activity=activity, app_name=app_name, debuggable=debuggable + ).to_xml(pretty=pretty) diff --git a/pymobile/compiler/pipeline.py b/pymobile/compiler/pipeline.py index 9bfc42d..63f1833 100644 --- a/pymobile/compiler/pipeline.py +++ b/pymobile/compiler/pipeline.py @@ -119,7 +119,7 @@ def find_bytecode_interpreter() -> str | None: #: Directories never considered when reporting files that were not packaged. #: Reuses the same set the collector skips so the warning does not fire on #: cache/tag files inside .pytest_cache/.mypy_cache/.ruff_cache/node_modules -#: (П-19 — the collector already knows about them). +#: (the collector already knows about them). _IGNORED_ASSET_DIRS = frozenset(_ALWAYS_EXCLUDED_DIRS | {".pymobile", "build", "dist"}) #: Names that make ``.notify(...)`` a PyMobile notification: ``app``, @@ -253,10 +253,20 @@ def __init__( keystore_password: str | None = None, key_alias: str | None = None, key_password: str | None = None, + debug: bool = False, + bundle: bool = False, ) -> None: self.config = config self.use_cache = use_cache self.native = native + #: ``build --native --bundle``: also write the ``.aab`` Google Play + #: requires (an APK cannot be uploaded any more). + self.bundle = bundle + #: ``build --native --debug``: add ``android:debuggable="true"`` so + #: `adb shell run-as`, Layout Inspector and the Android Studio debugger + #: can attach. Refused together with a release keystore — a debuggable + #: APK must never be the artifact a store or a user installs. + self.debug = debug self.check_startup = native if check_startup is None else check_startup self.on_stage = on_stage self.keystore = keystore @@ -293,6 +303,25 @@ def _stage(self, name: str, action: Callable[[], Any]) -> Any: def _validate(self) -> None: """Re-check the configuration and warn about likely mistakes.""" self.config.validate() + if self.debug and not self.native: + raise PyMobileError( + "`--debug` only applies to a native APK", + hint="A structural package never installs, so it has nothing to debug. " + "Run `pymobile build --native --debug`.", + ) + if self.bundle and not self.native: + raise PyMobileError( + "`--bundle` needs a native build", + hint="An app bundle contains a compiled APK's contents; a structural " + "package has none. Run `pymobile build --native --bundle`.", + ) + if self.debug and self.keystore is not None: + raise PyMobileError( + "`--debug` cannot be combined with a release keystore", + hint="A debuggable APK lets anything with the key attach a debugger; " + "build and test it without `--keystore`, then sign a release build " + "without `--debug`.", + ) if self.config.min_sdk < self.config.effective_min_sdk: self.warnings.append( f"min_sdk = {self.config.min_sdk} is below what the embedded CPython 3.14 " @@ -313,6 +342,17 @@ def _validate(self) -> None: "Full Python stdlib is included. Use --minimal-stdlib to reduce APK size; " "test the reduced build against your app's imports before distributing." ) + from .sdk_installer import SDK_PLATFORM + + if self.config.target_sdk > SDK_PLATFORM: + self.warnings.append( + f"target_sdk = {self.config.target_sdk} is newer than the Android platform " + f"the toolchain installs (android-{SDK_PLATFORM}): the APK still compiles " + f"against API {SDK_PLATFORM}, so APIs from {self.config.target_sdk} are not " + f"available and behaviour switches meant for it will not apply. " + f"Set target_sdk = {SDK_PLATFORM} in pymobile.toml, or install a newer " + "command-line tools release and rebuild." + ) permissions = {str(p) for p in self.config.permissions} if "android.permission.INTERNET" not in permissions and self._uses_http(): self.warnings.append( @@ -529,7 +569,7 @@ def _warn_about_ignored_assets(self, sources: SourceSet) -> None: against the allowed set (defaults + ``asset_suffixes``), not against what happened to be collected. """ - from .collector import _is_excluded + from .collector import _is_excluded, is_credential_file allowed_suffixes = DEFAULT_ASSET_SUFFIXES | { str(suffix).lower() for suffix in self.config.asset_suffixes @@ -540,6 +580,7 @@ def _warn_about_ignored_assets(self, sources: SourceSet) -> None: java_overlay = self.config.root / "java" ignored: dict[str, int] = {} secret_packaged: list[str] = [] + credentials_skipped: list[str] = [] for path in self.config.source_path.rglob("*"): if not path.is_file(): continue @@ -548,6 +589,11 @@ def _warn_about_ignored_assets(self, sources: SourceSet) -> None: continue if _is_excluded(relative, self.config.exclude): continue + if is_credential_file(relative): + # collect_sources() drops these; say so instead of leaving the + # user to wonder why a file they did not exclude is missing. + credentials_skipped.append(relative.as_posix()) + continue if path.suffix.lower() == ".java": try: path.relative_to(java_overlay) @@ -558,7 +604,7 @@ def _warn_about_ignored_assets(self, sources: SourceSet) -> None: suffix = path.suffix.lower() if suffix and suffix not in allowed_suffixes: ignored[suffix] = ignored.get(suffix, 0) + 1 - # П-03: warn when a secret-like file IS packaged (not excluded). + # Warn when a secret-like file IS packaged (not excluded). if path.name in SECRET_LIKE_BASENAMES or suffix in SECRET_LIKE_SUFFIXES: secret_packaged.append(relative.as_posix()) if ignored: @@ -568,6 +614,19 @@ def _warn_about_ignored_assets(self, sources: SourceSet) -> None: "Add the extensions you need with `asset_suffixes = ['…']` in " "pymobile.toml (read them on device through the packaged app dir)." ) + if credentials_skipped: + listed = ", ".join(sorted(credentials_skipped)[:5]) + more = ( + "" + if len(credentials_skipped) <= 5 + else f" … (+{len(credentials_skipped) - 5} more)" + ) + self.warnings.append( + f"kept out of the APK as credentials: {listed}{more}. " + "Anything inside an APK can be extracted. If one of these is app " + "content rather than a secret, rename it (or read it from " + "`~/.pymobile/` at build time and ship the result)." + ) if secret_packaged: listed = ", ".join(sorted(secret_packaged)[:5]) more = "" if len(secret_packaged) <= 5 else f" … (+{len(secret_packaged) - 5} more)" @@ -579,7 +638,7 @@ def _warn_about_ignored_assets(self, sources: SourceSet) -> None: ) def _check_python_syntax(self, sources: SourceSet) -> None: - """П-06: fail the build on a syntax error instead of shipping broken code. + """Fail the build on a syntax error instead of shipping broken code. ``py_compile`` used to emit a warning and continue, producing an APK that installs but crashes at launch with ImportError. A plain @@ -729,7 +788,7 @@ def _package( ) -> PackageResult: """Write the final archive.""" resources = { - f"res/mipmap-{density}/icon.png": path for density, path in icons.files.items() + f"res/mipmap-{density}/ic_launcher.png": path for density, path in icons.files.items() } entrypoint = sources.entrypoint.relative_to(sources.root).as_posix() packaged = {name for name, _ in entries} @@ -760,7 +819,7 @@ def run(self) -> BuildResult: self._stage("validate", self._validate) self._warn_unexcluded_output() sources: SourceSet = self._stage("collect", self._collect) - # П-06: fail fast on Python syntax errors rather than shipping an + # Fail fast on Python syntax errors rather than shipping an # APK that crashes at launch. self._stage("syntax", lambda: self._check_python_syntax(sources)) self._check_requested_permissions(sources) @@ -809,7 +868,7 @@ def run(self) -> BuildResult: output_dir = self.config.output_path output_dir.mkdir(parents=True, exist_ok=True) - apk_path = output_dir / self.config.apk_name + apk_path = output_dir / self.config.apk_name_for(self.build_mode()) cache = BuildCache(output_dir) fingerprint = self._fingerprint(sources, dependencies) @@ -927,7 +986,8 @@ def _run_native( require_javac=has_project_java or os.environ.get("PYMOBILE_BUILD_JAVA") != "0", ) - runtime = self._stage("runtime", lambda: ensure_runtime(self.config.abis[0])) + primary_abi = self.config.abis[0] + runtime = self._stage("runtime", lambda: ensure_runtime(primary_abi)) backend = NativeBackend( self.config, toolchain, @@ -938,15 +998,9 @@ def _run_native( keystore_password=self.keystore_password, key_alias=self.key_alias, key_password=self.key_password, - abi=self.config.abis[0], + abi=primary_abi, + debuggable=self.debug, ) - if len(self.config.abis) > 1: - # The native backend packages only the first ABI; surfacing this - # beats silently shipping an APK that ignores the rest. - self.warnings.append( - "native builds package only the first requested ABI " - f"({self.config.abis[0]} of {self.config.abis}); build one ABI at a time" - ) # What the launcher has to run: recorded in assets/pymobile.properties # and, for the prebuilt launcher, in a main.py bootstrap as well. @@ -956,10 +1010,10 @@ def _run_native( backend.set_entrypoint(entrypoint_name, entrypoint_type) # The launcher re-extracts its bundled Python when this changes, so an # ``edit → build → adb install -r`` that keeps versionCode = 1 no - # longer leaves the previous build's app code on disk (PM-29). + # longer leaves the previous build's app code on disk. backend.set_payload_digest(fingerprint) - native_dir = self._stage("jni", lambda: backend.compile_jni(workdir)) + native_dir = self._stage("jni", lambda: self._compile_native_libraries(backend, workdir)) dex = self._stage("dex", lambda: backend.compile_java(workdir)) self._verify_renderers(dex) base = self._stage("resources", lambda: backend.link_resources(workdir, icons.files)) @@ -973,6 +1027,9 @@ def _run_native( self.warnings.append("apksigner could not verify the signature") self.warnings.extend(backend.warnings) + if self.bundle: + self._write_app_bundle(backend, workdir, apk_path) + duration = time.perf_counter() - started return BuildResult( apk=signed, @@ -986,6 +1043,199 @@ def _run_native( warnings=list(self.warnings), ) + def _compile_native_libraries(self, backend: NativeBackend, workdir: Path) -> Path: + """Compile ``libpymobile.so`` for every requested ABI into one ``lib/``. + + An APK could only ever carry the first ABI: ``abis = ["arm64-v8a", + "x86_64"]`` silently produced an arm64-only package, so the same file + could not run on an emulator. Each ABI now gets its own + ``lib//`` directory in a single, larger APK (a split APK per ABI + would need a build per ABI and a bundle to ship them). + """ + shared = workdir / "lib" + first: Path | None = None + for index, abi in enumerate(self.config.abis): + if index == 0: + directory = self._stage("jni", lambda: backend.compile_jni(workdir)) + else: + directory = self._stage(f"jni:{abi}", self._secondary_stage(backend, abi, workdir)) + first = first or directory + target = shared / abi + if directory == target: + continue + target.mkdir(parents=True, exist_ok=True) + for library in directory.glob("*.so"): + shutil.copyfile(library, target / library.name) + if len(self.config.abis) > 1: + self.warnings.append( + "APK carries " + ", ".join(self.config.abis) + "; one file for every device, " + "at the size of all of them together. Pick one with --abi for a smaller APK." + ) + return shared + + def _secondary_stage( + self, backend: NativeBackend, abi: str, workdir: Path + ) -> Callable[[], Path]: + """A thunk, so the stage timer sees a call rather than a closure.""" + return lambda: self._compile_secondary_abi(backend, abi, workdir) + + def _compile_secondary_abi(self, backend: NativeBackend, abi: str, workdir: Path) -> Path: + """Run the ABI-independent parts of the build for a second architecture.""" + toolchain = backend.toolchain + runtime = ensure_runtime(abi) + secondary = NativeBackend( + self.config, + toolchain, + runtime, + keystore=self.keystore, + keystore_password=self.keystore_password, + key_alias=self.key_alias, + key_password=self.key_password, + abi=abi, + debuggable=self.debug, + ) + secondary.set_entrypoint(backend.entrypoint_name, backend.entrypoint_type) + secondary.set_payload_digest(backend.payload_digest) + directory = secondary.compile_jni(workdir) + self.warnings.extend(secondary.warnings) + return directory + + def _run_aapt2(self, command: list[str | Path]) -> None: + """Run ``aapt2 link`` (the bundle needs a proto-format second link).""" + from .backends.native import _run + + _run(command, step="aapt2 link (bundle)", java_home=find_toolchain().java_home) + + def _write_app_bundle(self, backend: NativeBackend, workdir: Path, apk_path: Path) -> None: + """Write the ``.aab`` next to the APK and verify it with bundletool. + + The bundle is assembled from the same artifacts the APK used — the + binary manifest, ``classes.dex``, the assets and the native libraries — + so the two cannot drift. ``bundletool validate`` then reads the whole + thing, which is the only check that answers "will Play accept this". + Without a JDK or bundletool the file is still written and a warning says + plainly that it was not verified. + """ + import zipfile + + from .bundle import build_bundle, bundletool_path, validate_bundle + + output = apk_path.with_suffix(".aab") + + def stage() -> None: + # A bundle stores the manifest and the resource table in *protobuf* + # form (proto XmlNode), not as the flat bytes an APK holds. aapt2 + # produces that form itself; hand-copying the APK's bytes made + # bundletool fail with a protobuf parse error. + binary_manifest = workdir / "bundle-manifest.xml" + resource_table = workdir / "resources.pb" + flat = sorted((workdir / "flat").glob("*.flat")) + self._run_aapt2( + [ + str(find_toolchain().aapt2), + "link", + "-o", + str(workdir / "base-proto.apk"), + "-I", + str(find_toolchain().platform_jar), + "--manifest", + str(workdir / "AndroidManifest.xml"), + *[str(path) for path in flat], + "--min-sdk-version", + str(self.config.effective_min_sdk), + "--target-sdk-version", + str(self.config.target_sdk), + "--auto-add-overlay", + "--proto-format", + ] + ) + with zipfile.ZipFile(workdir / "base-proto.apk") as proto: + binary_manifest.write_bytes(proto.read("AndroidManifest.xml")) + resource_table.write_bytes(proto.read("resources.pb")) + asset_tree = workdir / "bundle-assets" + asset_tree.mkdir(parents=True, exist_ok=True) + for name, path in backend.last_assets.items(): + # Archive names start with "assets/"; inside the bundle the + # module's asset directory *is* base/assets/, so the prefix + # would be doubled ("base/assets/assets/app/main.py"). + relative = name[len("assets/") :] if name.startswith("assets/") else name + asset_file = asset_tree / relative + asset_file.parent.mkdir(parents=True, exist_ok=True) + asset_file.write_bytes(path.read_bytes()) + # compile_jni() writes into lib//; a bundle wants the same + # /… path under base/lib/, for every ABI in the build. + library_tree = workdir / "bundle-lib" + library_tree.mkdir(parents=True, exist_ok=True) + for native_lib in sorted((workdir / "lib").rglob("*.so")): + abi_path = native_lib.relative_to(workdir / "lib") + copied = library_tree / abi_path + copied.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(native_lib, copied) + # base/res/ must hold the *proto* resource files the resource + # table points at (`res/mipmap-mdpi-v4/ic_launcher.png`), which are + # the entries of the proto-format APK — not the compiler's `.flat` + # intermediates (shipping those gives "resource files that are not + # referenced from the resource table"). + resource_tree = workdir / "bundle-res" + resource_tree.mkdir(parents=True, exist_ok=True) + with zipfile.ZipFile(workdir / "base-proto.apk") as proto: + for name in proto.namelist(): + if not name.startswith("res/") or name.endswith("/"): + continue + target = resource_tree / name + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(proto.read(name)) + self._bundle = build_bundle( + output, + manifest=binary_manifest, + dex=workdir / "dex" / "classes.dex", + assets=asset_tree, + libraries=workdir / "bundle-lib", + resources=resource_tree, + resource_table=resource_table, + ) + + self._stage("bundle", stage) + + toolchain = find_toolchain() + java = toolchain.java_home / "bin" / "java" + candidates: list[Path] = [] + override = os.environ.get("PYMOBILE_BUNDLETOOL") + if override: + candidates.append(Path(override).expanduser()) + candidates.extend( + [ + self.config.root / "tools" / "bundletool.jar", + Path.home() / ".andro" / "bundletool.jar", + Path.home() / ".pymobile" / "bundletool.jar", + ] + ) + jar = bundletool_path(candidates) + if jar is None or not java.is_file(): + missing = "bundletool" if jar is None else "a JDK" + self.warnings.append( + f"wrote {output.name} but did not verify it: no {missing} on this " + "machine. Download bundletool-all.jar from " + "github.com/google/bundletool/releases into ~/.andro/bundletool.jar " + f"(or set PYMOBILE_BUNDLETOOL), then run `java -jar bundletool.jar " + f"validate --bundle {output.name}` before uploading." + ) + if isinstance(getattr(self, "_bundle", None), object) and self._bundle is not None: + self._bundle = self._bundle.__class__( + path=self._bundle.path, size=self._bundle.size, entries=self._bundle.entries + ) + return + + universal = output.with_name(f"{output.stem}-universal.apks") + self._stage( + "bundle-verify", + lambda: validate_bundle(output, java=java, bundletool=jar, universal=universal), + ) + self.warnings.append( + f"app bundle verified by bundletool; the universal APK it produced is " + f"{universal.name} — install that to check the bundle before uploading" + ) + def signer_identity(self) -> str: """A stable description of the key this build will be signed with. @@ -1013,7 +1263,9 @@ def build_mode(self) -> str: Java source builds are the default so framework fixes reach the APK; ``PYMOBILE_BUILD_JAVA=0`` explicitly selects the prebuilt dex unless a project overlay is present. ``PYMOBILE_BUILD_JNI=1`` opts into building - the bridge from source. These artifact choices belong in the cache key. + the bridge from source. These artifact choices belong in the cache key, + and so does ``--debug``: a debuggable APK and a release-shaped one are + different artifacts even though both are "native". """ mode = "native" if self.native else "structural" if os.environ.get("PYMOBILE_BUILD_JNI") == "1": @@ -1024,6 +1276,12 @@ def build_mode(self) -> str: mode += "+java" elif self.native: mode += "+prebuilt-java" + if self.bundle and self.native: + mode += "+bundle" + if self.debug: + # Last, so the flag stays visible and greppable in the cache key: + # "native+java+debug", never "native+debug+java". + mode += "+debug" return mode def _fingerprint( diff --git a/pymobile/compiler/precheck.py b/pymobile/compiler/precheck.py index d8f662a..36f0a36 100644 --- a/pymobile/compiler/precheck.py +++ b/pymobile/compiler/precheck.py @@ -161,6 +161,7 @@ def check_project(root: str | Path, *, run_app: bool = True) -> list[Finding]: name_findings = _import_findings(entry, tree) findings.extend(name_findings) + findings.extend(_handler_findings(entry, source, tree)) findings.extend(_module_findings(root, entry)) if findings or config is None or not run_app: return findings @@ -271,6 +272,84 @@ def _import_findings(entry: Path, tree: ast.AST) -> list[Finding]: return findings +#: Keyword arguments whose value is meant to be a handler, not a call. +HANDLER_KEYWORDS = frozenset( + { + "on_press", + "on_click", + "on_change", + "on_toggle", + "on_select", + "on_submit", + "on_search", + "on_long_press", + "on_refresh", + "on_action", + "on_tap", + "on_end", + "on_error", + "on_tick", + "on_dismiss", + "on_open", + "on_close", + "on_retry", + } +) + +#: Names that return a handler instead of calling one; their parentheses are fine. +HANDLER_FACTORIES = frozenset( + {"functools.partial", "partial", "callback", "handler", "make_handler", "lambda"} +) + + +def _handler_findings(entry: Path, source: str, tree: ast.AST) -> list[Finding]: + """``on_press=self.tap()``: a handler written with parentheses. + + The call runs once while the tree is built and passes its result, so the + button silently does nothing when tapped — no exception, no placeholder, + nothing to search for. The AST sees the shape, so `pymobile check` names the + line and the fix before the app is ever started. + + Only a bare call counts: ``lambda: self.tap()``, ``partial(f, 1)`` and a + function returning a handler are correct and are left alone. + """ + findings: list[Finding] = [] + for node in ast.walk(tree): + if not isinstance(node, ast.Call): + continue + for keyword in node.keywords: + if keyword.arg not in HANDLER_KEYWORDS: + continue + value = keyword.value + if not isinstance(value, ast.Call): + continue + called = value.func + if isinstance(called, ast.Attribute): + name = called.attr + elif isinstance(called, ast.Name): + name = called.id + else: # pragma: no cover - a subscript call is not a handler + continue + if name in HANDLER_FACTORIES or name.lstrip("_").startswith("lambda"): + continue + text = ast.get_source_segment(source, value) or f"{name}(…)" + keep = text[:-2] if text.endswith("()") else text + hint = ( + f"drop the parentheses: {keyword.arg}={keep} — the call runs once" + " while the screen is built, so nothing is left to tap." + ) + findings.append( + Finding( + entry, + f"{keyword.arg} is given the result of {text}, not a handler", + value.lineno, + value.col_offset + 1, + hint, + ) + ) + return findings + + def _startup_findings(config: ProjectConfig, entry: Path) -> list[Finding]: """Start the app on the stub bridge; report where it fails in ``main.py``.""" from ..cli import _execute # lazy: ``cli`` imports this package @@ -282,11 +361,16 @@ def _startup_findings(config: ProjectConfig, entry: Path) -> list[Finding]: try: _execute(config, entry) except Exception as exc: # the app's own error is the finding + # ``_execute`` already names the file and line for a user error; take + # the line from it rather than from the traceback, which by then leads + # through the framework's own frames. + line = getattr(exc, "line", None) or _traceback_line(exc, entry) + message = str(exc) if isinstance(exc, PyMobileError) else f"{type(exc).__name__}: {exc}" return [ Finding( entry, - f"{type(exc).__name__}: {exc}", - _traceback_line(exc, entry), + message, + line, hint="The app failed on the desktop stub; the phone would fail too.", ) ] diff --git a/pymobile/compiler/rebuild_dex.py b/pymobile/compiler/rebuild_dex.py index b997708..ce67b69 100644 --- a/pymobile/compiler/rebuild_dex.py +++ b/pymobile/compiler/rebuild_dex.py @@ -84,6 +84,7 @@ def rebuild(output: Path | None = None) -> Path: def main() -> int: + """Rebuild or check the bundled dex; ``--check`` verifies the recorded hashes.""" parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--check", action="store_true", help="check bundled dex source provenance") parser.add_argument("--output", type=Path, help="write a separate dex and provenance manifest") diff --git a/pymobile/compiler/scaffold.py b/pymobile/compiler/scaffold.py index d625b7d..6422a8d 100644 --- a/pymobile/compiler/scaffold.py +++ b/pymobile/compiler/scaffold.py @@ -117,9 +117,7 @@ def slugify(name: str) -> str: transliterated = name.lower().translate(_CYRILLIC) # Then drop the diacritics from whatever Latin is left (é → e). ascii_only = ( - unicodedata.normalize("NFKD", transliterated) - .encode("ascii", "ignore") - .decode("ascii") + unicodedata.normalize("NFKD", transliterated).encode("ascii", "ignore").decode("ascii") ) slug = re.sub(r"[^a-z0-9]+", "", ascii_only) if not slug: diff --git a/pymobile/compiler/sdk_installer.py b/pymobile/compiler/sdk_installer.py index 27444ef..d504027 100644 --- a/pymobile/compiler/sdk_installer.py +++ b/pymobile/compiler/sdk_installer.py @@ -32,7 +32,7 @@ def _safe_extract_zip(zf: zipfile.ZipFile, destination: Path) -> None: """Extract a ZIP verifying no member escapes the destination directory. - П-20: mirrors tarfile's ``filter="data"`` behaviour for zip, so bandit's + Mirrors tarfile's ``filter="data"`` behaviour for zip, so bandit's B202 warning is not a false positive. SHA-256 is verified *before* extraction already; this is a belt-and-braces defence against a path traversal entry (``../../etc/passwd`` or an absolute Windows path). @@ -64,7 +64,7 @@ def chmod_launchers(tools_bin: Path) -> None: extraction leaves ``sdkmanager``/``avdmanager`` with mode 644. Only ``sdkmanager`` used to be repaired, and only on the first download — an ``avdmanager`` without the executable bit made - ``pymobile emulator create`` die with "Permission denied" (PM-09), and a + ``pymobile emulator create`` die with "Permission denied", and a cache unpacked by an older release stayed broken for ever. This runs on every install: fresh extraction or existing cache, same repair. """ @@ -77,9 +77,20 @@ def chmod_launchers(tools_bin: Path) -> None: with suppress(OSError): entry.chmod(entry.stat().st_mode | 0o755) + +#: Android platform the toolchain installs; the build compiles against it. +#: ``target_sdk`` above this asks Android for behaviour of a newer release while +#: the APK never gets compiled against it — see ``build``'s warning. +#: +#: This is what Google Play requires as of 31 August 2026: new apps and updates +#: must target API 36. Compiling against 36 is the whole point — a manifest that +#: claims 36 while the classes and resources were built against 35 is the state +#: that got rejected and that silently skipped API 36 behaviour switches. +SDK_PLATFORM = 36 + #: Everything needed to build an APK using the prebuilt JNI bridge (~450 MB). MINIMAL_PACKAGES = ( - "platforms;android-35", + f"platforms;android-{SDK_PLATFORM}", "build-tools;35.0.0", "platform-tools", # adb for installing/debugging APKs on a phone or emulator ) diff --git a/pymobile/compiler/size_report.py b/pymobile/compiler/size_report.py index 4d396d7..5557a78 100644 --- a/pymobile/compiler/size_report.py +++ b/pymobile/compiler/size_report.py @@ -20,6 +20,7 @@ class SizeReport: dependencies: dict[str, int] def to_dict(self) -> dict[str, object]: + """The report as plain data, ready to serialise.""" return { "apk": str(self.apk), "total": self.total, diff --git a/pymobile/compiler/toolchain.py b/pymobile/compiler/toolchain.py index 0360b2b..4bef6d5 100644 --- a/pymobile/compiler/toolchain.py +++ b/pymobile/compiler/toolchain.py @@ -271,13 +271,23 @@ def find_toolchain( sdk: str | Path | None = None, *, build_tools_version: str | None = None, - platform_api: int = 34, + platform_api: int | None = None, ) -> Toolchain: """Discover the Android toolchain. The newest installed build-tools and the newest platform at or above - ``platform_api`` are chosen unless pinned explicitly. + ``platform_api`` are chosen unless pinned explicitly. The default is + :data:`~pymobile.compiler.sdk_installer.SDK_PLATFORM` — the API level the + build actually compiles against, *not* ``target_sdk``: a project that + declares target 36 while the classes were compiled against android-35 has + the manifest of one release and the behaviour of another. + + Imported inside the function because ``sdk_installer`` imports this module. """ + if platform_api is None: + from .sdk_installer import SDK_PLATFORM + + platform_api = SDK_PLATFORM root = _sdk_root(sdk) if root is None or not root.exists(): raise ToolchainError( diff --git a/pymobile/compiler/widgets.py b/pymobile/compiler/widgets.py index 195f18d..fa4ba98 100644 --- a/pymobile/compiler/widgets.py +++ b/pymobile/compiler/widgets.py @@ -170,9 +170,7 @@ def scan_custom_widgets(files: Iterable[Path]) -> CustomWidgets: widgets.add(name) changed = True types = { - type_name - for name, _, type_name in definitions - if name in widgets and type_name is not None + type_name for name, _, type_name in definitions if name in widgets and type_name is not None } - widget_types() return CustomWidgets(frozenset(types), frozenset(declared), frozenset(preview_only)) @@ -232,22 +230,74 @@ def dex_has_class(dex: bytes, class_name: str) -> bool: #: Attributes every ``Widget`` already has; a prop of that name would clobber them. _WIDGET_RESERVED = frozenset( { - "id", "style", "visible", "enabled", "parent", "children", "screen", - "type_name", "props", "on_press", + "id", + "style", + "visible", + "enabled", + "parent", + "children", + "screen", + "type_name", + "props", + "on_press", } ) #: Locals of ``build()`` / ``updateNode()`` a generated variable must not shadow. -_RESERVED_LOCALS = frozenset( - {"id", "props", "view", "node", "type", "style", "context", "enabled"} -) +_RESERVED_LOCALS = frozenset({"id", "props", "view", "node", "type", "style", "context", "enabled"}) _JAVA_KEYWORDS = frozenset( ( - "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", - "const", "continue", "default", "do", "double", "else", "enum", "extends", "final", - "finally", "float", "for", "goto", "if", "implements", "import", "instanceof", "int", - "interface", "long", "native", "new", "package", "private", "protected", "public", - "return", "short", "static", "strictfp", "super", "switch", "synchronized", "this", - "throw", "throws", "transient", "try", "void", "volatile", "while", "true", "false", + "abstract", + "assert", + "boolean", + "break", + "byte", + "case", + "catch", + "char", + "class", + "const", + "continue", + "default", + "do", + "double", + "else", + "enum", + "extends", + "final", + "finally", + "float", + "for", + "goto", + "if", + "implements", + "import", + "instanceof", + "int", + "interface", + "long", + "native", + "new", + "package", + "private", + "protected", + "public", + "return", + "short", + "static", + "strictfp", + "super", + "switch", + "synchronized", + "this", + "throw", + "throws", + "transient", + "try", + "void", + "volatile", + "while", + "true", + "false", "null", ) ) @@ -468,8 +518,7 @@ def scaffold_widget_sources(type_name: str, props: Sequence[WidgetProp] = ()) -> "list": "list[object]", } parameters = ",\n ".join( - f"{prop.name}: {annotations[prop.kind]} = {prop.default}" - for prop in fields + f"{prop.name}: {annotations[prop.kind]} = {prop.default}" for prop in fields ) if parameters: signature = ( @@ -485,12 +534,14 @@ def scaffold_widget_sources(type_name: str, props: Sequence[WidgetProp] = ()) -> " **kwargs: Any," ) assignments = "\n".join( - f" self.{prop.name} = list({prop.name})" if prop.kind == "list" + f" self.{prop.name} = list({prop.name})" + if prop.kind == "list" else f" self.{prop.name} = {prop.name}" for prop in fields ) entries = "\n".join( - f' "{prop.name}": list(self.{prop.name}),' if prop.kind == "list" + f' "{prop.name}": list(self.{prop.name}),' + if prop.kind == "list" else f' "{prop.name}": self.{prop.name},' for prop in fields ) @@ -507,7 +558,7 @@ def scaffold_widget_sources(type_name: str, props: Sequence[WidgetProp] = ()) -> " super().__init__(**kwargs)\n" f"{assignments + chr(10) if assignments else ''}" " if on_press is not None and not callable(on_press):\n" - " raise TypeError(\"on_press must be callable or None\")\n" + ' raise TypeError("on_press must be callable or None")\n' " self.on_press = on_press\n\n" " def props(self) -> dict[str, Any]:\n" " return {\n" @@ -525,18 +576,16 @@ def scaffold_widget_sources(type_name: str, props: Sequence[WidgetProp] = ()) -> for prop in fields: if prop.kind == "str": shown.append( - f' if (!{prop.variable}.isEmpty()) ' + f" if (!{prop.variable}.isEmpty()) " f'label.append("\\n{prop.name}=").append({prop.variable});' ) elif prop.kind == "list": shown.append( - f' if ({prop.variable} != null) ' + f" if ({prop.variable} != null) " f'label.append("\\n{prop.name}=").append({prop.variable});' ) else: - shown.append( - f' label.append("\\n{prop.name}=").append({prop.variable});' - ) + shown.append(f' label.append("\\n{prop.name}=").append({prop.variable});') java = ( "package org.pymobile.app.widgets;\n\n" "import android.content.Context;\n" @@ -616,9 +665,7 @@ def python_only_widget_source(type_name: str, props: Sequence[WidgetProp] = ()) f" {prop.name}: {annotations[prop.kind]} = {prop.default},\n" for prop in props ) helper_args = "".join(f", {name}" for name in names) - helper_params = "".join( - f",\n {prop.name}: {annotations[prop.kind]}" for prop in props - ) + helper_params = "".join(f",\n {prop.name}: {annotations[prop.kind]}" for prop in props) needs_sequence = any(prop.kind == "list" for prop in props) shapes = "".join( f' Shape("text", x=12, y={24 + 24 * index}, ' diff --git a/pymobile/core/api/audio.py b/pymobile/core/api/audio.py index 6ddc0b0..9f088c9 100644 --- a/pymobile/core/api/audio.py +++ b/pymobile/core/api/audio.py @@ -170,7 +170,7 @@ def seek(self, position_ms: int) -> None: raise TypeError("position_ms must be a number") target = max(0, int(position_ms)) if not self.duration and self._handle is not None: - # The cached zero may just mean "not prepared yet" (PM-12). + # The cached zero may just mean "not prepared yet". with contextlib.suppress(Exception): self.duration = max(0, int(self._handle.duration())) if self.duration: @@ -216,6 +216,7 @@ def volume(self) -> float: @volume.setter def volume(self, value: float) -> None: + """Playback volume from 0.0 to 1.0, clamped and forwarded to the bridge.""" if isinstance(value, bool) or not isinstance(value, (int, float)): raise TypeError("volume must be a number from 0.0 to 1.0") if not 0.0 <= float(value) <= 1.0: @@ -306,7 +307,7 @@ def _tick(self) -> None: # The platform prepares asynchronously: duration() answers 0 # until the file is ready. Refresh instead of caching that # zero for the whole playback and silently losing the end - # detection that depends on it (PM-12). + # detection that depends on it. with contextlib.suppress(Exception): self.duration = max(0, int(self._handle.duration())) except Exception: # pragma: no cover - defensive @@ -338,7 +339,8 @@ def _tick(self) -> None: elif now - self._not_playing_since >= _PREPARE_TIMEOUT_S: _log.warning( "audio %s did not start playing within %.0f s; stopping the watcher", - self._source, _PREPARE_TIMEOUT_S, + self._source, + _PREPARE_TIMEOUT_S, ) self._stop_polling() return diff --git a/pymobile/core/api/notifications.py b/pymobile/core/api/notifications.py index 313c4e5..424ac87 100644 --- a/pymobile/core/api/notifications.py +++ b/pymobile/core/api/notifications.py @@ -68,17 +68,15 @@ def notify( if not isinstance(title, str): raise TypeError( f"notification title must be a string, got {type(title).__name__!r}; " - f"write notify(\"Title\", \"Body\") not notify({title!r}, ...)" + f'write notify("Title", "Body") not notify({title!r}, ...)' ) if not title: raise ValueError( "notification title must not be empty; " - "pass e.g. notify(\"Update\", \"Download complete\")" + 'pass e.g. notify("Update", "Download complete")' ) if not isinstance(body, str): - raise TypeError( - f"notification body must be a string, got {type(body).__name__!r}" - ) + raise TypeError(f"notification body must be a string, got {type(body).__name__!r}") if notification_id is not None and not isinstance(notification_id, int): raise TypeError( f"notification_id must be an int, got {type(notification_id).__name__!r}; " diff --git a/pymobile/core/api/storage.py b/pymobile/core/api/storage.py index 5e3c6d5..5ff9784 100644 --- a/pymobile/core/api/storage.py +++ b/pymobile/core/api/storage.py @@ -29,6 +29,7 @@ from __future__ import annotations +import atexit import json import os import tempfile @@ -66,19 +67,35 @@ class _StoreState: Two ``Storage`` objects on the same file used to keep independent snapshots: whichever wrote last saved *its* copy of the whole file and - silently reverted the other's changes (PM-01). One shared data dict under + silently reverted the other's changes. One shared data dict under one re-entrant lock removes that class of loss; namespaces are views on top, not separate owners. """ - __slots__ = ("data", "lock", "status", "error", "disk_stamp", "tx_depth", - "tx_dirty", "__weakref__") + __slots__ = ( + "data", + "lock", + "status", + "error", + "disk_stamp", + "tx_depth", + "tx_dirty", + "path", + "write_count", + "__weakref__", + ) - def __init__(self) -> None: + def __init__(self, path: Path) -> None: + #: Where this state lives on disk: a deferred write has to know. + self.path = path self.data: dict[str, Any] = {} self.lock = threading.RLock() self.status = _UNLOADED self.error: BaseException | None = None + #: How many times this file has been written. A counter, not a timer: + #: "one file write per burst" is what the batching promise means, and a + #: count means the same thing on a laptop and on a shared CI runner. + self.write_count = 0 #: (mtime_ns, size) of the file as we last read or wrote it — used to #: notice another process writing the same store. self.disk_stamp: tuple[int, int] | None = None @@ -91,7 +108,30 @@ def __init__(self) -> None: #: file is gone the state goes with it, and the next ``Storage`` reloads from #: disk — which is the source of truth anyway. _BACKENDS: weakref.WeakValueDictionary[Path, _StoreState] = weakref.WeakValueDictionary() +#: Stores that failed permanently, kept alive for the process. +#: +#: The registry above is weak, so a failed state was garbage-collected as soon +#: as the ``Storage`` that raised went out of scope — and the next open of the +#: same file quietly tried again instead of refusing. That made the documented +#: "a failure is sticky" true only on CPython builds where the object happened +#: to survive (3.12/3.13), and false on 3.10, where CI caught it. +_FAILED_STATES: dict[Path, _StoreState] = {} +_FAILED_LIMIT = 128 _BACKENDS_LOCK = threading.Lock() +#: Deferred stores that still have to be written when the interpreter exits. +_EXITING: list[weakref.ReferenceType[_StoreState]] = [] + + +def _flush_all_on_exit() -> None: + with _BACKENDS_LOCK: + pending, _EXITING[:] = list(_EXITING), [] + for reference in pending: + state = reference() + if state is not None: + _flush_on_exit(state) + + +atexit.register(_flush_all_on_exit) def _canonical(path: Path) -> Path: @@ -105,13 +145,47 @@ def _canonical(path: Path) -> Path: def _state_for(path: Path) -> _StoreState: key = _canonical(path) with _BACKENDS_LOCK: - state = _BACKENDS.get(key) + state = _FAILED_STATES.get(key) or _BACKENDS.get(key) if state is None: - state = _StoreState() + state = _StoreState(key) _BACKENDS[key] = state return state +def _remember_failure(state: _StoreState) -> None: + """Pin a failed store so the next open of the file is refused too.""" + with _BACKENDS_LOCK: + _FAILED_STATES[state.path] = state + while len(_FAILED_STATES) > _FAILED_LIMIT: # pragma: no cover - pathological + _FAILED_STATES.pop(next(iter(_FAILED_STATES))) + + +def _flush_on_exit(state: _StoreState) -> None: + """Last chance for a deferred store: write what is still pending. + + A short-lived script that sets three keys and exits has no ``save()`` call + and no ``with`` block; without this its writes would sit in a timer that + the interpreter kills at shutdown. Failures are logged, never raised from + an interpreter hook. + """ + try: + with state.lock: + if not state.tx_dirty or state.status != _READY: + return + state.tx_dirty = False + payload = json.dumps(state.data, ensure_ascii=False, indent=2) + fd, temp_name = tempfile.mkstemp( + dir=str(state.path.parent), suffix=".tmp", prefix=state.path.name + ) + with os.fdopen(fd, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) + os.replace(temp_name, state.path) + except Exception: # pragma: no cover - shutdown path, nothing else to do + pass + + DEFAULT_STORE_FILENAME = "pymobile_store.json" @@ -183,6 +257,12 @@ class Storage: # writes through one are visible to the other, and clearing the cache # cannot roll back the auth namespace + A store created with ``deferred=True`` batches writes: ``set`` marks the + state dirty and one save follows ``defer_seconds`` later, so a burst of + writes costs one file write instead of one per call. ``save()``, + ``transaction()`` and ``flush()`` write immediately; the pending write is + also flushed when the last reference to the store goes away. + Individual operations are atomic. A read-modify-write **sequence** written by hand is not — use :meth:`update`, :meth:`increment` or the :meth:`transaction` context manager when several steps must be one unit. @@ -196,7 +276,10 @@ class Storage: __slots__ = ( "_path", "_state", + "_timer", "namespace", + "_deferred", + "defer_seconds", "_schema_version", "_migrations", ) @@ -206,6 +289,8 @@ def __init__( path: str | Path | None = None, *, namespace: str | None = None, + deferred: bool = False, + defer_seconds: float = 0.05, schema_version: int = 0, migrations: Mapping[int, Callable[[dict[str, Any]], dict[str, Any]]] | None = None, ) -> None: @@ -228,14 +313,32 @@ def __init__( ) for version in self._migrations: if isinstance(version, bool) or not isinstance(version, int) or version < 1: - raise ValueError("migration keys are the target version, an int >= 1") + raise ValueError( + "migration keys are the stored version the migration upgrades, " + "an int >= 1 (ModelStore uses the same convention)" + ) if version > schema_version: raise ValueError( - f"migration {version} reaches past schema_version {schema_version}" + f"migration {version} reaches past schema_version {schema_version} " + "(ModelStore keys its migrations the same way, by the version " + "they upgrade to)" ) # Shared per file: the data, the lock, the load lifecycle and the # transaction depth all live on the backend, not on this object. self._state = _state_for(self._path) + # ``deferred=True`` batches several writes into one save. Without it a + # store with 5000 keys rewrote ~90 KB of JSON on every ``set``: 1 ms + # per write, 12.9 s for 4000 of them. + self._deferred = bool(deferred) + self._timer: threading.Timer | None = None + if self._deferred: + # A short script has no save() and no `with` block; flush at exit. + _EXITING.append(weakref.ref(self._state)) + if not isinstance(defer_seconds, (int, float)) or isinstance(defer_seconds, bool): + raise TypeError("defer_seconds must be a number") + if defer_seconds <= 0: + raise ValueError("defer_seconds must be positive") + self.defer_seconds = float(defer_seconds) # Load now: a store that cannot be opened (newer schema, unreadable # file, failing migration) must fail where it is created, not at some # later first access deep inside the app. @@ -248,6 +351,11 @@ def path(self) -> Path: """Filesystem location of the store.""" return self._path + @property + def write_count(self) -> int: + """How many times the backing file has been written this process.""" + return self._state.write_count + def _stamp(self) -> tuple[int, int] | None: try: st = self._path.stat() @@ -290,6 +398,7 @@ def _load(self) -> None: else: state.status = _FAILED state.error = exc + _remember_failure(state) raise state.status = _READY @@ -302,12 +411,12 @@ def _load_locked(self) -> None: except FileNotFoundError: # A brand-new store: initialise it *now*, schema stamp included, # so the first migration runs before any user write instead of - # ambush-ing the next launch (PM-03). + # ambushing the next launch. self._migrate() return except UnicodeDecodeError as exc: # Not valid UTF-8 is corruption, same as unparsable JSON: keep the - # original bytes aside instead of failing every launch (PM-08). + # original bytes aside instead of failing every launch. self._quarantine(exc) text = None except OSError as exc: @@ -333,9 +442,7 @@ def _load_locked(self) -> None: def _quarantine(self, reason: Exception) -> None: """Move an unparsable store aside instead of letting a write replace it.""" - backup = self._path.with_name( - f"{self._path.name}.corrupt-{time.strftime('%Y%m%d-%H%M%S')}" - ) + backup = self._path.with_name(f"{self._path.name}.corrupt-{time.strftime('%Y%m%d-%H%M%S')}") try: os.replace(self._path, backup) except OSError as exc: @@ -347,7 +454,9 @@ def _quarantine(self, reason: Exception) -> None: raise error from exc _log.warning( "store %s could not be parsed (%s); it was moved to %s and the store starts empty", - self._path, reason, backup, + self._path, + reason, + backup, ) def save(self) -> None: @@ -361,6 +470,13 @@ def save(self) -> None: """ with self._state.lock: self._load() + self._cancel_timer() + if self._state.tx_dirty: + # A deferred write is already "made": save() must put it on + # disk rather than queue a second copy behind it. + self._state.tx_dirty = False + self._write_locked() + return self._persist() def _persist(self) -> None: @@ -368,9 +484,49 @@ def _persist(self) -> None: state = self._state if state.tx_depth: state.tx_dirty = True + elif self._deferred: + self._schedule_flush_locked() else: self._write_locked() + def _schedule_flush_locked(self) -> None: + """Arm (or re-arm) the debounce timer; caller holds the lock.""" + state = self._state + state.tx_dirty = True + if self._timer is not None: + self._timer.cancel() + timer = threading.Timer(self.defer_seconds, self._flush_timer) + timer.daemon = True + self._timer = timer + timer.start() + + def _flush_timer(self) -> None: + """Write whatever the deferred store is holding, if anything.""" + with self._state.lock: + if not self._state.tx_dirty: + return + self._state.tx_dirty = False + self._write_locked() + + def flush(self) -> None: + """Write pending changes now, even on a deferred store. + + Called by :meth:`save`, by :meth:`transaction`, and by ``App.stop`` + (through ``save``), so an app that goes to the background does not + lose the last few hundred milliseconds of writes. + """ + with self._state.lock: + self._load() + self._cancel_timer() + if self._state.tx_dirty: + self._state.tx_dirty = False + self._write_locked() + + def _cancel_timer(self) -> None: + if self._timer is not None: + self._timer.cancel() + self._timer = None + def _save_locked(self) -> None: """Backward-compatible name used by subclasses/tests; caller holds the lock.""" self._persist() @@ -378,6 +534,7 @@ def _save_locked(self) -> None: def _write_locked(self) -> None: """Atomically and durably persist the in-memory store; caller holds the lock.""" state = self._state + state.write_count += 1 # Serialise first: a bad value must fail before any file is touched. try: payload = json.dumps(state.data, ensure_ascii=False, indent=2) @@ -391,7 +548,8 @@ def _write_locked(self) -> None: if state.disk_stamp is not None and stamp is not None and stamp != state.disk_stamp: _log.warning( "store %s was modified by another process since it was loaded; " - "those changes are being overwritten", self._path, + "those changes are being overwritten", + self._path, ) try: self._path.parent.mkdir(parents=True, exist_ok=True) @@ -445,9 +603,7 @@ def _scoped(self, data: Mapping[str, Any]) -> dict[str, Any]: prefix = self._scope_prefix() if not prefix: return dict(data) - return { - key[len(prefix):]: value for key, value in data.items() if key.startswith(prefix) - } + return {key[len(prefix) :]: value for key, value in data.items() if key.startswith(prefix)} def _migrate(self) -> None: """Bring the loaded data up to :attr:`schema_version`; caller holds the lock. @@ -485,7 +641,8 @@ def _migrate(self) -> None: raise PyMobileError( f"no migration to schema {version} in {self._path}", hint=( - "Migrations are keyed by the version they reach: " + "Migrations are keyed by the version being upgraded " + "to (the same convention as ModelStore): " "Storage(migrations={1: step_one, 2: step_two}, " f"schema_version={self._schema_version})" ), @@ -525,7 +682,7 @@ def _visible_keys(self) -> list[str]: prefix = self._scope_prefix() hidden = self._meta_key("__schema_version__") return [ - key[len(prefix):] if prefix else key + key[len(prefix) :] if prefix else key for key in self._state.data if (not prefix or key.startswith(prefix)) and key != hidden ] @@ -676,6 +833,7 @@ def transaction(self) -> Iterator[Storage]: state.tx_depth -= 1 if state.tx_depth == 0 and state.tx_dirty: state.tx_dirty = False + self._cancel_timer() try: self._write_locked() except BaseException: @@ -750,6 +908,7 @@ def increment(self, key: str, amount: float = 1) -> float: zero", but silently turning the string ``"5"`` into ``1`` lost data that came back from JSON, so numeric strings are parsed first. """ + def bump(current: Any) -> float: if isinstance(current, bool): return amount @@ -790,7 +949,7 @@ def items(self) -> list[tuple[str, Any]]: self._load() return [ ( - self._full_key(key)[len(self._scope_prefix()):], + self._full_key(key)[len(self._scope_prefix()) :], _copy(self._state.data[self._full_key(key)]), ) for key in self._visible_keys() diff --git a/pymobile/core/api/typed_storage.py b/pymobile/core/api/typed_storage.py index 99c64df..06f0299 100644 --- a/pymobile/core/api/typed_storage.py +++ b/pymobile/core/api/typed_storage.py @@ -13,14 +13,17 @@ from __future__ import annotations import json -from collections.abc import Callable, Mapping +from collections.abc import Callable, Iterable, Mapping from dataclasses import asdict, is_dataclass from typing import Any, Generic, TypeVar, cast from ...errors import ModelStoreError +from ...log import get_logger from .storage import Storage -__all__ = ["ModelStore", "ModelMigration"] +__all__ = ["ModelStore", "ModelMigration", "Q", "ENVELOPE_WARN_BYTES"] + +_log = get_logger("api.typed_storage") T = TypeVar("T") ModelId = str | int @@ -30,6 +33,151 @@ ModelMigration = Callable[[list[_Record]], list[Mapping[str, Any]]] +class Q: + """A query expression for :meth:`ModelStore.find`. + + Deliberately tiny: ``Q`` compares one field, ``&`` and ``|`` combine + queries, ``~`` negates one. A dict passed to ``find`` means the same as an + ``&`` of ``Q(field, "==", value)`` for every entry, which is what a caller + writing ``store.find(lambda m: …)`` actually wanted most of the time. + + >>> Q("done", "==", False) & Q("priority", ">=", 2) + """ + + __slots__ = ("_text", "_predicate") + _predicate: Callable[[Mapping[str, Any]], bool] + _text: str + + def __init__(self, field: str, op: str, value: Any = None) -> None: + if not isinstance(field, str) or not field.strip(): + raise ValueError("Q needs a field name") + if op not in _OPERATORS: + raise ValueError(f"unknown operator {op!r}; use one of {', '.join(sorted(_OPERATORS))}") + compare = _OPERATORS[op] + self._text = f"{field} {op} {value!r}" + + def predicate(record: Mapping[str, Any]) -> bool: + if field not in record: + return False + try: + return bool(compare(record[field], value)) + except TypeError: + # Comparing 3 with "three" is a data question, not a crash: + # the record simply does not match. + return False + + self._predicate = predicate + + def __and__(self, other: Q) -> Q: + return _Combined( + lambda record: self.matches(record) and other.matches(record), f"({self} and {other})" + ) + + def __or__(self, other: Q) -> Q: + return _Combined( + lambda record: self.matches(record) or other.matches(record), f"({self} or {other})" + ) + + def __invert__(self) -> Q: + return _Combined(lambda record: not self.matches(record), f"not ({self})") + + def matches(self, record: Mapping[str, Any]) -> bool: + """Whether ``record`` satisfies this query.""" + return self._predicate(record) + + def __repr__(self) -> str: + return f"Q({self._text})" + + +#: A warning threshold for one model store's envelope; beyond this, every write +#: serialises the whole list and the store should be split or moved to sqlite3. +ENVELOPE_WARN_BYTES = 1_000_000 + + +def _check_envelope_overflow(key: str, by_id: Mapping[Any, Mapping[str, Any]]) -> None: + """Warn once per store when the record list outgrows a single JSON value.""" + if len(by_id) % 500: + return + try: + size = len(json.dumps(list(by_id.values()))) + except (TypeError, ValueError): # pragma: no cover - records are JSON by contract + return + if size > ENVELOPE_WARN_BYTES: + _log.warning( + "model store %r holds %d records (~%.1f MB) in one JSON array: every " + "write rewrites all of them; consider sqlite3 or splitting the store", + key, + len(by_id), + size / 1_000_000, + ) + + +def _matches( + query: object, + record: Mapping[str, Any], + decode: Callable[[Mapping[str, Any]], Any] | None = None, +) -> bool: + """Apply a ``find`` query to one raw record.""" + if query is None: + return True + if isinstance(query, Q): + return query.matches(record) + if isinstance(query, Mapping): + return all( + _OPERATORS["=="](record.get(field, _MISSING), value) for field, value in query.items() + ) + if callable(query): + # A predicate on the *model* cannot be applied to a raw record: decode + # the record to ask the question, which keeps dict/Q filters cheap and + # lets a caller write the obvious lambda when it is clearer. + return bool(query(decode(record) if decode is not None else record)) + raise TypeError("query must be a Q, a mapping of fields or a callable predicate") + + +def _sort_key(record: Mapping[str, Any], fields: list[str]) -> tuple[Any, ...]: + """A total order across records, tolerating a missing or mixed-type field.""" + parts: list[tuple[int, Any]] = [] + for field in fields: + value = record.get(field, _MISSING) + if value is _MISSING: + parts.append((1, "")) + elif isinstance(value, (int, float)) and not isinstance(value, bool): + parts.append((0, value)) + else: + parts.append((0, str(value))) + return tuple(parts) + + +class _Combined(Q): + """The result of ``&``, ``|`` or ``~``; kept separate to keep the slots tidy.""" + + __slots__ = () + + def __init__(self, predicate: Callable[[Mapping[str, Any]], bool], text: str) -> None: + self._predicate = predicate + self._text = text + + +_OPERATORS: dict[str, Callable[[Any, Any], bool]] = { + "==": lambda a, b: a == b, + "!=": lambda a, b: a != b, + "<": lambda a, b: a < b, + "<=": lambda a, b: a <= b, + ">": lambda a, b: a > b, + ">=": lambda a, b: a >= b, + "in": lambda a, b: a in b, + "not in": lambda a, b: a not in b, + "contains": lambda a, b: b in a, + "startswith": lambda a, b: isinstance(a, str) and a.startswith(b), + "endswith": lambda a, b: isinstance(a, str) and a.endswith(b), +} + +#: Sentinel for "this field is absent" so a missing field never equals None. +_MISSING: Any = object() + +Query = Q | Mapping[str, Any] | Callable[[T], bool] + + class ModelStore(Generic[T]): """A typed CRUD adapter over one key in :class:`Storage`. @@ -42,8 +190,10 @@ class ModelStore(Generic[T]): JSON cannot reconstruct by calling its constructor, provide both ``to_record=`` and ``from_record=``. - ``migrations`` maps the *source* version to a function that upgrades the - complete list of records by one version. For example, ``{1: migrate_v1}`` + ``migrations`` maps the *source* version to a function, like + ``Storage``'s ``{version: fn}`` is keyed by the version the store is + already at — both mean "this is the function that runs when the stored data + is at that version". ``{1: migrate_v1}`` upgrades v1 records to v2. handles the transition from schema 1 to schema 2. Migrations run in order and are written back atomically on the next read or write. A missing step or a store created by a newer app raises :class:`ModelStoreError`; data is @@ -75,6 +225,8 @@ class ModelStore(Generic[T]): "_migrations", "_to_record", "_from_record", + "_by_id", + "_indexed", ) def __init__( @@ -120,8 +272,8 @@ def __init__( or source_version >= schema_version ): raise ValueError( - "migration keys must be source versions from 1 up to " - "schema_version - 1" + "migration keys are the version the store is at " + "(1 up to schema_version - 1), the same convention as Storage" ) if not callable(migration): raise TypeError(f"migration for schema {source_version} must be callable") @@ -135,6 +287,17 @@ def __init__( self._migrations = checked_migrations self._to_record = to_record self._from_record = from_record + # id -> record, built once per store. Every read used to walk and + # re-validate the whole list, so 1000 sequential puts cost five + # seconds; ``put``/``delete`` now touch one entry and the cache is + # dropped whenever the envelope on disk is replaced from outside. + self._by_id: dict[Any, _Record] = {} + self._indexed = False + + @property + def storage(self) -> Storage: + """The :class:`Storage` this store keeps its records in.""" + return self._storage @property def key(self) -> str: @@ -168,9 +331,7 @@ def _json_record(record: Mapping[str, Any], *, context: str) -> _Record: if any(not isinstance(name, str) for name in record): raise ModelStoreError(f"{context} field names must be strings") try: - converted = json.loads( - json.dumps(dict(record), ensure_ascii=False, allow_nan=False) - ) + converted = json.loads(json.dumps(dict(record), ensure_ascii=False, allow_nan=False)) except (TypeError, ValueError) as exc: raise ModelStoreError( f"{context} is not JSON serializable: {exc}", @@ -258,16 +419,82 @@ def _read_records(self) -> list[_Record]: ) return records + def _records(self) -> list[_Record]: + """Every record, through the id cache; caller holds the transaction.""" + if not self._indexed: + records = self._read_records() + self._by_id = { + self._identifier(record, context="stored record"): record for record in records + } + self._indexed = True + return records + return list(self._by_id.values()) + + def _invalidate(self) -> None: + self._indexed = False + self._by_id = {} + + def find( + self, + query: Q | Mapping[str, Any] | Callable[[T], bool] | None = None, + *, + limit: int | None = None, + offset: int = 0, + order_by: str | Iterable[str] | None = None, + reverse: bool = False, + ) -> list[T]: + """Return the models matching ``query``, decoded. + + ``query`` is a :class:`Q`, a mapping (all fields must match) or a plain + predicate on the model. ``order_by`` names one or more record fields; + ``limit``/``offset`` page the result. Filtering happens on the stored + records — before decoding — so a page of ten does not build a thousand + dataclasses. + """ + if limit is not None and (not isinstance(limit, int) or isinstance(limit, bool)): + raise TypeError("limit must be an int or None") + if limit is not None and limit < 0: + raise ValueError("limit must be >= 0") + if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0: + raise ValueError("offset must be an int >= 0") + decode = self._decode if callable(query) and not isinstance(query, Q) else None + with self._storage.transaction(): + records = self._records() + matched = [record for record in records if _matches(query, record, decode)] + if order_by is not None: + fields = [order_by] if isinstance(order_by, str) else list(order_by) + for field in fields: + if not isinstance(field, str): + raise TypeError("order_by takes field names") + matched.sort(key=lambda record: _sort_key(record, fields), reverse=reverse) + window = matched[offset:] if limit is None else matched[offset : offset + limit] + return [self._decode(record) for record in window] + + def count(self, query: Q | Mapping[str, Any] | Callable[[T], bool] | None = None) -> int: + """How many models match ``query`` (``None`` counts everything). + + Counted on records, so it costs no decoding and no list of models. + """ + decode = self._decode if callable(query) and not isinstance(query, Q) else None + with self._storage.transaction(): + return sum(1 for record in self._records() if _matches(query, record, decode)) + + def get_by(self, **fields: Any) -> T | None: + """The first model whose fields equal ``fields``, or ``None``. + + The indexed shortcut for ``store.get(store.find({"email": email})[0].id)``. + """ + if not fields: + raise ValueError("get_by needs at least one field") + found = self.find(fields, limit=1) + return found[0] if found else None + def _encode(self, model: T) -> _Record: if not isinstance(model, self._model_type): - raise TypeError( - f"expected {self._model_type.__name__}, got {type(model).__name__}" - ) + raise TypeError(f"expected {self._model_type.__name__}, got {type(model).__name__}") try: source = ( - self._to_record(model) - if self._to_record is not None - else asdict(cast(Any, model)) + self._to_record(model) if self._to_record is not None else asdict(cast(Any, model)) ) except Exception as exc: raise ModelStoreError( @@ -297,7 +524,7 @@ def _decode(self, record: Mapping[str, Any]) -> T: def all(self) -> list[T]: """Return every stored model in insertion order.""" with self._storage.transaction(): - return [self._decode(record) for record in self._read_records()] + return [self._decode(record) for record in self._records()] def list(self) -> list[T]: """Alias for :meth:`all`.""" @@ -307,11 +534,9 @@ def get(self, identifier: ModelId) -> T | None: """Return a model by id, or ``None`` when it does not exist.""" self._validate_lookup_id(identifier) with self._storage.transaction(): - for record in self._read_records(): - stored_id = self._identifier(record, context="stored record") - if type(stored_id) is type(identifier) and stored_id == identifier: - return self._decode(record) - return None + self._records() # populates the id cache + record = self._lookup(identifier) + return None if record is None else self._decode(record) def put(self, model: T) -> T: """Insert or replace a model, identified by ``id_field``. @@ -328,17 +553,17 @@ def put(self, model: T) -> T: record = self._encode(model) identifier = self._identifier(record, context=f"{self._model_type.__name__} record") with self._storage.transaction() as storage: - records = self._read_records() - for index, stored in enumerate(records): - stored_id = self._identifier(stored, context="stored record") - if type(stored_id) is type(identifier) and stored_id == identifier: - records[index] = record - break - else: - records.append(record) + self._records() + # One dict write instead of a list walk and a full re-validation: + # this is what turns 1000 puts from five seconds into milliseconds. + self._by_id[identifier] = record + _check_envelope_overflow(self._key, self._by_id) storage.set( self._key, - {"schema_version": self._schema_version, "records": records}, + { + "schema_version": self._schema_version, + "records": list(self._by_id.values()), + }, ) return model @@ -375,8 +600,7 @@ def edit(self, identifier: ModelId, /, **changes: Any) -> T: if not hasattr(model, name): known = ", ".join(sorted(vars(model))) or "none" raise ModelStoreError( - f"{self._model_type.__name__} has no field {name!r} " - f"(fields: {known})" + f"{self._model_type.__name__} has no field {name!r} (fields: {known})" ) try: setattr(model, name, value) @@ -394,31 +618,43 @@ def delete(self, identifier: ModelId) -> bool: """Delete a model by id; return ``False`` when the id was absent.""" self._validate_lookup_id(identifier) with self._storage.transaction() as storage: - records = self._read_records() - remaining = [ - record - for record in records - if not ( - type(self._identifier(record, context="stored record")) is type(identifier) - and self._identifier(record, context="stored record") == identifier - ) - ] - if len(remaining) == len(records): + self._records() + if self._lookup(identifier) is None: return False + del self._by_id[identifier] storage.set( self._key, - {"schema_version": self._schema_version, "records": remaining}, + { + "schema_version": self._schema_version, + "records": list(self._by_id.values()), + }, ) return True def clear(self) -> None: """Remove all records while keeping an empty envelope at the current schema.""" with self._storage.transaction() as storage: + self._invalidate() storage.set(self._key, {"schema_version": self._schema_version, "records": []}) def __len__(self) -> int: with self._storage.transaction(): - return len(self._read_records()) + return len(self._records()) + + def _lookup(self, identifier: ModelId) -> _Record | None: + """The raw record for ``identifier``, comparing types as before. + + ``True == 1`` in Python; a store keyed by strings must not hand back the + record whose id is ``1`` for a lookup of ``True``. + """ + record = self._by_id.get(identifier) + if record is None: + return None + if type(record.get(self._id_field)) is not type(identifier): + # ``True == 1`` and they hash alike, so the dict would happily hand + # back the row whose id is ``1`` for a lookup of ``True``. + return None + return record @staticmethod def _validate_lookup_id(identifier: ModelId) -> None: diff --git a/pymobile/core/app.py b/pymobile/core/app.py index 65924b4..1763fe4 100644 --- a/pymobile/core/app.py +++ b/pymobile/core/app.py @@ -44,6 +44,9 @@ #: Event kind the device bridge uses to wake the event loop for UI calls. WAKE_EVENT = "__wake__" +#: The platform telling the app that its window is going away (or arriving). +#: The value is ``"stop"`` or ``"resume"``; see :meth:`App.save_state`. +LIFECYCLE_EVENT = "__lifecycle__" #: Event the application emits when the data behind its screens changed. #: Subscribing to it is optional — :meth:`App.notify_data_changed` emits it and @@ -66,6 +69,7 @@ "select", "toggle", "search", + "submit", "increment", "decrement", "swipe", @@ -78,17 +82,32 @@ #: ``"3:button-1"`` — and come back the same way. The token is what lets an #: event from a screen that is no longer displayed be recognised and dropped: #: automatic ids restart per screen, so the Delete button of a dialog and the -#: Open button of the menu it replaced are both ``button-1`` (PM-14). +#: Open button of the menu it replaced are both ``button-1``. _WIRE_ID = re.compile(r"^(?P\d+):(?P.*)$") __all__ = ["App"] +#: Screen transitions the Android renderer can play. ``fade`` cross-dissolves, +#: ``fade_through`` fades out then in (Material's change of context), ``slide`` +#: moves horizontally, ``slide_up`` rises from the bottom, ``scale`` grows the +#: incoming screen. Anything unknown falls back to a fade on the device. +SCREEN_TRANSITIONS = ( + "none", + "fade", + "fade_through", + "slide", + "slide_up", + "slide_down", + "scale", +) + _log = get_logger("app") def _noop() -> None: return None + #: The application started most recently, or None. Developer tooling (the #: interactive preview, the reloader) needs a handle on the running app #: without dictating where the author keeps theirs. @@ -145,7 +164,7 @@ def _app_store_path(package: str) -> Path: def _sandboxed_storage_for_tests(package: str) -> str | None: """Return a sandbox storage path when we detect a test runner. - П-08: without this, a test that instantiates ``App(...)`` silently writes + Without this, a test that instantiates ``App(...)`` silently writes to ``~/.pymobile/.json`` and can wipe the developer's real data. When pytest or unittest is in ``sys.modules`` *and* the user did not set ``PYMOBILE_STORAGE_DIR``, we isolate the store under ``$TMPDIR/pymobile-test/`` @@ -266,12 +285,32 @@ def __init__(self, widget: Widget, title: str) -> None: self._widget = widget def build(self) -> Widget: + """The single widget this screen shows.""" return self._widget def on_unmount(self) -> None: + """Detach the widget tree when the screen goes away.""" self._detach_tree() +def _remote_image_sources(tree: dict[str, Any]) -> list[str]: + """Image sources the Android renderer cannot load (A19).""" + found: list[str] = [] + stack: list[Any] = [tree] + while stack: + node = stack.pop() + if isinstance(node, dict): + if node.get("type") == "Image": + props = node.get("props") + source = str(props.get("source", "")) if isinstance(props, dict) else "" + if source.startswith(("http://", "https://", "data:")): + found.append(source) + stack.extend(node.values()) + elif isinstance(node, list): + stack.extend(node) + return found + + class App: """Root object of a PyMobile application. @@ -302,6 +341,7 @@ def __init__( log_file: str | None = None, transition: str | None = "fade", transition_duration_ms: int = 220, + follow_system_theme: bool = False, ) -> None: if dark_theme is not None and not isinstance(dark_theme, Theme): raise TypeError("dark_theme must be a Theme") @@ -309,8 +349,8 @@ def __init__( raise ValueError("dark_theme must be named 'dark' so renderers recognize it") if isinstance(theme, Theme) and theme.is_dark and dark_theme is not None: raise ValueError("pass a dark theme as either theme or dark_theme, not both") - if transition not in (None, "none", "fade", "slide", "scale"): - raise ValueError("transition must be one of: none, fade, slide, scale") + if transition not in (None, *SCREEN_TRANSITIONS): + raise ValueError("transition must be one of: " + ", ".join(SCREEN_TRANSITIONS)) if ( isinstance(transition_duration_ms, bool) or not isinstance(transition_duration_ms, int) @@ -318,6 +358,12 @@ def __init__( ): raise ValueError("transition_duration_ms must be an int from 0 to 2000") self.name = name + #: Switch between the light palette and its dark counterpart when the + #: system does. On Android that used to be invisible: ``uiMode`` is in + #: ``configChanges``, so the activity survives the switch and nothing + #: told Python. Default off keeps the palette the app chose. + self.follow_system_theme = bool(follow_system_theme) + self._system_dark: bool | None = None self.transition = "none" if transition is None else transition self.transition_duration_ms = transition_duration_ms self.version = version or "0.1.0" @@ -333,7 +379,7 @@ def __init__( self.vibration = Vibration(self.bridge) self.permissions = PermissionManager(self.bridge) self.http = HttpClient(base_url=base_url, deliver=self._deliver) - # П-08: a script/test that builds its own App(...) without + # A script/test that builds its own App(...) without # ``storage_path`` must not clobber the real app's data on disk. # When pytest (or unittest) is running and the caller did not point at # a store explicitly, sandbox the storage under a temp directory and @@ -360,10 +406,15 @@ def __init__( #: True once stop() ran; stop() releases resources for good, so such an #: app cannot be started again (see run()). self._stopped = False + #: Widget state read from the store, waiting for the widgets to exist. + self._restore_pending: dict[str, Any] = {} + #: True between a ``__lifecycle__``/stop and the next resume: the window + #: is gone, the interpreter is not. + self._window_stopped = False #: Bumped every time a different screen is shown. Widget ids are #: qualified with it on the way out and checked on the way in, so an #: event that was queued by the previous screen cannot act on a widget - #: of the current one (PM-14). + #: of the current one. self._generation = 0 #: Metadata for the next native screen swap; consumed by one render only. self._pending_navigation: dict[str, Any] | None = None @@ -379,7 +430,8 @@ def __init__( self._warned_render_loop = False #: Widget types already reported as having no native renderer. self._warned_unknown_types: set[str] = set() - # П-10: screens popped during a UI dispatch land here so their + self._warned_remote_images: set[str] = set() + # Screens popped during a UI dispatch land here so their # ``_app`` reference can be cleared after the handler returns (see # Navigator._discard / Screen.app). self._in_ui_dispatch = 0 @@ -461,6 +513,22 @@ def info(self) -> dict[str, str]: "platform": self.platform, } + @property + def system_is_dark(self) -> bool | None: + """The system's light/dark choice, or ``None`` before Android says.""" + return self._system_dark + + def _apply_system_theme(self, dark: bool) -> None: + """Follow the system palette, if the app asked to.""" + target = "dark" if dark else "light" + if self._theme.name == target: + return + try: + self.set_theme(target) + except (KeyError, ValueError): + # No counterpart registered: the app's own palette stays. + _log.debug("no %s palette registered; keeping %s", target, self._theme.name) + def set_theme(self, theme: str | Theme) -> None: """Switch to a registered light/dark palette or install a Theme and redraw. @@ -553,10 +621,125 @@ def run(self, screen: Screen | Widget) -> None: _plugin_registry.on_app_start(self) self.events.emit("app:start", source=self.name) self.navigator.reset(screen) + # A window that is adopting an interpreter which outlived the previous + # one gets its typed-in values back before the first frame. + self.restore_state() if hasattr(self.bridge, "next_event"): self._event_loop() + # -- window lifecycle -------------------------------------------------- + def save_state(self) -> None: + """Write the state that must survive the window being destroyed. + + Called automatically when the platform reports that the Activity is + going away and the app stays in memory; call it in ``Screen.on_stop`` + for the application's own data. Two things happen: + + * every screen on the navigator stack gets ``on_stop()`` once, so a + screen can pause a timer or stash a draft; + * the widget state the framework tracks — a field's text, a switch's + position, a dropdown's choice — is written to the app store under + ``__ui_state__``, keyed by widget id. + + The write goes through :class:`~pymobile.core.api.storage.Storage`, so + it is a normal, atomic store write, and it is a no-op when ``storage`` + was never touched and nothing is tracked. + """ + tracked = self._tracked_widget_state() + if tracked: + try: + self._ui_state_store().set("state", tracked) + except Exception: # a full disk must not take the window down + _log.exception("could not save the widget state") + for screen in self.navigator.stack: + try: + screen.on_stop() + except Exception: + _log.exception("Screen.on_stop failed for %r", screen) + + def _ui_state_store(self) -> Storage: + """A namespaced view of the app store for the framework's own state. + + ``pymobile`` as the namespace keeps ``__ui_state__`` out of the app's + own keys, so iterating ``app.storage`` never shows framework bookkeeping. + """ + return Storage(self.storage.path, namespace="pymobile") + + def _tracked_widget_state(self) -> dict[str, Any]: + """Widget values worth restoring, by the screen that holds them. + + The same snapshot a rebuild uses (:meth:`Screen._snapshot_state`), so + a field keeps what the user typed across a window being destroyed for + exactly the reasons it keeps it across ``Screen.rebuild()`` — one code + path, one set of widget ``capture_state`` implementations. + """ + state: dict[str, Any] = {} + for index, screen in enumerate(self.navigator.stack): + try: + snapshot = screen._snapshot_state() + except Exception: # a screen that never built anything + continue + if snapshot: + state[str(index)] = snapshot + return state + + def restore_state(self) -> None: + """Apply what :meth:`save_state` wrote, before the first frame. + + Widgets created with an id the store knows get their value back after + the screen is built, so a relaunch after the window was destroyed + shows the half-typed form rather than an empty one. + """ + try: + stored = self._ui_state_store().get("state", None) + except Exception: + _log.exception("could not read the saved widget state") + return + if not isinstance(stored, dict): + return + self._restore_pending = dict(stored) + self._apply_saved_state() + + def _apply_saved_state(self) -> None: + pending = self._restore_pending + if not pending: + return + for index, screen in enumerate(self.navigator.stack): + snapshot = pending.get(str(index)) + if not isinstance(snapshot, dict): + continue + try: + screen._restore_state(snapshot) + except Exception: + _log.exception("could not restore the state of %r", screen) + self._restore_pending = {} + + def _lifecycle(self, phase: str) -> None: + """Handle ``__lifecycle__``: the window left, or a new one adopted us.""" + if phase == "stop": + _log.info("window stopped; saving state (Python keeps running)") + self.save_state() + self._window_stopped = True + return + if phase == "resume": + _log.info("window resumed on the live interpreter") + self._window_stopped = False + self._apply_saved_state() + for screen in self.navigator.stack: + try: + screen.on_start() + except Exception: + _log.exception("Screen.on_start failed for %r", screen) + # A visible window needs a frame: the tree may have been patched + # while nothing was drawn. + current = self.navigator.current + if current is not None: + try: + current.refresh() + except Exception: + _log.exception("could not redraw after resume") + def _event_loop(self) -> None: """Dispatch UI events until the platform asks us to stop. @@ -575,6 +758,8 @@ def _event_loop(self) -> None: try: if kind == WAKE_EVENT: self._run_ui_calls() + elif kind == LIFECYCLE_EVENT: + self._lifecycle(value) else: self.handle_ui_event(widget_id, kind, value) except Exception: @@ -647,9 +832,16 @@ def handle_ui_event(self, widget_id: str, kind: str, value: str) -> None: preview — funnels through here, so the batching lives inside rather than being something each caller has to remember to wrap. """ - # П-10: track UI-event depth so Navigator._discard can defer clearing + # Track UI-event depth so Navigator._discard can defer clearing # a popped screen's ``_app`` until the current handler returns. Then # code like ``self.app.pop(); self.app.theme`` still works. + if self._window_stopped and kind not in (WAKE_EVENT, LIFECYCLE_EVENT): + # The window is gone but the interpreter is not: a tap that arrives + # behind the stop belongs to whatever the user is looking at now. + # Dropping it here covers every front end; the device also refuses + # to queue one, which is the cheaper of the two. + _log.debug("ignoring %s on %s: the window is stopped", kind, widget_id) + return self._in_ui_dispatch += 1 try: with self._ui_lock, self.batch(): @@ -679,6 +871,30 @@ def _handle_ui_event(self, widget_id: str, kind: str, value: str) -> None: # device language react with: app.on("app:locale", ...). self.events.emit("app:locale", source=value) return + if kind == "insets": + # The keyboard opened or closed (the window handles the system bars + # itself). Apps that want to react — scroll to the field being + # typed into, hide a bottom bar — listen on "app:insets". + try: + height = int(str(value).strip() or "0") + except ValueError: + height = 0 + # ``source`` is typed as str on the bus; the height travels as a + # string and listeners can int() it, or read ``event.value``. + self.events.emit("app:insets", source=str(height)) + return + if kind == "theme": + # The system switched light/dark. ``uiMode`` is in configChanges, so + # the activity survives and this event is the only thing that tells + # Python; an app that picks its palette by hand listens on + # "app:system-theme", one that set ``follow_system_theme`` switches + # by itself. + dark = str(value).strip().lower() == "dark" + self._system_dark = dark + if self.follow_system_theme: + self._apply_system_theme(dark) + self.events.emit("app:system-theme", source="dark" if dark else "light") + return screen = self.navigator.current if screen is None: @@ -731,6 +947,10 @@ def _handle_ui_event(self, widget_id: str, kind: str, value: str) -> None: widget.increment() elif kind == "decrement" and hasattr(widget, "decrement"): widget.decrement() + elif kind == "submit" and hasattr(widget, "submit"): + # The keyboard's action key (Enter, "Go", "Done"). TextInput.submit + # takes no value: the field already holds what was typed. + widget.submit() elif kind == "search" and hasattr(widget, "submit"): widget.submit() elif kind == "load_more" and hasattr(widget, "_ui_load_more"): @@ -766,7 +986,7 @@ def _flush_detach_queue(self) -> None: """Null out the ``_app`` reference of screens popped during dispatch. Runs at the end of :meth:`handle_ui_event` once the outermost handler - has returned (П-10). + has returned. """ import contextlib @@ -793,6 +1013,33 @@ def _finish_or_stop(self) -> None: _log.exception("finish_app failed") self.stop() + # -- secrets ----------------------------------------------------------- + def save_secret(self, name: str, value: str) -> bool: + """Store ``value`` behind the platform keystore (Android) or in memory. + + A ``Storage`` file is plain JSON: an API token written there sits in the + app's data directory in the clear, inside every backup. This keeps it + encrypted with a key the Android keystore holds, so only this app on + this device can read it back. + """ + if not isinstance(name, str) or not name.strip(): + raise ValueError("secret name must be a non-empty string") + if not isinstance(value, str): + raise TypeError("secret value must be a string") + return bool(self.bridge.store_secret(name, value)) + + def load_secret(self, name: str) -> str | None: + """The secret stored under ``name``, or ``None``.""" + if not isinstance(name, str) or not name.strip(): + raise ValueError("secret name must be a non-empty string") + return self.bridge.load_secret(name) + + def delete_secret(self, name: str) -> bool: + """Forget ``name``; ``False`` when it was not there.""" + if not isinstance(name, str) or not name.strip(): + raise ValueError("secret name must be a non-empty string") + return bool(self.bridge.delete_secret(name)) + def stop(self) -> None: """Shut the app down and release subscriptions. @@ -809,6 +1056,9 @@ def stop(self) -> None: # (app.repeat_job() before run()), and those used to survive stop() # because the early return below skipped this line. self.jobs.shutdown() + # Idle keep-alive sockets: leaving them open after stop() would keep + # the process's fds alive and confuse a restart in the same process. + self.http.close() self._stopped = True if not self._running: return @@ -835,7 +1085,7 @@ def stop(self) -> None: finally: self.events.clear() _log.info("stopped %s", self.name) - # П-10: drop any deferred screen references at shutdown. + # Drop any deferred screen references at shutdown. self._in_ui_dispatch = 0 self._flush_detach_queue() @@ -947,9 +1197,7 @@ def _render_locked(self) -> dict[str, Any] | None: if bar is not None and bar.visible: tree["snackbar"] = bar.to_dict() native_navigation = ( - self._pending_navigation - if getattr(self.bridge, "native_widgets", False) - else None + self._pending_navigation if getattr(self.bridge, "native_widgets", False) else None ) self._check_widget_types(tree) # Qualify the ids the front end will echo back (see _resolve_wire_id). @@ -998,6 +1246,20 @@ def _check_widget_types(self, tree: dict[str, Any]) -> None: """ if not getattr(self.bridge, "native_widgets", False): return + # A19: the Android renderer draws local files only. An http(s) or data + # source is accepted by Image() and drawn by every desktop preview, so + # the phone showed an empty box and the log line was the only clue. + for source in _remote_image_sources(tree): + if source in self._warned_remote_images: + continue + self._warned_remote_images.add(source) + shown = source[:64] + ("…" if len(source) > 64 else "") + _log.warning( + "Image(source=%r) cannot be drawn on Android: the device renderer " + "loads local files only. Download it to the app's files directory " + "and pass that path, or keep it as a bundled asset.", + shown, + ) for name in sorted(unknown_types(tree, renderer="android")): if name in self._warned_unknown_types: continue diff --git a/pymobile/core/bridge/android.py b/pymobile/core/bridge/android.py index c8682be..5a61902 100644 --- a/pymobile/core/bridge/android.py +++ b/pymobile/core/bridge/android.py @@ -16,7 +16,7 @@ from ...errors import BridgeError from ...log import get_logger -from .base import Bridge, NotificationSpec, PickedFile +from .base import Bridge, NotificationSpec, PickedFile, _check_openable_url __all__ = [ "AndroidBridge", @@ -44,6 +44,10 @@ class AndroidBridge(Bridge): #: The device renderer draws its default colours from the app theme. accepts_theme = True + # ``chrome`` carries the screen title and ``can_go_back``; the window needs + # the second one to decide whether the back gesture belongs to the app or + # to the platform (A9: a permanently registered callback swallowed it). + accepts_chrome = True #: The tree goes to ``ViewBuilder.java``, which has one branch per built-in #: type and drops anything else. Apps are warned about unknown types (see @@ -54,7 +58,16 @@ def __init__(self) -> None: self._native = native_module() self._granted: set[str] = set() + @classmethod + def with_native(cls, native: Any) -> AndroidBridge: + """Build a bridge around an explicit native module (tests, custom runtimes).""" + bridge = cls.__new__(cls) + bridge._native = native + bridge._granted = set() + return bridge + def is_available(self) -> bool: + """Whether the app is running inside the Android runtime.""" return self._native is not None # -- ui ---------------------------------------------------------------- @@ -84,6 +97,7 @@ def wake(self) -> None: self._native.render(self.WAKE_PAYLOAD) def toast(self, message: str, long: bool = False) -> None: + """Show a short system message, or do nothing off the device.""" if self._native is not None: self._native.toast(message, bool(long)) @@ -99,6 +113,7 @@ def ensure_channel(self, channel_id: str, channel_name: str, importance: int) -> self._native.ensure_channel(channel_id, channel_name, int(importance)) def notify(self, spec: NotificationSpec) -> None: + """Post the notification, falling back to the older native signature.""" if self._native is None: return native = self._native @@ -126,11 +141,13 @@ def notify(self, spec: NotificationSpec) -> None: _log.exception("notify failed") def cancel_notification(self, notification_id: int) -> None: + """Remove the notification with ``notification_id``.""" if self._native is not None: self._native.cancel_notification(notification_id) # -- vibration --------------------------------------------------------- def vibrate(self, milliseconds: int, amplitude: int = -1) -> None: + """Vibrate once for ``milliseconds`` at the given amplitude.""" if self._native is None: return try: @@ -140,15 +157,18 @@ def vibrate(self, milliseconds: int, amplitude: int = -1) -> None: self._native.vibrate(int(milliseconds)) def vibrate_pattern(self, pattern: list[int], repeat: int = -1) -> None: + """Vibrate in the given on/off pattern, repeating it ``repeat`` times.""" if self._native is not None: self._native.vibrate_pattern([int(v) for v in pattern], int(repeat)) def cancel_vibration(self) -> None: + """Stop any vibration in progress.""" if self._native is not None: self._native.cancel_vibration() # -- permissions ------------------------------------------------------- def has_permission(self, permission: str) -> bool: + """Whether the runtime permission is currently granted.""" if self._native is None: return False return bool(self._native.has_permission(permission)) @@ -173,7 +193,6 @@ def request_permissions(self, permissions: list[str]) -> dict[str, bool]: results[permission] = granted or bool(self._native.has_permission(permission)) return results - # -- files ------------------------------------------------------------- def pick_file(self, request: str = "*/*", *, multiple: bool = False) -> list[PickedFile]: """Open the system picker and copy the answer into the app's cache. @@ -193,6 +212,7 @@ def pick_file(self, request: str = "*/*", *, multiple: bool = False) -> list[Pic return [self._describe(path) for path in paths if path] def pick_image(self) -> list[PickedFile]: + """Ask the system picker for images and return what the user chose.""" if self._native is None: return [] picker = getattr(self._native, "pick_image", None) @@ -215,6 +235,7 @@ def _describe(path: str) -> PickedFile: # -- clipboard --------------------------------------------------------- def copy_to_clipboard(self, text: str) -> bool: + """Copy the text to the system clipboard and report success.""" if self._native is None: return False copy = getattr(self._native, "copy_to_clipboard", None) @@ -223,6 +244,7 @@ def copy_to_clipboard(self, text: str) -> bool: return bool(copy(text)) def clipboard_text(self) -> str: + """The text on the system clipboard, or an empty string.""" if self._native is None: return "" getter = getattr(self._native, "clipboard_text", None) @@ -232,6 +254,7 @@ def clipboard_text(self) -> str: # -- share sheet ------------------------------------------------------- def share(self, text: str = "", url: str = "", subject: str = "") -> bool: + """Open the system share sheet and report whether it was shown.""" if self._native is None: return False share = getattr(self._native, "share", None) @@ -250,6 +273,7 @@ def audio_player(self, source: str, **options: Any) -> Any: return NativeAudioPlayer(self._native, source, **options) def audio_recorder(self, *, directory: str = "") -> Any: + """The on-device recorder, or an error when the runtime cannot record.""" if self._native is None: raise BridgeError( "the native recorder is not available in this runtime", @@ -267,6 +291,53 @@ def device_language(self) -> str: return "" return str(getter() or "") + # -- secrets ----------------------------------------------------------- + def store_secret(self, name: str, value: str) -> bool: + """Encrypt ``value`` with the Android keystore and persist it.""" + native = self._native + setter = getattr(native, "put_secret", None) if native is not None else None + if setter is None: + raise NotImplementedError( + "this device runtime has no put_secret; rebuild the APK with " + "the current framework (pymobile rebuild-dex)" + ) + try: + return bool(setter(name, value)) + except Exception: + _log.exception("put_secret(%r) failed", name) + return False + + def load_secret(self, name: str) -> str | None: + """The stored secret, or ``None`` when absent (or the key is gone).""" + native = self._native + getter = getattr(native, "get_secret", None) if native is not None else None + if getter is None: + raise NotImplementedError( + "this device runtime has no get_secret; rebuild the APK with " + "the current framework (pymobile rebuild-dex)" + ) + try: + value = getter(name) + except Exception: + _log.exception("get_secret(%r) failed", name) + return None + return None if value is None else str(value) + + def delete_secret(self, name: str) -> bool: + """Remove a stored secret and report whether it existed.""" + native = self._native + remover = getattr(native, "delete_secret", None) if native is not None else None + if remover is None: + raise NotImplementedError( + "this device runtime has no delete_secret; rebuild the APK with " + "the current framework (pymobile rebuild-dex)" + ) + try: + return bool(remover(name)) + except Exception: + _log.exception("delete_secret(%r) failed", name) + return False + # -- external ---------------------------------------------------------- def open_url(self, url: str) -> bool: """Open ``url`` in the system browser on Android. @@ -274,6 +345,7 @@ def open_url(self, url: str) -> bool: Falls back to the native module when it exposes ``open_url``; otherwise returns ``False`` (no crash, the app keeps running). """ + _check_openable_url(url) if self._native is not None and hasattr(self._native, "open_url"): try: return bool(self._native.open_url(url)) @@ -338,33 +410,43 @@ def __init__(self, native: Any, source: str, **options: Any) -> None: # MediaPlayer has no end callback Python can safely re-enter, so the API # layer's polling detects the end; these are the plain transport calls. def play(self) -> None: + """Start or resume playback.""" self._native.audio_play(self.handle) def pause(self) -> None: + """Pause playback, keeping the position.""" self._native.audio_pause(self.handle) def stop(self) -> None: + """Stop playback and rewind to the start.""" self._native.audio_stop(self.handle) def seek(self, position_ms: int) -> None: + """Jump to ``position_ms`` inside the clip.""" self._native.audio_seek(self.handle, int(position_ms)) def position(self) -> int: + """How far the clip has played, in milliseconds.""" return int(self._native.audio_position(self.handle)) def duration(self) -> int: + """The length of the clip, in milliseconds.""" return int(self._native.audio_duration(self.handle)) def is_playing(self) -> bool: + """Whether the clip is playing right now.""" return bool(self._native.audio_is_playing(self.handle)) def set_volume(self, level: float) -> None: + """Set the volume on a 0.0..1.0 scale.""" self._native.audio_volume(self.handle, float(level)) def set_looping(self, looping: bool) -> None: + """Choose whether playback repeats at the end.""" self._native.audio_looping(self.handle, bool(looping)) def release(self) -> None: + """Stop playback and release the native player handle.""" if self.handle >= 0: self._native.audio_release(self.handle) self.handle = -1 @@ -379,6 +461,7 @@ def __init__(self, native: Any, directory: str = "") -> None: self.handle = -1 def start(self) -> None: + """Start recording, or raise when the microphone is unavailable.""" starter = getattr(self._native, "recorder_start", None) if starter is None: # pragma: no cover - older runtime raise BridgeError("this runtime cannot record audio") @@ -390,6 +473,7 @@ def start(self) -> None: ) def stop(self) -> str: + """Stop recording and return the path of the file written.""" if self.handle < 0: return "" path = str(self._native.recorder_stop(self.handle) or "") @@ -397,6 +481,7 @@ def stop(self) -> str: return path def cancel(self) -> None: + """Stop recording and delete the partial file.""" if self.handle >= 0: cancel = getattr(self._native, "recorder_cancel", None) if cancel is not None: @@ -404,11 +489,13 @@ def cancel(self) -> None: self.handle = -1 def is_recording(self) -> bool: + """Whether the recorder is capturing sound right now.""" if self.handle < 0: return False return bool(self._native.recorder_is_recording(self.handle)) def elapsed_ms(self) -> int: + """How long the current recording has been running.""" if self.handle < 0: return 0 return int(self._native.recorder_elapsed(self.handle)) diff --git a/pymobile/core/bridge/base.py b/pymobile/core/bridge/base.py index 0cafdb1..0264ead 100644 --- a/pymobile/core/bridge/base.py +++ b/pymobile/core/bridge/base.py @@ -14,7 +14,14 @@ from pathlib import Path from typing import Any -__all__ = ["Bridge", "BridgeCall", "NotificationSpec", "PickedFile", "pick_filters"] +__all__ = [ + "Bridge", + "BridgeCall", + "NotificationSpec", + "PickedFile", + "OPENABLE_SCHEMES", + "pick_filters", +] @dataclass(frozen=True, slots=True) @@ -213,9 +220,7 @@ def device_language(self) -> str: return "" # -- files ------------------------------------------------------------- - def pick_file( - self, accept: str = "*/*", *, multiple: bool = False - ) -> list[PickedFile]: + def pick_file(self, accept: str = "*/*", *, multiple: bool = False) -> list[PickedFile]: """Let the user choose one or more files; empty when they cancel. Not abstract: a bridge with no picker (a desktop preview) returns an @@ -242,14 +247,69 @@ def share(self, text: str = "", url: str = "", subject: str = "") -> bool: """Open the system share sheet; ``False`` when nothing could share it.""" return False + # -- secrets ----------------------------------------------------------- + def store_secret(self, name: str, value: str) -> bool: + """Store ``value`` under ``name`` behind the platform keystore. + + Not abstract: a bridge with no keystore (a desktop preview) returns + ``False`` and the caller decides what to do. On Android the value is + encrypted with a key the keystore holds, so it is not readable from a + copy of the app's data directory. + """ + raise NotImplementedError( + f"the {self.name} bridge cannot store secrets; " + "use app.save_secret() on a device or pass a custom bridge" + ) + + def load_secret(self, name: str) -> str | None: + """The secret stored under ``name``, or ``None`` when there is none.""" + raise NotImplementedError( + f"the {self.name} bridge cannot read secrets; " + "use app.load_secret() on a device or pass a custom bridge" + ) + + def delete_secret(self, name: str) -> bool: + """Forget ``name``; ``False`` when it did not exist or is unsupported.""" + raise NotImplementedError( + f"the {self.name} bridge cannot delete secrets; " + "use app.delete_secret() on a device or pass a custom bridge" + ) + # -- external ---------------------------------------------------------- def open_url(self, url: str) -> bool: """Open ``url`` in an external viewer (browser). Returns ``True`` when handled; the default desktop implementation opens - the system browser via ``webbrowser``. + the system browser via ``webbrowser``. Only ``http``, ``https``, + ``mailto`` and ``tel`` are opened: the URL often comes from server data, + and a ``file:`` or ``intent:`` link there must not reach the platform. """ + _check_openable_url(url) import webbrowser webbrowser.open(url) return True + + +#: Schemes a link from app data may open. ``tel:`` and ``sms:`` dial or compose; +#: everything else (``file:``, ``intent:``, ``javascript:``, custom schemes) is +#: refused, because ``Intent.parseUri`` on a hostile string can reach parts of +#: the system the app never meant to expose. +OPENABLE_SCHEMES: frozenset[str] = frozenset({"http", "https", "mailto", "tel"}) + + +def _check_openable_url(url: str) -> str: + """Validate ``url`` for :meth:`Bridge.open_url`; returns the stripped URL.""" + if not isinstance(url, str): + raise TypeError("url must be a string") + text = url.strip() + if not text: + raise ValueError("url must not be empty") + scheme = text.split(":", 1)[0].strip().casefold() if ":" in text else "" + # A relative path has no scheme and cannot open anything: refuse it here + # rather than letting the platform guess. + if scheme not in OPENABLE_SCHEMES: + raise ValueError( + f"refusing to open {text!r}: allowed schemes are {', '.join(sorted(OPENABLE_SCHEMES))}" + ) + return text diff --git a/pymobile/core/bridge/gui.py b/pymobile/core/bridge/gui.py index 4bb8ef7..6a117ac 100644 --- a/pymobile/core/bridge/gui.py +++ b/pymobile/core/bridge/gui.py @@ -38,11 +38,13 @@ def attach(self, preview: GuiPreview) -> None: preview.render(self.last_tree) def render(self, tree: dict[str, Any]) -> None: + """Record the tree and draw it in the window, when one is open.""" super().render(tree) if self._preview is not None: self._preview.render(tree) def toast(self, message: str, long: bool = False) -> None: + """Record the message and show it in the window's status line.""" super().toast(message, long) if self._preview is not None: self._preview.toast(message) @@ -55,6 +57,7 @@ def call_soon(self, function: Callable[[], None]) -> bool: return True def vibrate(self, milliseconds: int, amplitude: int = -1) -> None: + """Record the vibration and say so in the window, since nothing can shake.""" super().vibrate(milliseconds, amplitude) if self._preview is not None: self._preview.toast(f"vibrate {milliseconds} ms") @@ -76,16 +79,19 @@ def attach(self, preview: WebPreview) -> None: preview.update(self.last_tree) def render(self, tree: dict[str, Any]) -> None: + """Record the tree and hand it to the browser page.""" super().render(tree) if self._preview is not None: self._preview.update(tree) def toast(self, message: str, long: bool = False) -> None: + """Record the message and show it in the page.""" super().toast(message, long) if self._preview is not None: self._preview.toast(message) def vibrate(self, milliseconds: int, amplitude: int = -1) -> None: + """Record the vibration and say so in the page, since nothing can shake.""" super().vibrate(milliseconds, amplitude) if self._preview is not None: self._preview.toast(f"vibrate {milliseconds} ms") diff --git a/pymobile/core/bridge/jni.py b/pymobile/core/bridge/jni.py index 13e68cc..6529eca 100644 --- a/pymobile/core/bridge/jni.py +++ b/pymobile/core/bridge/jni.py @@ -82,6 +82,7 @@ def _context(self) -> Any: # pragma: no cover - device-only path return self._activity.getApplicationContext() def is_available(self) -> bool: + """Whether the pyjnius bindings can be imported in this runtime.""" try: import jnius # type: ignore[import-not-found] # noqa: F401 except ImportError: @@ -92,6 +93,7 @@ def is_available(self) -> bool: def ensure_channel( # pragma: no cover - device-only path self, channel_id: str, channel_name: str, importance: int = IMPORTANCE_DEFAULT ) -> None: + """Create the notification channel, which Android 8 and newer require.""" build_version = self._autoclass("android.os.Build$VERSION") if build_version.SDK_INT < 26: # channels landed in Oreo return @@ -103,6 +105,7 @@ def ensure_channel( # pragma: no cover - device-only path manager.createNotificationChannel(channel) def notify(self, spec: NotificationSpec) -> None: # pragma: no cover - device-only path + """Build and post the notification through the platform builder.""" self.ensure_channel(spec.channel_id, spec.channel_name, IMPORTANCE_DEFAULT) builder_cls = self._autoclass("android.app.Notification$Builder") build_version = self._autoclass("android.os.Build$VERSION") @@ -126,7 +129,11 @@ def _icon_id(self, name: str | None) -> int: # pragma: no cover - device-only p """Resolve a drawable name to a resource id, falling back to the app icon.""" resources = self._context.getResources() package = self._context.getPackageName() - for candidate, kind in ((name, "drawable"), ("icon", "mipmap"), ("icon", "drawable")): + for candidate, kind in ( + (name, "drawable"), + ("ic_launcher", "mipmap"), + ("ic_launcher", "drawable"), + ): if not candidate: continue found = resources.getIdentifier(candidate, kind, package) @@ -135,6 +142,7 @@ def _icon_id(self, name: str | None) -> int: # pragma: no cover - device-only p return int(self._autoclass("android.R$drawable").ic_dialog_info) def cancel_notification(self, notification_id: int) -> None: # pragma: no cover + """Remove the notification with ``notification_id``.""" manager = self._context.getSystemService( self._autoclass("android.content.Context").NOTIFICATION_SERVICE ) @@ -153,6 +161,7 @@ def _vibrator(self) -> Any: # pragma: no cover - device-only path def vibrate( # pragma: no cover - device-only path self, milliseconds: int, amplitude: int = DEFAULT_AMPLITUDE ) -> None: + """Vibrate once for ``milliseconds`` at the given amplitude.""" build_version = self._autoclass("android.os.Build$VERSION") if build_version.SDK_INT >= 26: effect_cls = self._autoclass("android.os.VibrationEffect") @@ -163,6 +172,7 @@ def vibrate( # pragma: no cover - device-only path def vibrate_pattern( # pragma: no cover - device-only path self, pattern: list[int], repeat: int = -1 ) -> None: + """Vibrate in the given on/off pattern, repeating it ``repeat`` times.""" build_version = self._autoclass("android.os.Build$VERSION") if build_version.SDK_INT >= 26: effect_cls = self._autoclass("android.os.VibrationEffect") @@ -171,10 +181,12 @@ def vibrate_pattern( # pragma: no cover - device-only path self._vibrator.vibrate(pattern, repeat) def cancel_vibration(self) -> None: # pragma: no cover - device-only path + """Stop any vibration in progress.""" self._vibrator.cancel() # -- permissions ------------------------------------------------------- def has_permission(self, permission: str) -> bool: # pragma: no cover - device-only path + """Whether the runtime permission is currently granted.""" package_manager = self._autoclass("android.content.pm.PackageManager") result = self._context.checkSelfPermission(permission) return int(result) == int(package_manager.PERMISSION_GRANTED) @@ -252,9 +264,7 @@ def _ensure_permission_callback(self) -> None: bridge = self class _PermissionListener(PythonJavaClass): # type: ignore[misc] - __javainterfaces__: ClassVar[list[str]] = [ - "org/pymobile/app/PermissionListener" - ] + __javainterfaces__: ClassVar[list[str]] = ["org/pymobile/app/PermissionListener"] __javacontext__: ClassVar[str] = "app" @java_method( # type: ignore[untyped-decorator] @@ -267,6 +277,7 @@ def onResult( grant_results_j: Any, _rationale_asked: bool, ) -> None: + """Collect the answers, finish the future and drop the listener.""" names = list(permissions_j) if permissions_j is not None else [] grants = list(grant_results_j) if grant_results_j is not None else [] # PackageManager.PERMISSION_GRANTED == 0; anything else is denied. @@ -283,6 +294,7 @@ def onResult( # -- ui ---------------------------------------------------------------- def toast(self, message: str, long: bool = False) -> None: # pragma: no cover + """Show a short system message on the UI thread.""" toast_cls = self._autoclass("android.widget.Toast") duration = toast_cls.LENGTH_LONG if long else toast_cls.LENGTH_SHORT self._run_on_ui(lambda: toast_cls.makeText(self._context, message, duration).show()) @@ -307,6 +319,7 @@ class _Runnable(PythonJavaClass): # type: ignore[misc] @java_method("()V") # type: ignore[untyped-decorator] def run(self) -> None: + """Run the posted action on the UI thread, then forget it.""" try: action() finally: @@ -355,10 +368,12 @@ def __init__(self, permissions: list[str]) -> None: @property def done(self) -> bool: + """Whether every requested permission has been answered.""" return self._done.is_set() @property def result(self) -> dict[str, bool]: + """The answers as a permission-to-bool mapping, waiting for them if needed.""" return dict(self._result) def wait(self, timeout: float | None = None) -> dict[str, bool]: diff --git a/pymobile/core/bridge/stub.py b/pymobile/core/bridge/stub.py index 57dde0b..bba4d59 100644 --- a/pymobile/core/bridge/stub.py +++ b/pymobile/core/bridge/stub.py @@ -49,6 +49,9 @@ def __init__( self.clipboard = "" #: Every :meth:`share` call, in order. self.shared: list[dict[str, str]] = [] + #: Secrets written through :meth:`store_secret`; a desktop run keeps + #: them in memory only, which is the honest answer to "no keystore". + self.secrets: dict[str, str] = {} #: Players and recorders created through this bridge, for assertions. self.players: list[StubAudioPlayer] = [] self.recordings: list[StubAudioRecorder] = [] @@ -77,10 +80,12 @@ def reset(self) -> None: self.recordings.clear() def is_available(self) -> bool: + """The stub answers every call, so it is always available.""" return True # -- notifications ----------------------------------------------------- def ensure_channel(self, channel_id: str, channel_name: str, importance: int) -> None: + """Record the notification channel request; nothing is created.""" self._record( "ensure_channel", channel_id=channel_id, @@ -89,28 +94,35 @@ def ensure_channel(self, channel_id: str, channel_name: str, importance: int) -> ) def notify(self, spec: NotificationSpec) -> None: + """Store the notification and record the call.""" self.notifications[spec.notification_id] = spec self._record("notify", id=spec.notification_id, title=spec.title, body=spec.body) def cancel_notification(self, notification_id: int) -> None: + """Drop the stored notification and record the call.""" self.notifications.pop(notification_id, None) self._record("cancel_notification", id=notification_id) # -- vibration --------------------------------------------------------- def vibrate(self, milliseconds: int, amplitude: int) -> None: + """Record a one-shot vibration; no device is touched.""" self._record("vibrate", milliseconds=milliseconds, amplitude=amplitude) def vibrate_pattern(self, pattern: list[int], repeat: int) -> None: + """Record a vibration pattern; no device is touched.""" self._record("vibrate_pattern", pattern=list(pattern), repeat=repeat) def cancel_vibration(self) -> None: + """Record that any vibration should stop.""" self._record("cancel_vibration") # -- permissions ------------------------------------------------------- def has_permission(self, permission: str) -> bool: + """Whether the permission was granted to this stub.""" return permission in self.granted def request_permissions(self, permissions: list[str]) -> dict[str, bool]: + """Grant the permissions this stub was told to grant and report the outcome.""" self._record("request_permissions", permissions=list(permissions)) result: dict[str, bool] = {} for permission in permissions: @@ -122,32 +134,39 @@ def request_permissions(self, permissions: list[str]) -> dict[str, bool]: # -- ui ---------------------------------------------------------------- def toast(self, message: str, long: bool = False) -> None: + """Record a toast message.""" self._record("toast", message=message, long=long) def render(self, tree: dict[str, Any]) -> None: + """Remember the latest tree and record how big it was.""" self.last_tree = tree self._record("render", root=tree.get("type"), children=len(tree.get("children", ()))) # -- files ------------------------------------------------------------- def pick_file(self, accept: str = "*/*", *, multiple: bool = False) -> list[PickedFile]: + """Return the file picks this stub was given, filtered by nothing.""" self._record("pick_file", accept=accept, multiple=multiple) return [PickedFile(path) for path in self.file_picks] def pick_image(self) -> list[PickedFile]: + """Return the file picks this stub was given.""" self._record("pick_image") return [PickedFile(path) for path in self.file_picks] # -- clipboard --------------------------------------------------------- def copy_to_clipboard(self, text: str) -> bool: + """Keep the text where :meth:`clipboard_text` can read it back.""" self.clipboard = text self._record("copy_to_clipboard", text=text) return True def clipboard_text(self) -> str: + """The text last copied, or an empty string.""" return self.clipboard # -- share sheet ------------------------------------------------------- def share(self, text: str = "", url: str = "", subject: str = "") -> bool: + """Record what was shared and report success.""" self.shared.append({"text": text, "url": url, "subject": subject}) self._record("share", text=text, url=url, subject=subject) return True @@ -161,13 +180,34 @@ def audio_player(self, source: str, **options: Any) -> Any: return player def audio_recorder(self, *, directory: str = "") -> Any: + """A recorder that writes a small file instead of recording sound.""" recorder = StubAudioRecorder(Path(self.recordings_dir or directory or ".")) self.recordings.append(recorder) self._record("audio_recorder", directory=str(recorder.directory)) return recorder # -- locale ------------------------------------------------------------ + # -- secrets ----------------------------------------------------------- + def store_secret(self, name: str, value: str) -> bool: + # The value is deliberately not recorded: a call log that quotes a + # secret is exactly what this API exists to avoid. + """Keep the secret in memory and record the call without the value.""" + self._record("store_secret", secret=name) + self.secrets[name] = value + return True + + def load_secret(self, name: str) -> str | None: + """The secret stored under ``name``, or an empty string.""" + self._record("load_secret", secret=name) + return self.secrets.get(name) + + def delete_secret(self, name: str) -> bool: + """Forget the secret and report whether it was there.""" + self._record("delete_secret", secret=name) + return self.secrets.pop(name, None) is not None + def device_language(self) -> str: + """The language tag this stub was configured for.""" return self.language @@ -204,33 +244,43 @@ def _now(self) -> int: return self.offset + int((time.monotonic() - self.started_at) * 1000) def play(self) -> None: + """Start the fake clock: time advances, but nothing is heard.""" self.started_at = time.monotonic() def pause(self) -> None: + """Freeze the clock and remember the position.""" self.offset = self._now() def stop(self) -> None: + """Freeze the clock and rewind to the start.""" self.offset = 0 def seek(self, position_ms: int) -> None: + """Move the position to ``position_ms``, clamped to the clip.""" self.offset = max(0, int(position_ms)) def position(self) -> int: + """How far the clip has played, from the fake clock.""" return self._now() def duration(self) -> int: + """The length of the clip, as the stub was told it.""" return self.duration_ms def is_playing(self) -> bool: + """Whether the fake clock is running.""" return not self.released and self._now() < self.duration_ms def set_looping(self, looping: bool) -> None: + """Remember whether playback should repeat.""" self.looping = bool(looping) def set_volume(self, volume: float) -> None: + """Remember the volume, clamped to 0.0..1.0.""" self.volume = float(volume) def release(self) -> None: + """Stop playback and free the fake player.""" self.released = True @@ -244,6 +294,7 @@ def __init__(self, directory: Path) -> None: self.target: Path | None = None def start(self) -> None: + """Create an empty file in place of a recording and start the clock.""" self.started_at = time.monotonic() self.active = True self.directory.mkdir(parents=True, exist_ok=True) @@ -251,18 +302,22 @@ def start(self) -> None: self.target.write_bytes(b"pymobile-stub-recording") def is_recording(self) -> bool: + """Whether the fake recorder has been started and not stopped.""" return self.active def elapsed_ms(self) -> int: + """How long the fake recording has been running.""" if not self.active: return 0 return int((time.monotonic() - self.started_at) * 1000) def stop(self) -> str: + """Stop the clock and return the path of the empty file.""" self.active = False return str(self.target) if self.target is not None else "" def cancel(self) -> None: + """Stop the clock and delete the empty file.""" self.active = False if self.target is not None: self.target.unlink(missing_ok=True) diff --git a/pymobile/core/config.py b/pymobile/core/config.py index 8029aff..9a74a8d 100644 --- a/pymobile/core/config.py +++ b/pymobile/core/config.py @@ -8,7 +8,9 @@ from __future__ import annotations +import base64 import re +from collections.abc import Mapping, Sequence from dataclasses import dataclass, field, fields from pathlib import Path from typing import Any @@ -51,7 +53,7 @@ #: scaffolded ``README.md`` out of the APK so a fresh project builds with no #: "not packaged" warning. #: -#: Secret-like filenames are excluded by default (П-03): shipping keystores, +#: Secret-like filenames are excluded by default: shipping keystores, #: private keys or env files inside an APK leaks credentials the moment the #: APK is unzipped. ``google-services.json`` is intentionally **not** here — #: it is a Firebase config that must ship; projects that name a file @@ -76,7 +78,7 @@ # the default output_dir; a project that keeps the default must not ship # the previous APK (see BuildPipeline._warn_unexcluded_output) "apk/**", - # secret-like files (П-03) + # secret-like files ".env", ".env.*", "*.jks", @@ -90,11 +92,23 @@ "secrets.*.json", "credentials.json", "credentials.*.json", + # A folder is matched by name, not only the exact `secrets/` one: projects + # keep credentials in `secret/`, `config/private/`, `.aws/`. S6 in the 3.1 + # audit was a plain `secret/notes.txt` inside an APK. + "secret/**", + ".aws/**", + ".ssh/**", + "*.p12", + "*.pfx", + "*.ovpn", + "token.json", + "tokens.json", + "auth.json", ) #: File basenames that look like secrets (used to emit a warning when a #: matching file is **not** covered by an exclude pattern, so the user notices -#: before shipping). П-03. +#: before shipping). SECRET_LIKE_BASENAMES: frozenset[str] = frozenset( { ".env", @@ -151,8 +165,9 @@ class ProjectConfig: #: Projects created before 0.8.0 say ``min_sdk = 21``; that still loads, #: but the APK declares :attr:`effective_min_sdk` and the build warns. min_sdk: int = RUNTIME_MIN_SDK - #: Android API level the app is tested against. - target_sdk: int = 35 + #: Android API level the app is tested against. 36 is what Google Play + #: requires for new apps and updates from 31 August 2026. + target_sdk: int = 36 #: Screen orientation, for example "portrait" or "landscape". orientation: str = "portrait" #: Android permissions the app asks for, for example android.permission.CAMERA. @@ -162,6 +177,14 @@ class ProjectConfig: #: Let Android back up the app's private data (cloud backup, adb backup). #: Off by default: the store often holds tokens and personal data. allow_backup: bool = False + #: Trust only these certificates for the listed domains, ignoring the + #: device's user-installed roots (a corporate proxy, a "Wi-Fi inspector" + #: app, a malware profile with a CA). TOML: + #: ``[network.pins] "api.example.com" = ["sha256/AAAA…="]`` — a pin is a + #: base64 SHA-256 of the certificate's SubjectPublicKeyInfo, the same string + #: ``openssl`` prints. Only domains listed are pinned; the rest of the app + #: keeps the system trust store. + network_pins: dict[str, list[str]] = field(default_factory=dict) # -- build ------------------------------------------------------------- #: CPU architectures to build for: arm64-v8a for phones, x86_64 for the emulator. @@ -204,7 +227,7 @@ def effective_min_sdk(self) -> int: # -- validation -------------------------------------------------------- def __post_init__(self) -> None: - # П-05: coerce path-like scalars to strings early so a Path value + # Coerce path-like scalars to strings early so a Path value # (e.g. passed from the API) round-trips cleanly, then validate() # runs the type gates before any range/path arithmetic. self.root = Path(self.root).resolve() @@ -212,7 +235,7 @@ def __post_init__(self) -> None: self.source_dir = str(self.source_dir) if isinstance(self.output_dir, Path): self.output_dir = str(self.output_dir) - # П-04: "no"/"yes"/"true"/"false" strings are a common TOML typo. + # "no"/"yes"/"true"/"false" strings are a common TOML typo: refuse them. for bool_field in ( "allow_backup", "optimize", @@ -229,7 +252,7 @@ def __post_init__(self) -> None: elif low in ("false", "no", "off", "0", ""): setattr(self, bool_field, False) # leave other strings for the type gate in validate() - # П-01/П-02: normalize list fields defensively. + # Normalise list fields defensively: a bare string is one entry, not characters. for list_field in ("permissions", "abis", "asset_suffixes", "dependencies"): value = getattr(self, list_field) if value is None: @@ -254,7 +277,7 @@ def normalise_exclude(self) -> None: def validate(self) -> None: """Raise :class:`ConfigError` if any field is invalid.""" - # ---- type gates (П-01, П-02, П-04, П-05, П-15) ------------------- + # ---- type gates --------------------------------------------------- # These come first so a wrong type gives a helpful message instead # of a raw ``TypeError`` from a downstream range/path comparison. self._check_type("name", self.name, str) @@ -369,7 +392,7 @@ def validate(self) -> None: # Normalise permissions now so every caller (manifest, info --json, # warnings) sees the fully-qualified form that actually ends up in - # the APK. П-23. + # the APK. from ..core.api.permissions import normalize as _norm_perm self.permissions = [_norm_perm(p) for p in self.permissions] @@ -380,6 +403,37 @@ def validate(self) -> None: f"Invalid asset suffix {suffix!r}", hint="Write extensions with a leading dot, e.g. asset_suffixes = ['.csv'].", ) + if not isinstance(self.network_pins, Mapping): + raise ConfigError("`network_pins` must map a domain to a list of pins") + for domain, pins in self.network_pins.items(): + if not isinstance(domain, str) or not domain.strip() or "/" in domain: + raise ConfigError( + f"`network_pins` key {domain!r} is not a domain " + "(use `api.example.com`, without a scheme or a path)" + ) + if isinstance(pins, str) or not isinstance(pins, Sequence) or not pins: + raise ConfigError(f"`network_pins[{domain!r}]` must be a non-empty list of pins") + for pin in pins: + if not isinstance(pin, str) or not pin: + raise ConfigError( + f"`network_pins[{domain!r}]` entry {pin!r} is not a pin: " + 'a pin looks like "sha256/"' + ) + # Both forms are accepted: the one openssl prints with the + # algorithm prefix, and the bare base64 Android's XML wants. + encoded = pin[len("sha256/") :] if pin.startswith("sha256/") else pin + try: + raw = base64.b64decode(encoded, validate=True) + except Exception as error: + raise ConfigError( + f"`network_pins[{domain!r}]` entry {pin!r} is not valid base64: {error}" + ) from error + if len(raw) != 32: + raise ConfigError( + f"`network_pins[{domain!r}]` entry {pin!r} is {len(raw)} bytes, " + "expected 32 (SHA-256)" + ) + unknown_abis = [abi for abi in self.abis if abi not in _ABI_CHOICES] if unknown_abis: raise ConfigError( @@ -430,13 +484,34 @@ def icon_path(self) -> Path | None: @property def apk_name(self) -> str: - """File name of the produced APK. + """File name of the installable (native) APK. Names written in a non-Latin script strip to nothing under the ASCII filter — and so do names whose Latin residue is digits only, ``Нотатки 2`` (com.example.notes) strips to ``2`` — so the last package segment is used instead of a generic or digit-only file name: both yield ``notes-0.1.0.apk``. + + Use :meth:`apk_name_for` when the build mode is known: a structural + package gets its own name instead of overwriting this one. + """ + return self.apk_name_for("native") + + def apk_name_for(self, mode: str | None = None) -> str: + """File name of the APK a build in ``mode`` produces. + + ``mode`` is :meth:`pymobile.compiler.pipeline.BuildPipeline.build_mode` + — ``native``, ``native+java``, ``structural`` and their variants. A + structural build is not installable, so its artifact is named + ``…-debug.apk``, the usual Android convention, and a following + ``build --native`` cannot mistake it for its own output. The two used to + share one name, so a quick structural build silently left an + uninstallable file where ``pymobile install`` looked for the APK — and + the install then failed with a signature error that said nothing about + the real cause. + + An unknown mode is treated as native: the plain name belongs to the + installable artifact. """ safe = re.sub(r"[^A-Za-z0-9._-]+", "-", self.name).strip("-.").lower() if not re.search(r"[a-z]", safe): @@ -445,6 +520,8 @@ def apk_name(self) -> str: # APK: it is suffixed with its ABI. The arm64 name is unchanged. abi = self.abis[0] if self.abis else "arm64-v8a" suffix = "" if abi == "arm64-v8a" else f"-{abi}" + if mode is not None and not str(mode).startswith("native"): + suffix += "-debug" return f"{safe}-{self.version}{suffix}.apk" # -- serialisation ----------------------------------------------------- @@ -533,6 +610,16 @@ def load_config(path: str | Path | None = None) -> ProjectConfig: ) from exc if isinstance(project, dict) and "dependencies" in project: values["dependencies"] = project["dependencies"] + # `[network.pins] "host" = ["sha256/…"]` nests under a TOML table, because + # a domain key with dots in it (`api.example.com`) cannot be written flat. + # A single flat `network_pins = { … }` value is accepted as well. + network = raw.get("network") + if isinstance(network, dict): + # `[network.pins]` is a TOML table (a dotted host key cannot be a flat + # key), and `[network]` must not reach ProjectConfig as an unknown key. + values.pop("network", None) + if isinstance(network.get("pins"), dict): + values.setdefault("network_pins", dict(network["pins"])) return ProjectConfig.from_dict(values, root=candidate.parent) diff --git a/pymobile/core/driver.py b/pymobile/core/driver.py index 75751dd..fe4f231 100644 --- a/pymobile/core/driver.py +++ b/pymobile/core/driver.py @@ -129,9 +129,7 @@ def discover_screens( # The entry point has already been executed as ``__main__``: importing the # same file again would define every screen a second time and make names # ambiguous. Callers pass it in ``exclude``. - skipped = { - str(Path(item).expanduser().resolve()) for item in exclude - } + skipped = {str(Path(item).expanduser().resolve()) for item in exclude} roots: list[Path] = [] for raw in paths: root = Path(raw).expanduser().resolve() @@ -220,9 +218,7 @@ def _path_token(path: Path) -> str: return hashlib.blake2s(str(path.resolve()).encode("utf-8"), digest_size=4).hexdigest() -def find_screen_class( - name: str, candidates: Iterable[type[Screen]] | None = None -) -> type[Screen]: +def find_screen_class(name: str, candidates: Iterable[type[Screen]] | None = None) -> type[Screen]: """The :class:`Screen` subclass called ``name`` (``Result``, ``screens.Result``). Raises :class:`PyMobileError` listing the screens that exist when there is @@ -405,11 +401,7 @@ def open(self, target: str | type[Screen] | Screen, *args: Any, **kwargs: Any) - raise PyMobileError("arguments only apply when the screen is opened by class") instance = target else: - cls = ( - find_screen_class(target, self._screens) - if isinstance(target, str) - else target - ) + cls = find_screen_class(target, self._screens) if isinstance(target, str) else target try: instance = cls(*args, **kwargs) except TypeError as error: @@ -418,7 +410,7 @@ def open(self, target: str | type[Screen] | Screen, *args: Any, **kwargs: Any) - hint=( "Pass what its constructor needs — from the command line with " "--set score=7 (repeatable, no quoting needed) or as JSON: " - '--args \'{"score": 7}\' (an object is keywords, a list is positional).' + "--args '{\"score\": 7}' (an object is keywords, a list is positional)." ), ) from error if self.app.screen is None: @@ -501,8 +493,7 @@ def tab(self, target: str | int) -> Screen: if chosen is None: described = "; ".join( ", ".join( - str(label) - for label in getattr(bar, "labels", getattr(bar, "options", ())) + str(label) for label in getattr(bar, "labels", getattr(bar, "options", ())) ) for bar in bars ) @@ -528,7 +519,7 @@ def change(self, widget_id: str, value: object) -> None: everything else is sent as the text the front end would send. """ widget = self._usable(widget_id, "change") - # П-09: mirror the guard in press() — a Button/Chip/Link that only + # Mirror the guard in press(): a Button/Chip/Link that only # supports a tap must not silently swallow `id=value` routes. accepts_value = ( hasattr(widget, "set_checked") # Switch / Checkbox @@ -575,7 +566,7 @@ def navigate(self, route: str | Sequence[str]) -> list[Screen]: else: self.change(step.target, step.value) except PyMobileError as exc: - # П-17: if the user wrote "Meniu.start" (typo in a screen + # If the user wrote "Meniu.start" (typo in a screen # name) the parser treated "Meniu.start" as a widget id # because "Meniu" is not a known screen. Surface a screen # hint in addition to whatever the widget hint says. @@ -585,9 +576,7 @@ def navigate(self, route: str | Sequence[str]) -> list[Screen]: close_screen = get_close_matches(head, names, n=1, cutoff=0.6) if close_screen and close_screen[0] != head: tail = step.text.split(".", 1)[-1] if "." in step.text else "widget" - hint = ( - (exc.hint + " ") if exc.hint else "" - ) + ( + hint = ((exc.hint + " ") if exc.hint else "") + ( f"Did you mean the screen {close_screen[0]!r}? " f"Write it as {close_screen[0]}.{tail}." ) diff --git a/pymobile/core/i18n.py b/pymobile/core/i18n.py index 8b78b4a..2bc9cc5 100644 --- a/pymobile/core/i18n.py +++ b/pymobile/core/i18n.py @@ -81,7 +81,7 @@ _log = get_logger("i18n") -#: File stems that do not look like language tags (П-14). When a user passes +#: File stems that do not look like language tags. When a user passes #: ``messages.json`` they usually meant ``uk.json``/``en.json`` and would #: otherwise end up with a catalogue registered under ``"messages"``, which #: every ``t(...)`` call silently misses. @@ -103,7 +103,7 @@ def _warn_non_language_stem(stem: str) -> None: _log.warning( "the catalogue file %r does not look like a language tag " "(got %r). Rename it to a BCP-47 code like uk.json / en.json so " - "translations.use(\"uk\") can find it, or pass language= explicitly.", + 'translations.use("uk") can find it, or pass language= explicitly.', stem + ".json", stem, ) @@ -410,6 +410,7 @@ def missing(self) -> str: @missing.setter def missing(self, policy: str) -> None: + """How a missing key is handled: ``marker``, ``key``, ``empty`` or a template.""" if not isinstance(policy, str) or not policy.strip(): raise ValueError( "missing must be 'marker', 'key', 'empty' or a template containing {key}" @@ -448,7 +449,7 @@ def load( object is kept as-is and warned about at load time. ``flatten=True`` is accepted for compatibility and means the same as the default. """ - # П-13: a Path/str passed where a mapping is expected used to surface + # A Path/str passed where a mapping is expected used to surface # as ``AttributeError: 'PosixPath' object has no attribute 'items'`` # — point the caller at ``load_file``/``load_dir`` instead. if isinstance(messages, (str, Path)): @@ -458,9 +459,7 @@ def load( "translations.load_dir(directory) for a whole directory." ) if not isinstance(messages, Mapping): - raise TypeError( - f"messages must be a mapping, got {type(messages).__name__!r}" - ) + raise TypeError(f"messages must be a mapping, got {type(messages).__name__!r}") tag = normalise_language(language) if not tag: raise ValueError("language must not be empty") @@ -485,9 +484,7 @@ def _note_nested(self, tag: str, nested: list[str], flattened: Mapping[str, Any] self._noted_nested.add(tag) shown = ", ".join(repr(name) for name in nested[:3]) more = f" (+{len(nested) - 3} more)" if len(nested) > 3 else "" - example = next( - (key for key in flattened if "." in key), "" - ) + example = next((key for key in flattened if "." in key), "") example_note = f" (for example {example!r})" if example else "" _log.debug( "catalogue %r stores nested objects under %s%s; keys are flat, so the " @@ -539,15 +536,12 @@ def load_dict( reading, like :meth:`load`. """ if not isinstance(catalogues, Mapping): - raise TypeError( - f"catalogues must be a mapping, got {type(catalogues).__name__!r}" - ) + raise TypeError(f"catalogues must be a mapping, got {type(catalogues).__name__!r}") loaded: list[str] = [] for lang, messages in catalogues.items(): if not isinstance(messages, Mapping): raise TypeError( - f"messages for {lang!r} must be mapping, " - f"got {type(messages).__name__!r}" + f"messages for {lang!r} must be mapping, got {type(messages).__name__!r}" ) self.load(messages, language=lang, flatten=flatten) loaded.append(normalise_language(lang)) @@ -565,13 +559,13 @@ def load_file( """ file = Path(path) tag = normalise_language(language or file.stem) - # П-14: a file named ``messages.json`` / ``strings.json`` / ``i18n.json`` + # A file named ``messages.json`` / ``strings.json`` / ``i18n.json`` # is a common Windows/mobile convention that does NOT look like a # language tag — silently registering it under ``"messages"`` makes # every ``t(...)`` miss. Warn once per stem instead. _warn_non_language_stem(file.stem) try: - # П-18: ``utf-8-sig`` transparently strips a UTF-8 BOM, which + # ``utf-8-sig`` transparently strips a UTF-8 BOM, which # Notepad and other Windows editors prepend; without this the # JSON parser raised ``ValueError: Unexpected UTF-8 BOM``. data = json.loads(file.read_text(encoding="utf-8-sig")) diff --git a/pymobile/core/jobs.py b/pymobile/core/jobs.py index eb8b6c0..0a6a2a5 100644 --- a/pymobile/core/jobs.py +++ b/pymobile/core/jobs.py @@ -19,6 +19,7 @@ from __future__ import annotations +import queue import threading import time import uuid @@ -37,6 +38,85 @@ def job_id() -> str: return uuid.uuid4().hex[:12] +#: Threads kept alive for waiting work. One thread per job does not scale: 500 +#: queued jobs meant 500 threads, each with its own 8 MB stack reservation. +DEFAULT_MAX_WORKERS = 8 + + +def _worker_count(requested: int | None) -> int: + """How many worker threads a manager may run at once.""" + if requested is None: + try: + import os + + return max(2, min(32, (os.cpu_count() or 2) * 2)) + except Exception: # pragma: no cover - platform without cpu_count + return DEFAULT_MAX_WORKERS + if isinstance(requested, bool) or not isinstance(requested, int): + raise TypeError("max_workers must be an int or None") + if requested < 1: + raise ValueError("max_workers must be >= 1") + return requested + + +class _WorkerPool: + """A fixed set of daemon threads that drain a queue. + + Used for one-shot jobs (``enqueue``). Repeating jobs (``every``) keep their + own thread on purpose: their loop *is* the job, and parking one of eight + workers in ``stop.wait(interval)`` would starve the queue. + """ + + def __init__(self, size: int) -> None: + self._queue: queue.Queue[tuple[Callable[[], None], threading.Event] | None] = queue.Queue() + self._lock = threading.Lock() + self._threads: list[threading.Thread] = [] + self._size = size + self._closed = False + for index in range(size): + thread = threading.Thread( + target=self._loop, name=f"pymobile-worker-{index}", daemon=True + ) + thread.start() + self._threads.append(thread) + + def submit(self, task: Callable[[], None]) -> None: + """Queue ``task`` for a worker thread, refusing work after shutdown.""" + with self._lock: + if self._closed: + raise RuntimeError("the worker pool has been shut down") + self._queue.put((task, threading.Event())) + + def _loop(self) -> None: + while True: + item = self._queue.get() + if item is None: + return + task, started = item + started.set() + try: + task() + except BaseException: # pragma: no cover - JobHandle already catches + _log.exception("a job worker raised") + finally: + self._queue.task_done() + + def shutdown(self, wait: bool = False) -> None: + """Stop accepting work and wake every worker so it can exit.""" + with self._lock: + if self._closed: + return + self._closed = True + for _ in self._threads: + self._queue.put(None) + if wait: + for thread in self._threads: + thread.join(timeout=5) + + def __len__(self) -> int: + return len(self._threads) + + class JobHandle: """A handle to an enqueued background job. @@ -290,16 +370,28 @@ class JobManager: :meth:`App.stop` integration). """ - __slots__ = ("_jobs", "_lock", "_alive", "_deliver") + __slots__ = ("_jobs", "_lock", "_alive", "_deliver", "_pool", "_pool_size") - def __init__(self, *, deliver: Callable[[Callable[[], None]], None] | None = None) -> None: + def __init__( + self, + *, + deliver: Callable[[Callable[[], None]], None] | None = None, + max_workers: int | None = None, + ) -> None: """``deliver(callback)`` runs ``then()`` callbacks — :class:`App` passes one that runs them on the UI side; by default they run on the - worker thread.""" + worker thread. + + ``max_workers`` bounds how many one-shot jobs run at once (default: + twice the CPU count); extra jobs wait in a queue instead of each + starting a thread. + """ self._deliver = deliver self._jobs: dict[str, JobHandle] = {} self._lock = threading.Lock() self._alive = True + self._pool_size = _worker_count(max_workers) + self._pool = _WorkerPool(self._pool_size) @property def active(self) -> list[JobHandle]: @@ -354,7 +446,11 @@ def run() -> None: callback_guard=callback_guard, ) self._track(handle) - threading.Thread(target=run, name=f"pymobile-job-{handle_id}", daemon=True).start() + try: + self._pool.submit(run) + except RuntimeError: + handle._finish_cancelled() + raise return handle def every( @@ -432,7 +528,18 @@ def cancel_all(self) -> None: for handle in handles: handle.cancel() - def shutdown(self) -> None: - """Stop accepting new jobs and cancel all pending ones.""" + def shutdown(self, *, wait: bool = False) -> None: + """Stop accepting new jobs, cancel pending ones and close the pool.""" self._alive = False self.cancel_all() + self._pool.shutdown(wait=wait) + + @property + def max_workers(self) -> int: + """How many one-shot jobs this manager runs at once.""" + return self._pool_size + + @property + def workers(self) -> int: + """How many worker threads exist (a fixed number, not per job).""" + return len(self._pool) diff --git a/pymobile/core/net/cache.py b/pymobile/core/net/cache.py index 295dfde..0329f7e 100644 --- a/pymobile/core/net/cache.py +++ b/pymobile/core/net/cache.py @@ -195,8 +195,8 @@ def __contains__(self, url: object) -> bool: return isinstance(url, str) and self.get(url) is not None def __len__(self) -> int: - # Storage exposes keys() but deliberately is not a Mapping/iterable. + # Storage exposes keys() but deliberately is not a Mapping/iterable, + # so the loop stays a plain call rather than ``for key in storage``. with self._lock: - return sum( - 1 for key in self._storage.keys() if key.startswith(self._prefix) # noqa: SIM118 - ) + keys = self._storage.keys() + return len([key for key in keys if key.startswith(self._prefix)]) diff --git a/pymobile/core/net/http.py b/pymobile/core/net/http.py index e06a794..7d16a3c 100644 --- a/pymobile/core/net/http.py +++ b/pymobile/core/net/http.py @@ -9,17 +9,22 @@ from __future__ import annotations import codecs +import contextlib import functools import hashlib import http.client import json as jsonlib +import queue +import secrets import threading import time import urllib.error import urllib.parse import urllib.request -from collections.abc import Callable, Mapping +import zlib +from collections.abc import Callable, Iterator, Mapping from dataclasses import dataclass, field +from pathlib import Path from types import MappingProxyType from typing import TYPE_CHECKING, Any, ClassVar @@ -31,12 +36,22 @@ if TYPE_CHECKING: # pragma: no cover - typing only; `ssl` is imported lazily import ssl -__all__ = ["HttpClient", "HttpSecurityPolicy", "Response", "HttpFuture", "DEFAULT_TIMEOUT"] +__all__ = [ + "HttpClient", + "HttpSecurityPolicy", + "Response", + "HttpFuture", + "DEFAULT_TIMEOUT", + "redact_url", +] _log = get_logger("http") DEFAULT_TIMEOUT = 15.0 _RETRY_STATUSES = frozenset({408, 425, 429, 500, 502, 503, 504}) +_REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308}) +#: Methods a 301/302/303 turn into a GET, as browsers do; 307/308 keep them. +_SEE_OTHER_STATUSES = frozenset({301, 302, 303}) Params = Mapping[str, str | int | float | bool | None] @@ -101,6 +116,7 @@ def credential_header_names(self) -> frozenset[str]: return _DEFAULT_CREDENTIAL_HEADERS | self.credential_headers def validate(self, url: str) -> None: + """Raise when ``url`` breaks the policy: scheme, host and redirect rules.""" parsed = urllib.parse.urlparse(url) host = (parsed.hostname or "").casefold() if self.require_https and parsed.scheme != "https": @@ -137,15 +153,349 @@ def validate(self, url: str) -> None: ) +#: Request bodies at least this large are worth compressing when asked to. +COMPRESS_THRESHOLD = 1024 + +FileValue = "bytes | str | Path | tuple[str, Any] | tuple[str, Any, str]" + + +def _read_file_value(name: str, value: Any) -> tuple[str, bytes, str]: + """Normalise one ``files=`` entry into ``(filename, content, content_type)``.""" + if isinstance(value, (bytes, bytearray)): + return name, bytes(value), "application/octet-stream" + if isinstance(value, tuple): + if len(value) == 2: + filename, content = value + content_type = "application/octet-stream" + elif len(value) == 3: + filename, content, content_type = value + else: + raise ValueError( + f"files[{name!r}] must be (filename, content) or (filename, content, content_type)" + ) + return str(filename), _coerce_upload(content), str(content_type) + # A path is read here rather than by the caller: streaming a file upload + # from disk is the common case, and reading it lazily would mean holding + # the request open across a retry. + path = Path(value) + return path.name, path.read_bytes(), "application/octet-stream" + + +def _coerce_upload(content: Any) -> bytes: + if isinstance(content, (bytes, bytearray)): + return bytes(content) + if isinstance(content, str): + return content.encode("utf-8") + if isinstance(content, Path): + return content.read_bytes() + raise TypeError(f"file content must be bytes, str or a Path, got {type(content).__name__!r}") + + +def _encode_multipart( + fields: Mapping[str, Any] | None, files: Mapping[str, Any] +) -> tuple[bytes, str]: + """Build a ``multipart/form-data`` body. + + Uploads used to mean hand-rolling the boundary, the ``Content-Length`` and + the CRLF rules; a missing CRLF between parts is the classic bug, and it + fails silently on the server side. This does it once, correctly. + """ + boundary = f"----PyMobileBoundary{secrets.token_hex(16)}" + lines: list[bytes] = [] + for name, value in (fields or {}).items(): + lines.append(f"--{boundary}".encode()) + lines.append(f'Content-Disposition: form-data; name="{name}"'.encode()) + lines.append(b"") + lines.append(str(value).encode("utf-8")) + for name, entry in files.items(): + filename, content, content_type = _read_file_value(name, entry) + lines.append(f"--{boundary}".encode()) + disposition = f'Content-Disposition: form-data; name="{name}"' + if filename: + disposition += f'; filename="{filename}"' + lines.append(disposition.encode()) + lines.append(f"Content-Type: {content_type}".encode()) + lines.append(b"") + lines.append(content) + lines.append(f"--{boundary}--".encode()) + lines.append(b"") + return b"\r\n".join(lines), f"multipart/form-data; boundary={boundary}" + + +#: Query parameters whose value is a credential, masked before a URL reaches +#: the log. A debug log that carries ``?access_token=…`` ends up in logcat, +#: in bug reports and in a support ticket. +SECRET_QUERY_PARAMS = frozenset( + { + "access_token", + "api_key", + "apikey", + "auth", + "code", + "id_token", + "key", + "password", + "refresh_token", + "secret", + "session", + "sig", + "signature", + "token", + } +) + + +def redact_url(url: str) -> str: + """``url`` with credential-looking query values replaced by ``***``. + + Kept as a small function of its own so a caller can log the same + redaction, and so the behaviour is obvious in a test. + """ + try: + parts = urllib.parse.urlsplit(url) + except ValueError: # pragma: no cover - impossible for a str we built + return url + if not parts.query: + return url + pairs = urllib.parse.parse_qsl(parts.query, keep_blank_values=True) + if not any(name.casefold() in SECRET_QUERY_PARAMS for name, _ in pairs): + return url + masked = [ + (name, "***" if name.casefold() in SECRET_QUERY_PARAMS else value) for name, value in pairs + ] + # ``safe="*"`` keeps the mask readable in the log instead of %2A%2A%2A. + query = urllib.parse.urlencode(masked, safe="*") + return urllib.parse.urlunsplit((parts.scheme, parts.netloc, parts.path, query, parts.fragment)) + + +def _header_value(headers: Mapping[str, str], name: str) -> str: + """Case-insensitive header lookup; ``""`` when the header is absent.""" + wanted = name.casefold() + for key, value in headers.items(): + if key.casefold() == wanted: + return value + return "" + + def _normalise_header_names(names: frozenset[str] | tuple[str, ...] | list[str]) -> frozenset[str]: """Lower-case header names, rejecting a bare string ("x-api-key" is iterable).""" if isinstance(names, str): - raise TypeError( - "credential_headers must be a collection of header names, not a str" - ) + raise TypeError("credential_headers must be a collection of header names, not a str") return frozenset(str(name).strip().casefold() for name in names if str(name).strip()) +#: Encodings the client understands, in the order it advertises them. A server +#: that honours ``Accept-Encoding`` gets a smaller body on the wire; one that +#: compresses without being asked is still decoded (see :func:`_decompress`). +ACCEPT_ENCODING = "gzip, deflate" + +#: Enough for a phone: a pool entry is one idle socket, and these are cheap. +MAX_IDLE_CONNECTIONS = 4 +#: Servers close idle sockets after ~5-60 s; dropping ours sooner avoids +#: writing a request into a socket the peer has already shut down. +IDLE_CONNECTION_TIMEOUT = 20.0 + + +class _ConnectionPool: + """Idle keep-alive connections, keyed by scheme/host/port. + + Every request used to open a fresh TCP connection (and, over HTTPS, a fresh + TLS handshake). Reusing the socket turn is what makes a page of twenty API + calls bearable on a phone. ``http.client`` connections are not thread safe, + so a checked-out connection belongs to one caller until it is returned; + connections handed back after an error are dropped rather than reused. + """ + + def __init__( + self, + *, + max_idle: int = MAX_IDLE_CONNECTIONS, + idle_timeout: float = IDLE_CONNECTION_TIMEOUT, + ) -> None: + self._idle: dict[ + tuple[str, str, int | None], list[tuple[http.client.HTTPConnection, float]] + ] = {} + self._lock = threading.Lock() + self._max_idle = max_idle + self._idle_timeout = idle_timeout + + def acquire( + self, scheme: str, host: str, port: int | None, timeout: float + ) -> http.client.HTTPConnection: + """A reusable connection for the host, reusing an idle one when there is any.""" + key = (scheme, host, port) + with self._lock: + entries = self._idle.get(key, []) + while entries: + connection, returned_at = entries.pop() + if time.monotonic() - returned_at <= self._idle_timeout: + connection.timeout = timeout + if connection.sock is not None: + return connection + connection.close() + return self._new(scheme, host, port, timeout) + + @staticmethod + def _new( + scheme: str, host: str, port: int | None, timeout: float + ) -> http.client.HTTPConnection: + if scheme == "https": + return http.client.HTTPSConnection(host, port, timeout=timeout, context=_ssl_context()) + return http.client.HTTPConnection(host, port, timeout=timeout) + + def release( + self, scheme: str, host: str, port: int | None, connection: http.client.HTTPConnection + ) -> None: + """Return a healthy connection; anything else is closed instead.""" + key = (scheme, host, port) + with self._lock: + entries = self._idle.setdefault(key, []) + if len(entries) >= self._max_idle: + connection.close() + return + entries.append((connection, time.monotonic())) + + def discard(self, connection: http.client.HTTPConnection) -> None: + """Close and forget a connection that cannot be reused.""" + with self._lock: + for entries in self._idle.values(): + entries[:] = [item for item in entries if item[0] is not connection] + with contextlib.suppress(Exception): + connection.close() + + def close(self) -> None: + """Close every idle socket (called by ``App.stop`` and by tests).""" + with self._lock: + entries = [item for items in self._idle.values() for item in items] + self._idle.clear() + for connection, _ in entries: + with contextlib.suppress(Exception): + connection.close() + + def __len__(self) -> int: + with self._lock: + return sum(len(items) for items in self._idle.values()) + + +def _http_worker_count(max_workers: int | None) -> int: + """How many worker threads serve ``*_async`` requests.""" + if max_workers is None: + import os + + return max(2, min(32, (os.cpu_count() or 2) * 2)) + if isinstance(max_workers, bool) or not isinstance(max_workers, int): + raise TypeError("max_workers must be an int or None") + if max_workers < 1: + raise ValueError("max_workers must be >= 1") + return max_workers + + +class _RequestPool: + """Fixed daemon workers for ``get_async`` and friends. + + One thread per request does not scale: a screen that fires twenty async + loads, or a retry storm, used to create a thread each. A queued request + waits here instead, and ``close()`` drains the queue. + """ + + def __init__(self, size: int) -> None: + self._queue: queue.Queue[Callable[[], None] | None] = queue.Queue() + self._threads: list[threading.Thread] = [] + self._closed = False + self._lock = threading.Lock() + self._size = size + # Threads are started with the first async request, not with the client: + # every ``HttpClient()`` used to spawn a worker pool on creation, and so + # did every ``App`` and every test that built one, for requests a + # synchronous app never makes. + self._spawned = False + + def _ensure_started(self) -> None: + if self._spawned: + return + with self._lock: + if self._spawned: + return + for index in range(self._size): + thread = threading.Thread( + target=self._loop, name=f"pymobile-http-worker-{index}", daemon=True + ) + thread.start() + self._threads.append(thread) + self._spawned = True + + def submit(self, task: Callable[[], None]) -> None: + """Run ``task`` on one of the request threads, starting them on first use.""" + if self._closed: + raise NetworkError("the HTTP client has been closed") + self._ensure_started() + self._queue.put(task) + + def _loop(self) -> None: + while True: + task = self._queue.get() + if task is None: + return + try: + task() + except BaseException: # pragma: no cover - futures capture their own errors + _log.exception("an HTTP worker raised") + finally: + self._queue.task_done() + + def shutdown(self, wait: bool = False) -> None: + """Stop the request threads once their current task is done.""" + with self._lock: + if self._closed: + return + self._closed = True + for _ in self._threads: + self._queue.put(None) + if wait: + for thread in self._threads: + thread.join(timeout=5) + + def __len__(self) -> int: + return len(self._threads) + + +def _gzip_bytes(body: bytes) -> bytes: + """gzip a request body (``zlib.compress`` cannot ask for the gzip format).""" + import gzip + + return gzip.compress(body, 6) + + +def _decompress(body: bytes, encoding: str) -> bytes: + """Undo ``Content-Encoding`` on a body that was compressed anyway. + + The client advertises ``Accept-Encoding: gzip, deflate`` and also sends + ``Accept-Encoding: identity`` when the caller sets the header by hand. A + server that compresses regardless used to hand the caller gzip bytes as + ``response.text``; this decodes them, and falls back to the raw body when + the stream is truncated or otherwise unreadable (a partial body beats an + exception the app cannot act on). + """ + name = encoding.strip().casefold() + if not name or name == "identity": + return body + if not body: + return body + try: + if name in ("gzip", "x-gzip"): + return zlib.decompress(body, 16 + zlib.MAX_WBITS) + if name == "deflate": + try: + return zlib.decompress(body) + except zlib.error: + return zlib.decompress(body, -zlib.MAX_WBITS) + except zlib.error as exc: + _log.warning("could not decode a %s response body (%s); returning it as-is", name, exc) + return body + _log.debug("unknown Content-Encoding %r; returning the body as-is", encoding) + return body + + def _origin(url: str) -> tuple[str, str, int | None]: parsed = urllib.parse.urlsplit(url) return (parsed.scheme, (parsed.hostname or "").casefold(), parsed.port) @@ -167,6 +517,7 @@ def redirect_request( # type: ignore[override] headers: Any, newurl: str, ) -> urllib.request.Request | None: + """Follow a redirect only when the policy allows the destination.""" scheme = urllib.parse.urlsplit(newurl).scheme if scheme not in ("http", "https"): raise NetworkError(f"Redirect to unsupported URL scheme blocked: {newurl!r}") @@ -213,6 +564,12 @@ class Response: elapsed: float = 0.0 encoding: str = "utf-8" from_cache: bool = False + #: ``True`` when the body was **not** read: use ``iter_content()`` and call + #: ``close()`` (or use the response as a context manager) when done. + stream: bool = False + #: The reader behind a streaming response; other responses leave it None. + _reader: Callable[[int], bytes] | None = field(default=None, repr=False, compare=False) + _closer: Callable[[], None] | None = field(default=None, repr=False, compare=False) def __post_init__(self) -> None: # A server may send any junk in ``charset=…``. Decoding with a codec @@ -225,7 +582,8 @@ def __post_init__(self) -> None: except (LookupError, TypeError): _log.warning( "unknown charset %r for %s; decoding the body as utf-8", - self.encoding, self.url, + self.encoding, + self.url, ) object.__setattr__(self, "encoding", "utf-8") @@ -255,6 +613,42 @@ def json(self) -> Any: hint=f"First bytes of the body: {preview!r}", ) from exc + def iter_content(self, chunk_size: int = 64 * 1024) -> Iterator[bytes]: + """Yield the body in chunks. + + For ``stream=True`` responses the bytes are read from the socket as + they arrive and the connection is held until the iterator is done, so + a 30 MB download no longer sits in memory three times over. A response + that was fully read (the default) simply yields its content in slices. + """ + if chunk_size <= 0: + raise ValueError("chunk_size must be positive") + if self._reader is None: + for start in range(0, len(self.content), chunk_size): + yield self.content[start : start + chunk_size] + return + try: + while True: + chunk = self._reader(chunk_size) + if not chunk: + return + yield chunk + finally: + self.close() + + def close(self) -> None: + """Release the connection behind a streaming response (idempotent).""" + closer = self._closer + object.__setattr__(self, "_closer", None) + if closer is not None: + closer() + + def __enter__(self) -> Response: + return self + + def __exit__(self, *exc_info: object) -> None: + self.close() + def raise_for_status(self) -> Response: """Return ``self``, or raise :class:`NetworkError` for 4xx/5xx.""" if not self.ok: @@ -445,11 +839,11 @@ def _complete(self, result: Response | None, error: BaseException | None) -> Non #: Per-request options accepted by the verbs (they are forwarded to ``request``). -_REQUEST_OPTIONS = frozenset({"json", "data", "headers", "timeout", "retry_safe"}) -#: Options that exist, but on ``HttpClient(...)`` instead of on each request. -_CLIENT_OPTIONS = frozenset( - {"retries", "backoff", "cache", "security", "user_agent", "base_url"} +_REQUEST_OPTIONS = frozenset( + {"json", "data", "files", "compress", "headers", "timeout", "retry_safe", "stream"} ) +#: Options that exist, but on ``HttpClient(...)`` instead of on each request. +_CLIENT_OPTIONS = frozenset({"retries", "backoff", "cache", "security", "user_agent", "base_url"}) def _check_request_options(verb: str, kwargs: Mapping[str, Any]) -> None: @@ -487,6 +881,14 @@ class HttpClient: timeout: float = DEFAULT_TIMEOUT retries: int = 0 backoff: float = 0.5 + #: A deadline for the whole call -- every retry and every backoff sleep + #: included. ``timeout`` bounds one attempt: with ``timeout=2, retries=3`` + #: a single ``get()`` used to take 8.4 s. ``None`` keeps the old behaviour. + timeout_budget: float | None = None + #: Redirect hops followed before the response is returned as-is. + max_redirects: int = 10 + #: Worker threads for the ``*_async`` verbs (default: twice the CPU count). + max_workers: int | None = None user_agent: str = f"PyMobile/{__import__('pymobile').__version__}" cache: HttpCache | None = field(default=None, repr=False) security: HttpSecurityPolicy = field(default_factory=HttpSecurityPolicy) @@ -495,9 +897,17 @@ class HttpClient: deliver: Callable[[Callable[[], None]], None] | None = field( default=None, repr=False, compare=False ) + #: Idle keep-alive sockets, one per scheme/host/port (see _ConnectionPool). + _pool: _ConnectionPool = field( + default_factory=lambda: _ConnectionPool(), repr=False, compare=False, init=False + ) + _budget_started: float = field(default=0.0, repr=False, compare=False, init=False) + _workers: _RequestPool = field( + default_factory=lambda: _RequestPool(32), repr=False, compare=False, init=False + ) def __post_init__(self) -> None: - # Validation for common mistakes (BUG-27, BUG-28) + new checks + # Validation for the common mistakes + the options that used to slip through if not isinstance(self.timeout, (int, float)): raise TypeError(f"timeout must be a number, got {type(self.timeout).__name__!r}") if self.timeout <= 0: @@ -515,18 +925,30 @@ def __post_init__(self) -> None: f"retries must be >= 0, got {self.retries}; " "pass 0 for no retries, 2 for two retries" ) + if self.timeout_budget is not None: + if not isinstance(self.timeout_budget, (int, float)) or isinstance( + self.timeout_budget, bool + ): + raise TypeError( + f"timeout_budget must be a number or None, got " + f"{type(self.timeout_budget).__name__!r}" + ) + if self.timeout_budget <= 0: + raise ValueError(f"timeout_budget must be positive, got {self.timeout_budget}") + if isinstance(self.max_redirects, bool) or not isinstance(self.max_redirects, int): + raise TypeError("max_redirects must be an int") + if self.max_redirects < 0: + raise ValueError("max_redirects must be >= 0") if not isinstance(self.backoff, (int, float)): raise TypeError(f"backoff must be a number, got {type(self.backoff).__name__!r}") if self.backoff < 0: raise ValueError(f"backoff must be >= 0, got {self.backoff}") if self.base_url is not None and not isinstance(self.base_url, str): - raise TypeError( - f"base_url must be a string, got {type(self.base_url).__name__!r}" - ) + raise TypeError(f"base_url must be a string, got {type(self.base_url).__name__!r}") if isinstance(self.base_url, str) and self.base_url.strip() == "" and self.base_url != "": raise ValueError( "base_url must not be only whitespace; " - "pass \"\" for no base URL or a URL like https://api.example.com" + 'pass "" for no base URL or a URL like https://api.example.com' ) # Docs historically showed ``HttpClient(cache=app.storage)``. A # ``Storage`` is adopted **as the same instance** (see HttpCache): the @@ -535,6 +957,7 @@ def __post_init__(self) -> None: # other's keys ("settings change loses the cache, cache write loses # the settings"). Anything else with a ``path`` is a location, not an # owner, and gets its own file-backed cache. + self._workers = _RequestPool(_http_worker_count(self.max_workers)) cache = self.cache if cache is None or isinstance(cache, HttpCache): return @@ -595,7 +1018,7 @@ def run() -> None: else: future._complete(result, None) - threading.Thread(target=run, name=f"pymobile-http-{method}", daemon=True).start() + self._workers.submit(run) return future # -- cached GET -------------------------------------------------------- @@ -659,11 +1082,15 @@ def request( params: Params | None = None, json: Any = None, data: bytes | str | Mapping[str, Any] | None = None, + files: Mapping[str, Any] | None = None, + compress: bool = False, headers: Mapping[str, str] | None = None, timeout: float | None = None, retry_safe: bool | None = None, + stream: bool = False, ) -> Response: - """Send a request and return a :class:`Response`. + ( + """Send a request and return a :class:`Response`. Raises :class:`~pymobile.errors.NetworkError` on transport failures; HTTP error statuses are returned, not raised (use @@ -671,13 +1098,34 @@ def request( ``retry_safe=True`` permits retries for non-idempotent verbs; the default retries only GET/HEAD/OPTIONS. + + ``stream=True`` returns as soon as the headers are in, with the body + left on the socket: read it with ``response.iter_content()``, which + also releases the connection. """ + "" + ) if json is not None and data is not None: raise ValueError("pass either json= or data=, not both") + if files is not None and json is not None: + raise ValueError("pass files= with data=, not with json=") final_url = self._build_url(url, params) - body, content_type = self._encode_body(json, data) + body: bytes | None + content_type: str | None + if files is not None: + body, content_type = _encode_multipart( + data if isinstance(data, Mapping) else None, files + ) + else: + body, content_type = self._encode_body(json, data) request_headers = self._merge_headers(headers, content_type) + if compress and body is not None and len(body) >= COMPRESS_THRESHOLD: + # gzip the *request*: a 30 MB JSON payload on a phone uplink is + # mostly repetition. Skipped for tiny bodies, where the header and + # the gzip framing cost more than they save. + body = _gzip_bytes(body) + request_headers["Content-Encoding"] = "gzip" attempts = max(0, self.retries) + 1 # Never replay a non-idempotent verb implicitly: a retried POST could # perform its side effect twice. Callers opt in per request. @@ -690,17 +1138,20 @@ def request( if not allowed: attempts = 1 last_error: Exception | None = None + self._budget_started = time.monotonic() for attempt in range(1, attempts + 1): started = time.monotonic() try: - response = self._send(method.upper(), final_url, body, request_headers, timeout) + response = self._send( + method.upper(), final_url, body, request_headers, timeout, stream=stream + ) except NetworkError as exc: last_error = exc if attempt >= attempts: raise self._sleep(attempt) - _log.debug("retrying %s %s (%s)", method, final_url, exc) + _log.debug("retrying %s %s (%s)", method, redact_url(final_url), exc) continue elapsed = time.monotonic() - started @@ -711,12 +1162,26 @@ def request( url=response.url, elapsed=elapsed, encoding=response.encoding, + stream=response.stream, + _reader=response._reader, + _closer=response._closer, ) if response.status in _RETRY_STATUSES and attempt < attempts: self._sleep(attempt) - _log.debug("retrying %s %s after HTTP %s", method, final_url, response.status) + _log.debug( + "retrying %s %s after HTTP %s", + method, + redact_url(final_url), + response.status, + ) continue - _log.debug("%s %s -> %s in %.0f ms", method, final_url, response.status, elapsed * 1000) + _log.debug( + "%s %s -> %s in %.0f ms", + method, + redact_url(final_url), + response.status, + elapsed * 1000, + ) return response raise NetworkError(str(last_error) if last_error else "Request failed") @@ -728,47 +1193,238 @@ def _send( body: bytes | None, headers: dict[str, str], timeout: float | None, + *, + stream: bool = False, ) -> Response: - """One transport attempt.""" - request = urllib.request.Request(url, data=body, method=method) - for key, value in headers.items(): - request.add_header(key, value) - handlers: list[Any] = [_PolicyRedirectHandler(self.security)] - if urllib.parse.urlsplit(url).scheme == "https": - # ``ssl`` is imported here and nowhere else at module level: a - # build packaged with --no-ssl ships no ssl module at all, and an - # app that never speaks HTTPS must still start offline instead of - # dying on an import error inside pymobile.core.net.http. - handlers.insert(0, urllib.request.HTTPSHandler(context=_ssl_context())) - opener = urllib.request.build_opener(*handlers) + """One transport attempt, on a pooled keep-alive connection. + + ``timeout`` is a **deadline for the whole attempt**, not for each read: + a server that dribbles one byte a second used to keep a request alive + far past the timeout the caller asked for. It is enforced on the + socket and, for the body, by checking the elapsed time while reading. + """ + if self.timeout_budget is not None: + remaining_budget = self.timeout_budget - (time.monotonic() - self._budget_started) + if remaining_budget <= 0: + raise NetworkError( + f"Request to {url} ran past the {self.timeout_budget:g}s budget " + f"({self.retries} retr{'y' if self.retries == 1 else 'ies'} included)", + hint=( + "Raise HttpClient(timeout_budget=...) or lower `retries`; " + "the budget covers retries and backoff, `timeout` covers one attempt." + ), + ) + effective = remaining_budget if timeout is None else min(timeout, remaining_budget) + else: + effective = timeout if timeout is not None else self.timeout + deadline = time.monotonic() + effective + + parsed = urllib.parse.urlsplit(url) + scheme = parsed.scheme + host = parsed.hostname or "" + port = parsed.port + target = parsed.path or "/" + if parsed.query: + target = f"{target}?{parsed.query}" + pool_key = (scheme, host, port) + connection = self._pool.acquire(scheme, host, port, effective) + request_headers = dict(headers) + request_headers.setdefault("Host", parsed.netloc) + request_headers.setdefault("Accept-Encoding", ACCEPT_ENCODING) try: - with opener.open( - request, - timeout=timeout if timeout is not None else self.timeout, - ) as raw: - return self._to_response(raw.geturl(), raw.status, dict(raw.headers), raw.read()) - except urllib.error.HTTPError as exc: # 4xx/5xx are valid responses here - payload = exc.read() if hasattr(exc, "read") else b"" - # The error describes the *final* request in a redirect chain: - # reporting the URL we started from made every - # 302 → 404 look like it came from the original path. - final_url = exc.geturl() if hasattr(exc, "geturl") else "" - return self._to_response( - final_url or url, int(exc.code), dict(exc.headers or {}), payload + connection.request(method, target, body=body, headers=request_headers) + raw = connection.getresponse() + status = raw.status + response_headers = {key: value for key, value in raw.getheaders()} + # A redirect we are about to follow: its body is not part of the + # answer, and an unframed one (``HTTP/1.1`` without + # ``Content-Length``) would block the read until the server closes. + # Dropping the socket is what lets the hop happen at all. + following = ( + status in _REDIRECT_STATUSES + and bool(_header_value(response_headers, "location")) + and self.max_redirects > 0 ) - except urllib.error.URLError as exc: + if following: + payload = b"" + # Close the response before the socket: the file object holds + # its own reference, and a socket closed while the file is open + # leaves the server waiting on a connection we think is gone. + raw.close() + self._pool.discard(connection) + elif stream: + # Leave the body on the socket; iter_content() reads it and + # hands the connection back. Nothing may return early here. + payload = b"" + reader = raw.read + closer = functools.partial(self._release_stream, pool_key, connection, raw) + else: + payload = raw.read() + if time.monotonic() > deadline: + raise TimeoutError(f"body not received within {effective:g}s") + if raw.will_close: + self._pool.discard(connection) + else: + self._pool.release(*pool_key, connection) + final_url = url + except TimeoutError as exc: + self._pool.discard(connection) raise NetworkError( - f"Could not reach {url}: {exc.reason}", - hint="Check connectivity and the INTERNET permission in your project config.", + f"Request to {url} timed out after {effective:g}s", + hint=( + "Raise HttpClient(timeout=...) for slow servers; " + "the timeout covers the whole request." + ), ) from exc - except TimeoutError as exc: - raise NetworkError(f"Request to {url} timed out") from exc + except http.client.IncompleteRead as exc: + # The socket worked and the body stopped early: reporting "could + # not reach" there was misleading, and leaking IncompleteRead made + # the failure impossible for an app to handle. + self._pool.discard(connection) + raise NetworkError(f"Could not read {url}: {exc}") from exc except (http.client.HTTPException, OSError) as exc: + self._pool.discard(connection) raise NetworkError( - f"Could not read {url}: {exc}", + f"Could not reach {url}: {exc}", hint="Check connectivity and the INTERNET permission in your project config.", ) from exc + redirects = 0 + while ( + status in _REDIRECT_STATUSES + and (location := _header_value(response_headers, "location")) + and redirects < self.max_redirects + ): + final_url = urllib.parse.urljoin(final_url, location) + self._check_redirect(final_url, url) + redirects += 1 + if status in _SEE_OTHER_STATUSES: + # A browser turns a 301/302/303 into a GET and drops the body; + # replaying a POST to the new location would post twice. + method, body = "GET", None + request_headers.pop("Content-Type", None) + response_headers, status, payload = self._follow( + method, + final_url, + body, + request_headers, + deadline, + effective, + hop=redirects, + max_redirects=self.max_redirects, + ) + + lowered = {key.lower(): value for key, value in response_headers.items()} + if stream and not following: + # A compressed stream would have to be inflated chunk by chunk to be + # useful, and a truncated one is not detectable here; ask for the + # plain body instead and hand back what the socket delivered. + return Response( + status=status, + headers=lowered, + content=b"", + url=final_url, + encoding=_charset_from_headers(lowered) or "utf-8", + stream=True, + _reader=reader, + _closer=closer, + ) + encoding = _header_value(response_headers, "content-encoding") + if encoding: + payload = _decompress(payload, encoding) + # The bytes are no longer in that encoding: leaving the header in + # place would make a caller that re-serves the body wrong, and + # ``Content-Length`` no longer describes what we hold. + lowered.pop("content-encoding", None) + lowered.pop("content-length", None) + charset = _charset_from_headers(lowered) or "utf-8" + return Response( + status=status, headers=lowered, content=payload, url=final_url, encoding=charset + ) + + def _follow( + self, + method: str, + url: str, + body: bytes | None, + headers: Mapping[str, str], + deadline: float, + effective: float, + hop: int = 0, + max_redirects: int = 0, + ) -> tuple[dict[str, str], int, bytes]: + """Send one redirect hop, keeping the method and body for 307/308.""" + parsed = urllib.parse.urlsplit(url) + remaining = deadline - time.monotonic() + if remaining <= 0: + raise NetworkError(f"Request to {url} timed out after {effective:g}s") + connection = self._pool.acquire( + parsed.scheme, parsed.hostname or "", parsed.port, remaining + ) + hop_headers = dict(headers) + hop_headers["Host"] = parsed.netloc + target = parsed.path or "/" + if parsed.query: + target = f"{target}?{parsed.query}" + # No ``Connection`` header: a 302 whose body is omitted (so the socket + # stays usable) and one that closes the socket are both legal, and the + # server decides. ``will_close`` below records which one happened. + hop_headers.pop("Connection", None) + try: + connection.request(method, target, body=body, headers=hop_headers) + raw = connection.getresponse() + status = raw.status + response_headers = {key: value for key, value in raw.getheaders()} + following = ( + status in _REDIRECT_STATUSES + and bool(_header_value(response_headers, "location")) + and hop < max_redirects + ) + if following: + payload = b"" + raw.close() + self._pool.discard(connection) + return response_headers, status, payload + payload = raw.read() + except (http.client.HTTPException, OSError, TimeoutError) as exc: + self._pool.discard(connection) + raise NetworkError(f"Could not follow redirect to {url}: {exc}") from exc + if raw.will_close: + self._pool.discard(connection) + else: + self._pool.release(parsed.scheme, parsed.hostname or "", parsed.port, connection) + return response_headers, status, payload + + def _release_stream( + self, + pool_key: tuple[str, str, int | None], + connection: http.client.HTTPConnection, + raw: http.client.HTTPResponse, + ) -> None: + """Close a streamed response and return or drop its connection.""" + try: + raw.close() + finally: + self._pool.release(*pool_key, connection) + + def _check_redirect(self, target: str, source: str) -> None: + """Re-check the security policy on every hop and drop credentials cross-origin. + + Ported from the ``urllib`` redirect handler: a server (or whoever + controls it) must not be able to bounce a request to a blocked host, + downgrade it to plain HTTP, or carry its credentials to another origin. + """ + scheme = urllib.parse.urlsplit(target).scheme + if scheme not in ("http", "https"): + raise NetworkError(f"Redirect to unsupported URL scheme blocked: {target!r}") + try: + self.security.validate(target) + except NetworkError as exc: + raise NetworkError( + f"Redirect from {source} to {target} blocked: {exc}", + hint="Add the target host to HttpSecurityPolicy.allowed_hosts if it is trusted.", + ) from exc + @staticmethod def _to_response(url: str, status: int, headers: Mapping[str, str], content: bytes) -> Response: """Build a Response, honouring the charset from ``Content-Type``.""" @@ -778,6 +1434,17 @@ def _to_response(url: str, status: int, headers: Mapping[str, str], content: byt status=status, headers=normalized, content=content, url=url, encoding=encoding ) + def close(self) -> None: + """Close idle sockets and stop the async workers.""" + self._pool.close() + self._workers.shutdown() + + def __enter__(self) -> HttpClient: + return self + + def __exit__(self, *exc_info: object) -> None: + self.close() + # -- helpers ----------------------------------------------------------- def _build_url(self, url: str, params: Params | None) -> str: """Join the base URL and append the query string.""" @@ -841,9 +1508,7 @@ def _sleep(self, attempt: int) -> None: time.sleep(self.backoff * (2 ** (attempt - 1))) -def _credential_variant( - headers: Mapping[str, str], extra: frozenset[str] = frozenset() -) -> str: +def _credential_variant(headers: Mapping[str, str], extra: frozenset[str] = frozenset()) -> str: """Fingerprint of the credentials a request carries ('' when it has none). ``extra`` are the policy's additional credential header names, so the @@ -851,8 +1516,7 @@ def _credential_variant( """ names = _DEFAULT_CREDENTIAL_HEADERS | extra parts = sorted( - f"{key.lower()}:{value}" for key, value in headers.items() - if key.lower() in names + f"{key.lower()}:{value}" for key, value in headers.items() if key.lower() in names ) if not parts: return "" diff --git a/pymobile/core/plugins.py b/pymobile/core/plugins.py index a6f22bc..5de9e37 100644 --- a/pymobile/core/plugins.py +++ b/pymobile/core/plugins.py @@ -35,7 +35,7 @@ def activate(self, app): class Plugin: - """ Subclasses set ``name`` and may implement ``activate(app)`` plus optional + """Subclasses set ``name`` and may implement ``activate(app)`` plus optional ``on_app_start(app)`` / ``on_app_stop(app)`` hooks. ``activate`` runs **once per (plugin, app) pair** — for every application the plugin is activated against, including a second app created later in the same process, and diff --git a/pymobile/core/ui/__init__.py b/pymobile/core/ui/__init__.py index 253dfc0..1bc97b0 100644 --- a/pymobile/core/ui/__init__.py +++ b/pymobile/core/ui/__init__.py @@ -92,7 +92,8 @@ ) from .screen import Navigator, Screen from .snackbar import Snackbar -from .style import Align, Color, EdgeInsets, Style +from .state import Computed, Value +from .style import Align, Border, Color, EdgeInsets, Gradient, Style from .theme import Space, TextScale, Theme from .widget import Container, Widget @@ -143,7 +144,6 @@ "BarChart", "LineChart", "PieChart", - "Widget", "Container", "Label", @@ -197,6 +197,10 @@ "Color", "Align", "EdgeInsets", + "Border", + "Gradient", + "Value", + "Computed", "Theme", "WidgetCapability", "widget_types", diff --git a/pymobile/core/ui/_mockup_chrome.py b/pymobile/core/ui/_mockup_chrome.py index 16ec95e..e383edc 100644 --- a/pymobile/core/ui/_mockup_chrome.py +++ b/pymobile/core/ui/_mockup_chrome.py @@ -23,6 +23,7 @@ def _paint_load_more(self, pt: _Painter, x: float, y: float, b: _Box) -> None: pt.arc(x + b.w / 2, y + b.h / 2, 10, -90, 200, self.p["PRIMARY"], 3) def paint_chrome(self, pt: _Painter, width: float, title: str, *, back: bool = False) -> None: + """Draw the status bar and the app bar above the screen content.""" primary = self.p["PRIMARY"] status = _mix(primary, (0, 0, 0, 255), 0.2) white = _rgba(_readable_on("#{:02X}{:02X}{:02X}".format(*status[:3]))) @@ -50,6 +51,7 @@ def paint_chrome(self, pt: _Painter, width: float, title: str, *, back: bool = F def paint_dialog( self, pt: _Painter, node: dict[str, Any], screen: tuple[float, float, float, float] ) -> None: + """Draw a dialog over the dimmed screen content.""" sx, sy, sw, sh = screen props = node.get("props") or {} sheet = bool(props.get("sheet")) @@ -84,6 +86,7 @@ def paint_dialog( def paint_snackbar( self, pt: _Painter, data: dict[str, Any], screen: tuple[float, float, float, float] ) -> None: + """Draw the snackbar at the bottom of the screen.""" sx, sy, sw, sh = screen dark = self.p["dark"] bg = (0xE6, 0xE6, 0xE6, 255) if dark else (0x32, 0x32, 0x32, 255) diff --git a/pymobile/core/ui/_mockup_context.py b/pymobile/core/ui/_mockup_context.py index 8e42cab..2656ee0 100644 --- a/pymobile/core/ui/_mockup_context.py +++ b/pymobile/core/ui/_mockup_context.py @@ -27,7 +27,9 @@ def layout( fill: bool, force_h: float | None = None, axis: str = "v", - ) -> _Box | None: ... + ) -> _Box | None: + """Lay out one node: its box, or ``None`` when it takes no space.""" + ... @abstractmethod def _padding( diff --git a/pymobile/core/ui/_mockup_fonts.py b/pymobile/core/ui/_mockup_fonts.py index f89695f..bb6fa9f 100644 --- a/pymobile/core/ui/_mockup_fonts.py +++ b/pymobile/core/ui/_mockup_fonts.py @@ -43,6 +43,33 @@ ("C:/Windows/Fonts/arial.ttf", "C:/Windows/Fonts/arialbd.ttf"), ) +#: Faces a ``Style(font_family="serif" | "monospace")`` resolves to, in order. +_SERIF_CANDIDATES = ( + "/usr/share/fonts/truetype/dejavu/DejaVuSerif.ttf", + "/usr/share/fonts/truetype/liberation/LiberationSerif-Regular.ttf", + "/usr/share/fonts/truetype/noto/NotoSerif-Regular.ttf", + "/System/Library/Fonts/Supplemental/Times New Roman.ttf", + "C:/Windows/Fonts/times.ttf", +) + +_MONO_CANDIDATES = ( + "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf", + "/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf", + "/usr/share/fonts/truetype/noto/NotoMono-Regular.ttf", + "/System/Library/Fonts/Menlo.ttc", + "C:/Windows/Fonts/consola.ttf", +) + +#: Where a named family is looked for (file names without spaces are tried too). +_FONT_DIRECTORIES = ( + "/usr/share/fonts/truetype", + "/usr/share/fonts/TTF", + "/usr/share/fonts", + "/Library/Fonts", + "/System/Library/Fonts", + "C:/Windows/Fonts", +) + #: Faces consulted glyph by glyph for what the main face lacks (CJK, symbols). _FALLBACK_CANDIDATES = ( *_SYMBOL_CANDIDATES, @@ -78,6 +105,7 @@ def _pick_sans() -> tuple[str, str]: return "", "" def font(self, path: str, size: float) -> Any: + """The font for ``size``, style flags and family, created once and cached.""" key = (path, size) font = self._cache.get(key) if font is None: @@ -101,17 +129,58 @@ def _covers(self, path: str, font: Any, ch: str) -> bool: known = self._glyph[key] = _has_glyph(font, ch) return known - def runs(self, text: str, size: float, bold: bool = False) -> list[tuple[Any, str]]: + def family(self, requested: str) -> str: + """Resolve a ``Style(font_family=…)`` list to a font file, or ``""``. + + Only the first family that resolves is used: a mockup says "this is not + the default face", it does not reproduce the whole fallback chain of a + device that may not have the font at all. Known families are looked up + under the usual font directories; an unknown name falls back to the + shipped sans face so the picture stays legible. + """ + wanted = [part.strip().strip("'\"").lower() for part in requested.split(",")] + for name in wanted: + if not name: + continue + if name in ("sans-serif", "sans", "system-ui", "roboto", "arial", "helvetica"): + return self.regular + if name in ("serif", "georgia", "times", "times new roman", "noto serif"): + candidate = self._first_existing(_SERIF_CANDIDATES) + return candidate or self.regular + if name in ("monospace", "mono", "courier", "courier new", "consolas", "menlo"): + candidate = self._first_existing(_MONO_CANDIDATES) + return candidate or self.regular + for directory in _FONT_DIRECTORIES: + stem = Path(directory) / name.replace(" ", "") + for suffix in (".ttf", ".otf", ".ttc"): + for attempt in (stem.with_suffix(suffix), stem.parent / f"{stem.name}{suffix}"): + if attempt.is_file(): + return str(attempt) + spaced = Path(directory) / f"{name.title().replace(' ', '')}{suffix}" + if spaced.is_file(): + return str(spaced) + return self.regular + + @staticmethod + def _first_existing(candidates: tuple[str, ...]) -> str: + for path in candidates: + if Path(path).is_file(): + return path + return "" + + def runs( + self, text: str, size: float, bold: bool = False, *, path: str | None = None + ) -> list[tuple[Any, str]]: """Split ``text`` into (font, chunk) runs, patching missing glyphs.""" - main_path = self.bold if bold else self.regular + main_path = path or (self.bold if bold else self.regular) main = self.font(main_path, size) runs: list[tuple[Any, str]] = [] for ch in text: chosen = main if not self._covers(main_path, main, ch): - for path in self._fallbacks: - candidate = self.font(path, size) - if self._covers(path, candidate, ch): + for fallback_path in self._fallbacks: + candidate = self.font(fallback_path, size) + if self._covers(fallback_path, candidate, ch): chosen = candidate break else: @@ -140,9 +209,12 @@ def ellipsize(self, text: str, size: float, bold: bool, width: float) -> str: high = middle - 1 return text[:low] + "…" - def width(self, text: str, size: float, bold: bool = False) -> float: + def width( + self, text: str, size: float, bold: bool = False, *, path: str | None = None + ) -> float: + """How wide ``text`` is when drawn in ``font``.""" total = 0.0 - for font, chunk in self.runs(text, size, bold): + for font, chunk in self.runs(text, size, bold, path=path): try: total += float(font.getlength(chunk)) except AttributeError: # pragma: no cover - bitmap font diff --git a/pymobile/core/ui/_mockup_layout.py b/pymobile/core/ui/_mockup_layout.py index db66a17..93f4bc5 100644 --- a/pymobile/core/ui/_mockup_layout.py +++ b/pymobile/core/ui/_mockup_layout.py @@ -169,8 +169,14 @@ def layout( box.style = style if style.get("elevation") and style.get("background") is None: style["_surface"] = self.p["SURFACE"] + # Style(opacity=…) dims the widget and everything inside it — the same + # thing Android's View.setAlpha() does — so it composes with the dim a + # disabled widget already gets. + opacity = _number(style.get("opacity")) + if opacity is not None: + box.fade *= max(0.0, min(1.0, opacity)) if not node.get("enabled", True): - box.fade = 0.45 + box.fade *= 0.45 return box def _padding( diff --git a/pymobile/core/ui/_mockup_paint.py b/pymobile/core/ui/_mockup_paint.py index a7d5e1b..ba8cc81 100644 --- a/pymobile/core/ui/_mockup_paint.py +++ b/pymobile/core/ui/_mockup_paint.py @@ -5,6 +5,8 @@ from collections.abc import Callable from typing import Any +from PIL import Image, ImageDraw + from ._mockup_colors import _Colour, _rgba from ._mockup_fonts import _Fonts @@ -13,6 +15,30 @@ _PaintFn = Callable[["_Painter", float, float, "_Box"], None] +def _pixel_access(image: Any) -> Any: + """``image.load()`` with a non-optional type (Pillow types it as Optional).""" + return image.load() + + +def _sample_stops(stops: list[tuple[float, _Colour]], t: float) -> _Colour: + """Interpolate a colour at ``t`` (0..1) through a sorted stop list.""" + previous_offset, previous_colour = stops[0] + if t <= previous_offset: + return previous_colour + for offset, colour in stops[1:]: + if t <= offset: + span = offset - previous_offset + amount = 0.0 if span <= 0 else (t - previous_offset) / span + return ( + round(previous_colour[0] + (colour[0] - previous_colour[0]) * amount), + round(previous_colour[1] + (colour[1] - previous_colour[1]) * amount), + round(previous_colour[2] + (colour[2] - previous_colour[2]) * amount), + round(previous_colour[3] + (colour[3] - previous_colour[3]) * amount), + ) + previous_offset, previous_colour = offset, colour + return previous_colour + + class _Box: """A laid-out view: border-box size, margins, own painting and children.""" @@ -30,16 +56,20 @@ def __init__(self, w: float, h: float, paint: _PaintFn | None = None) -> None: @property def outer_w(self) -> float: + """The width of the box including its outside margins.""" return self.w + self.margin[0] + self.margin[2] @property def outer_h(self) -> float: + """The height of the box including its outside margins.""" return self.h + self.margin[1] + self.margin[3] def set_outer_h(self, value: float) -> None: + """Set the outer height by adjusting the height, never going below zero.""" self.h = max(0.0, value - self.margin[1] - self.margin[3]) def set_outer_w(self, value: float) -> None: + """Set the outer width by adjusting the width, never going below zero.""" self.w = max(0.0, value - self.margin[0] - self.margin[2]) @@ -70,6 +100,7 @@ def rect( outline: _Colour | None = None, width: float = 1, ) -> None: + """Paint a rectangle, optionally rounded and outlined.""" if w <= 0 or h <= 0: return s = self.s @@ -85,6 +116,74 @@ def rect( else: self.draw.rectangle(box, fill=self._c(fill), outline=self._c(outline), width=stroke) + def gradient_rect( + self, + x: float, + y: float, + w: float, + h: float, + stops: list[tuple[float, _Colour]], + *, + radius: float = 0, + direction: str = "to_bottom", + ) -> None: + """Fill a rectangle with a linear ramp, interpolated in sRGB. + + No numpy here on purpose: the renderer is pure Pillow. The ramp is + painted row by row (or column by column, or pixel by pixel on a + diagonal) and then clipped to the rounded shape, so a corner radius and + a gradient do not fight each other. + """ + if w <= 0 or h <= 0 or len(stops) < 2: + return + from .style import GRADIENT_DIRECTIONS + + s = self.s + width_px, height_px = max(1, round(w * s)), max(1, round(h * s)) + start_x, start_y, end_x, end_y = GRADIENT_DIRECTIONS.get( + direction, GRADIENT_DIRECTIONS["to_bottom"] + ) + vector_x = (end_x - start_x) * width_px + vector_y = (end_y - start_y) * height_px + length_sq = vector_x * vector_x + vector_y * vector_y + if length_sq <= 0: + return + origin_x, origin_y = start_x * width_px, start_y * height_px + ramp = Image.new("RGBA", (width_px, height_px)) + pixels = _pixel_access(ramp) + + def colour_at(t: float) -> _Colour: + return _sample_stops(stops, min(1.0, max(0.0, t))) + + if vector_x == 0: # vertical ramp: one colour per row + for py in range(height_px): + t = (py - origin_y) * vector_y / length_sq + row_colour = colour_at(t) + for px in range(width_px): + pixels[px, py] = row_colour + elif vector_y == 0: # horizontal ramp: one colour per column + for px in range(width_px): + t = (px - origin_x) * vector_x / length_sq + column_colour = colour_at(t) + for py in range(height_px): + pixels[px, py] = column_colour + else: # diagonal ramp: project each pixel onto the axis + for py in range(height_px): + base = (py - origin_y) * vector_y + for px in range(width_px): + pixels[px, py] = colour_at((base + (px - origin_x) * vector_x) / length_sq) + + if radius > 0: + shape = Image.new("L", (width_px, height_px), 0) + ImageDraw.Draw(shape).rounded_rectangle( + (0, 0, width_px - 1, height_px - 1), + radius=min(round(radius * s), width_px / 2, height_px / 2), + fill=255, + ) + self.image.paste(ramp, (round(x * s), round(y * s)), shape) + else: + self.image.paste(ramp, (round(x * s), round(y * s))) + def shadow( self, x: float, y: float, w: float, h: float, *, radius: float, elevation: float ) -> None: @@ -112,6 +211,7 @@ def circle( outline: _Colour | None = None, width: float = 1, ) -> None: + """Paint a circle, optionally outlined.""" s = self.s self.draw.ellipse( [(cx - r) * s, (cy - r) * s, (cx + r) * s, (cy + r) * s], @@ -121,6 +221,7 @@ def circle( ) def line(self, points: list[tuple[float, float]], fill: _Colour, width: float = 1) -> None: + """Paint a polyline through ``points``.""" s = self.s self.draw.line( [(px * s, py * s) for px, py in points], @@ -130,12 +231,14 @@ def line(self, points: list[tuple[float, float]], fill: _Colour, width: float = ) def polygon(self, points: list[tuple[float, float]], fill: _Colour) -> None: + """Paint a filled polygon through ``points``.""" s = self.s self.draw.polygon([(px * s, py * s) for px, py in points], fill=self._c(fill)) def arc( self, cx: float, cy: float, r: float, start: float, end: float, fill: _Colour, width: float ) -> None: + """Paint an arc of the circle at ``cx, cy`` between two angles.""" s = self.s self.draw.arc( [(cx - r) * s, (cy - r) * s, (cx + r) * s, (cy + r) * s], @@ -146,22 +249,70 @@ def arc( ) def text( - self, x: float, y: float, text: str, size: float, colour: _Colour, *, bold: bool = False + self, + x: float, + y: float, + text: str, + size: float, + colour: _Colour, + *, + bold: bool = False, + font_path: str | None = None, + letter_spacing: float = 0.0, + line_height: float = 0.0, + underline: bool = False, + strikethrough: bool = False, ) -> None: - """Draw one line; ``y`` is the top of a ``size * _LINE`` high line box.""" + """Draw one line; ``y`` is the top of a ``size * _LINE`` high line box. + + ``font_path`` overrides the discovered sans face when a Style names a + family; ``letter_spacing`` is in dp, like the Style field, and + ``line_height`` shifts the baseline inside the taller line box the + caller laid out. + """ s = self.s px = x * s - for font, chunk in self.fonts.runs(text, size, bold): + spacing = letter_spacing * s + line_box = (size * _LINE + line_height) * s + for font, chunk in self.fonts.runs(text, size, bold, path=font_path): try: ascent, descent = font.getmetrics() except AttributeError: # pragma: no cover - bitmap font ascent, descent = round(size * s * 0.8), round(size * s * 0.2) - top = y * s + (size * _LINE * s - (ascent + descent)) / 2 - self.draw.text((px, top), chunk, font=font, fill=self._c(colour)) - try: - px += float(font.getlength(chunk)) - except AttributeError: # pragma: no cover - px += len(chunk) * size * s * 0.6 + top = y * s + (line_box - (ascent + descent)) / 2 + if spacing: + # Pillow cannot letter-space a string, so the chunks are drawn + # glyph by glyph with the extra space between them. + for character in chunk: + self.draw.text((px, top), character, font=font, fill=self._c(colour)) + try: + px += float(font.getlength(character)) + spacing + except AttributeError: # pragma: no cover + px += size * s * 0.6 + spacing + else: + self.draw.text((px, top), chunk, font=font, fill=self._c(colour)) + try: + px += float(font.getlength(chunk)) + except AttributeError: # pragma: no cover + px += len(chunk) * size * s * 0.6 + if underline or strikethrough: + end = px - spacing + if underline: + self.rect( + x + 0, + y + (line_box - descent) / s - 1, + max(1.0, (end - x * s) / s), + 1, + colour, + ) + if strikethrough: + self.rect( + x + 0, + y + (line_box / 2) / s, + max(1.0, (end - x * s) / s), + 1, + colour, + ) def lines( self, @@ -174,16 +325,39 @@ def lines( *, bold: bool = False, align: str = "", + font_path: str | None = None, + letter_spacing: float = 0.0, + line_height: float = 0.0, + underline: bool = False, + strikethrough: bool = False, ) -> None: + """Paint several lines of text, with the spacing and decorations asked for.""" + stride = size * _LINE + line_height for index, line in enumerate(lines): dx = 0.0 if align in ("center", "end", "right"): - spare = w - self.fonts.width(line, size, bold) + spare = w - ( + self.fonts.width(line, size, bold, path=font_path) + + max(0, len(line) - 1) * letter_spacing + ) dx = spare / 2 if align == "center" else spare - self.text(x + max(0.0, dx), y + index * size * _LINE, line, size, colour, bold=bold) + self.text( + x + max(0.0, dx), + y + index * stride, + line, + size, + colour, + bold=bold, + font_path=font_path, + letter_spacing=letter_spacing, + line_height=line_height, + underline=underline, + strikethrough=strikethrough, + ) # -- tree -------------------------------------------------------------- def paint(self, box: _Box, x: float, y: float) -> None: + """Paint one laid-out box: background, border, then its own content.""" bx, by = x + box.margin[0], y + box.margin[1] saved = self.fade self.fade *= box.fade @@ -193,12 +367,46 @@ def paint(self, box: _Box, x: float, y: float) -> None: if elevation > 0: self.shadow(bx, by, box.w, box.h, radius=radius, elevation=elevation) background = style.get("background") - if background is not None or radius or elevation: + gradient = style.get("gradient") + if isinstance(gradient, dict) and gradient.get("stops"): + # A gradient is the more specific instruction; a flat background + # next to it is what the app falls back on where gradients cannot + # be drawn, so the ramp is what the picture shows. + self.gradient_rect( + bx, + by, + box.w, + box.h, + [(float(offset), _rgba(colour)) for offset, colour in gradient["stops"]], + radius=radius, + direction=str(gradient.get("direction", "to_bottom")), + ) + elif background is not None or radius or elevation: fill = _rgba(background, (0, 0, 0, 0)) if background is not None else None if fill is None and elevation: fill = style.get("_surface") if fill is not None: self.rect(bx, by, box.w, box.h, fill, radius=radius) + border = style.get("border") + if isinstance(border, dict) and border.get("sides"): + colour = _rgba(border.get("color", "#E0E0E0")) + thickness = float(border.get("width", 1)) + sides = set(border["sides"]) + if len(sides) == 4: + self.rect( + bx, by, box.w, box.h, None, outline=colour, radius=radius, width=thickness + ) + else: + # One hairline per named side, drawn inside the box the way + # Android's setStroke does it. + if "top" in sides: + self.rect(bx, by, box.w, thickness, colour) + if "bottom" in sides: + self.rect(bx, by + box.h - thickness, box.w, thickness, colour) + if "left" in sides: + self.rect(bx, by, thickness, box.h, colour) + if "right" in sides: + self.rect(bx + box.w - thickness, by, thickness, box.h, colour) if style.get("_tappable"): # A hairline in the accent colour, drawn under the children: it # shows that the whole surface takes a tap without inventing a diff --git a/pymobile/core/ui/_mockup_widgets.py b/pymobile/core/ui/_mockup_widgets.py index d9b039a..ecf695c 100644 --- a/pymobile/core/ui/_mockup_widgets.py +++ b/pymobile/core/ui/_mockup_widgets.py @@ -14,6 +14,27 @@ from .theme import _readable_on +def _transform(text: str, transform: object) -> str: + """Apply ``Style(text_transform=…)`` the way the device renderer does.""" + if not transform: + return text + if transform == "uppercase": + return text.upper() + if transform == "lowercase": + return text.lower() + if transform == "capitalize": + return text.title() + return text + + +def _font_path(layout: _MockupContext, style: dict[str, Any]) -> str | None: + """The font file a ``Style(font_family=…)`` resolves to, or ``None``.""" + family = style.get("font_family") + if not isinstance(family, str) or not family.strip(): + return None + return layout.fonts.family(family) or None + + class _WidgetLayout(_MockupContext): def _text_box( self, @@ -36,6 +57,13 @@ def _text_box( colour = _rgba(style.get("color"), colour) if style.get("color") else colour bold = bool(style.get("bold")) or bold align = str(style.get("align") or align) + # Typography from the Style: the picture has to agree with the phone, + # or a line that fits in the mockup overflows there. + text = _transform(text, style.get("text_transform")) + font_path = _font_path(self, style) + letter_spacing = float(style.get("letter_spacing") or 0) + line_height = float(style.get("line_height") or 0) + max_lines = int(style["max_lines"]) if style.get("max_lines") else 0 pad = self._padding(style, pad) inner = max(1.0, w - pad[0] - pad[2]) @@ -45,8 +73,19 @@ def wrap(width: float) -> list[str]: return self.fonts.wrap(text, size, bold, width) lines = wrap(inner) - text_w = max((self.fonts.width(line, size, bold) for line in lines), default=0.0) - text_h = len(lines) * size * _LINE + if max_lines and len(lines) > max_lines: + lines = lines[:max_lines] + if style.get("text_overflow") != "clip": + lines[-1] = self.fonts.ellipsize(lines[-1] + "…", size, bold, inner) + text_w = max( + ( + self.fonts.width(line, size, bold, path=font_path) + + max(0, len(line) - 1) * letter_spacing + for line in lines + ), + default=0.0, + ) + text_h = len(lines) * (size * _LINE + line_height) box_w = w if fill else min(w, max(min_w, text_w + pad[0] + pad[2])) box_h = max(min_h, text_h + pad[1] + pad[3]) @@ -55,11 +94,25 @@ def paint(p: _Painter, x: float, y: float, b: _Box) -> None: background(p, x, y, b) inner_w = b.w - pad[0] - pad[2] wrapped = lines if inner_w >= inner - 0.5 else wrap(max(1.0, inner_w)) - height = len(wrapped) * size * _LINE + height = len(wrapped) * (size * _LINE + line_height) top = ( y + pad[1] + max(0.0, (b.h - pad[1] - pad[3] - height) / 2) if min_h else y + pad[1] ) - p.lines(x + pad[0], top, inner_w, wrapped, size, colour, bold=bold, align=align) + p.lines( + x + pad[0], + top, + inner_w, + wrapped, + size, + colour, + bold=bold, + align=align, + font_path=font_path, + letter_spacing=letter_spacing, + line_height=line_height, + underline=bool(style.get("underline")), + strikethrough=bool(style.get("strikethrough")), + ) return _Box(box_w, box_h, paint) @@ -493,7 +546,7 @@ def paint(pt: _Painter, x: float, y: float, b: _Box) -> None: @staticmethod def _pairs(props: dict[str, Any]) -> list[tuple[str, str]]: - """П-11: zip option values with their (possibly localised) labels.""" + """Zip option values with their (possibly localised) labels.""" option_values = [str(o) for o in (props.get("options") or [])] option_labels = [str(lbl) for lbl in (props.get("labels") or option_values)] while len(option_labels) < len(option_values): diff --git a/pymobile/core/ui/audit.py b/pymobile/core/ui/audit.py index 1fc958b..4d5e77c 100644 --- a/pymobile/core/ui/audit.py +++ b/pymobile/core/ui/audit.py @@ -100,6 +100,10 @@ def _has_name(kind: str, props: Mapping[str, Any]) -> bool: "IconButton": "label", "FloatingActionButton": "label", "Link": "text", + # A check box carries its own label, but it was missing from this table: + # check-ui reported the most ordinary `Checkbox(text="Remember me")` as + # an unnamed control. + "Checkbox": "text", "RadioButton": "text", "RangeSlider": "label", "ListTile": "title", @@ -141,8 +145,10 @@ def _natural_width(node: Mapping[str, Any], available: float) -> float | None: elif kind == "Dropdown": estimate = max(112.0, _text_width(props.get("value", ""), style.get("font_size"), 32.0)) elif kind in {"Switch", "Checkbox", "RadioButton"}: - estimate = 48.0 if kind != "RadioButton" else max( - 80.0, _text_width(props.get("text", ""), style.get("font_size"), 48.0) + estimate = ( + 48.0 + if kind != "RadioButton" + else max(80.0, _text_width(props.get("text", ""), style.get("font_size"), 48.0)) ) elif kind in {"Slider", "RangeSlider"}: estimate = 160.0 @@ -372,9 +378,7 @@ def visit(node: Mapping[str, Any], available: float, background: str | None = No if not isinstance(children, (list, tuple)): return visible = [ - child - for child in children - if isinstance(child, Mapping) and child.get("visible", True) + child for child in children if isinstance(child, Mapping) and child.get("visible", True) ] own_width = fixed_width if fixed_width is not None else limit content_width = max(0.0, own_width - padding[0] - padding[2]) @@ -384,8 +388,7 @@ def visit(node: Mapping[str, Any], available: float, background: str | None = No widths = [ _natural_width(child, content_width) for child in visible - if child.get("type") not in {"Expanded", "Flexible"} - and not _has_weight(child) + if child.get("type") not in {"Expanded", "Flexible"} and not _has_weight(child) ] if all(value is not None for value in widths): total = sum(value or 0.0 for value in widths) + spacing * max(0, len(visible) - 1) diff --git a/pymobile/core/ui/canvas.py b/pymobile/core/ui/canvas.py index 3fd15fb..074d2c1 100644 --- a/pymobile/core/ui/canvas.py +++ b/pymobile/core/ui/canvas.py @@ -120,6 +120,7 @@ def primitives(self, default: str) -> list[dict[str, Any]]: raise NotImplementedError def props(self) -> dict[str, Any]: + """The serialised props shared by every canvas element.""" return { **super().props(), "element": type(self).__name__, @@ -164,6 +165,7 @@ def points(self) -> tuple[tuple[float, float], ...]: return self._points def primitives(self, default: str) -> list[dict[str, Any]]: + """The element as paint primitives the previews can draw.""" return [ { "type": "line", @@ -191,6 +193,7 @@ def __init__( super().__init__(*points, **kwargs) def primitives(self, default: str) -> list[dict[str, Any]]: + """The element as paint primitives, one per segment.""" points = list(self._points) if self.closed and len(points) > 2: points.append(points[0]) @@ -261,6 +264,7 @@ def __init__( self.align = align def props(self) -> dict[str, Any]: + """The serialised props: which shape it is and, for text, the caption.""" return { **super().props(), "kind": self.kind, @@ -271,6 +275,7 @@ def props(self) -> dict[str, Any]: } def primitives(self, default: str) -> list[dict[str, Any]]: + """The element as paint primitives for its shape kind.""" colour = self._paint(default) geometry = self._geometry if self.kind == "rect": @@ -412,6 +417,7 @@ def props(self) -> dict[str, Any]: # Elements without a colour of their own follow the theme's text colour, # like a Label does; the resolution happens here so a theme change # repaints the drawing instead of freezing the colour it was born with. + """The serialised props: the drawing, its label and its size.""" default_colour = theme_color(self, "TEXT") return { **super().props(), @@ -423,6 +429,7 @@ def props(self) -> dict[str, Any]: } def to_dict(self) -> WidgetNode: + """The serialised canvas, sized to the drawing it holds.""" node = super().to_dict() # The renderers size the surface from the style/height like a Chart does. node["style"] = {"height": self.height, **node.get("style", {})} diff --git a/pymobile/core/ui/charts.py b/pymobile/core/ui/charts.py index cad8011..7699007 100644 --- a/pymobile/core/ui/charts.py +++ b/pymobile/core/ui/charts.py @@ -94,10 +94,12 @@ def _validate( @property def data(self) -> tuple[float, ...]: + """The plotted values, with the keys of a mapping turned into labels.""" return self._data @data.setter def data(self, value: Data) -> None: + """The plotted values, with the keys of a mapping turned into labels.""" labels = ( None if isinstance(value, Mapping) @@ -107,9 +109,11 @@ def data(self, value: Data) -> None: @property def labels(self) -> tuple[str, ...]: + """The label under each plotted value.""" return self._labels def set_data(self, data: Data, *, labels: Sequence[str] | None = None) -> None: + """Plot ``data``, re-rendering the chart when anything changed.""" values, names = self._validate(data, labels) if (values, names) != (self._data, self._labels): self._data, self._labels = values, names @@ -268,6 +272,7 @@ def y(value: float) -> float: return {"width": width, "height": height, "shapes": shapes} def props(self) -> dict[str, Any]: + """The serialised props: the values, their labels, the bars and the height.""" if positive_int(self.height, "height") < 80: raise ValueError("chart height must be at least 80 dp") label = self.title or f"{self.chart_kind} chart" @@ -284,6 +289,7 @@ def props(self) -> dict[str, Any]: } def to_dict(self) -> WidgetNode: + """The serialised chart, tall enough for its bars.""" node = super().to_dict() node["style"] = {"height": self.height, **node.get("style", {})} return node diff --git a/pymobile/core/ui/components.py b/pymobile/core/ui/components.py index 22bc479..fc04120 100644 --- a/pymobile/core/ui/components.py +++ b/pymobile/core/ui/components.py @@ -10,7 +10,7 @@ import os import re -from collections.abc import Callable, Sequence +from collections.abc import Callable, Mapping, Sequence from pathlib import Path from typing import Any from urllib.parse import unquote, urlparse @@ -57,13 +57,17 @@ def _parse_options(options: Sequence[Any]) -> tuple[list[str], list[str]]: """Normalise selection-widget options into parallel ``(values, labels)``. - П-11: ``Dropdown``/``SegmentedButtons``/``BottomNavigation`` previously + ``Dropdown``/``SegmentedButtons``/``BottomNavigation`` previously treated every option as both value and label, which breaks i18n — a translated label sent back from the front end would not match any value after a language switch. Accepting ``(value, label)`` pairs keeps the internal value stable while showing a localised label. A plain string ``"x"`` is shorthand for ``("x", "x")``. """ + if isinstance(options, Mapping): + # A whole mapping is the same shorthand as a list of single-item ones: + # ``SegmentedButtons({"all": "All", "mine": "Mine"})``. + options = list(options.items()) if not options: raise ValueError( "options must not be empty; pass at least one option, " @@ -75,6 +79,18 @@ def _parse_options(options: Sequence[Any]) -> tuple[list[str], list[str]]: if isinstance(opt, str): values.append(opt) labels.append(opt) + elif isinstance(opt, Mapping) and len(opt) == 1: + # ``{"all": "All"}`` — the shape ``MultiSelect`` and ``TabView`` + # already accept. SegmentedButtons used to read only the key, so a + # localised label silently turned into its internal value. + key, label = next(iter(opt.items())) + if not isinstance(key, str) or not isinstance(label, str): + raise ValueError( + f"options must be strings, (value, label) pairs or single-item " + f"{{value: label}} mappings of strings, got {opt!r}" + ) + values.append(key) + labels.append(label) elif ( isinstance(opt, (tuple, list)) and len(opt) == 2 @@ -177,6 +193,7 @@ def text(self) -> str: @text.setter def text(self, value: str) -> None: + """The label's text; assigning it re-renders the label.""" value = "" if value is None else str(value) if value != self._text: self._text = value @@ -187,6 +204,7 @@ def set_text(self, text: str) -> None: self.text = text def props(self) -> dict[str, Any]: + """The serialised props: the text after a transform or an overflow rule.""" return {**super().props(), "text": self._text} @@ -249,6 +267,7 @@ def text(self) -> str: @text.setter def text(self, value: str) -> None: + """The caption on the button; assigning it re-renders the button.""" value = "" if value is None else str(value) if value != self._text: self._text = value @@ -264,6 +283,7 @@ def press(self) -> None: self.on_press() def props(self) -> dict[str, Any]: + """The serialised props: the caption, the variant and the press callback.""" return { **super().props(), "text": self._text, @@ -272,8 +292,34 @@ def props(self) -> dict[str, Any]: } +#: ``TextInput(keyboard=…)`` values, each mapped to an Android input type on the +#: device and to an ````/``inputmode`` in the browser preview. +KEYBOARD_TYPES = { + "text": "text", + "email": "email", + "phone": "phone", + "number": "number", + "decimal": "decimal", + "url": "url", + "password": "password", + "search": "search", + "multiline": "multiline", +} + +#: What the keyboard's action key says; ``None`` keeps the platform default +#: (a newline for a multiline field, "Done" otherwise). +IME_ACTIONS = ("done", "go", "next", "search", "send", "previous", "none") + + class TextInput(Widget): - """Single- or multi-line text field.""" + """Single- or multi-line text field. + + ``keyboard`` picks the soft keyboard the field asks for (``"email"``, + ``"number"``, ``"phone"``, ``"url"``, ``"decimal"``, ``"search"``, + ``"password"``), ``ime_action`` the label of its action key, and + ``on_submit`` fires when that key is pressed — the Enter key on a desktop + preview, the ⌨ action on a phone. ``submit()`` triggers it from code. + """ type_name = "TextInput" __slots__ = ( @@ -283,6 +329,9 @@ class TextInput(Widget): "password", "max_length", "on_change", + "on_submit", + "keyboard", + "ime_action", "_revision", ) @@ -295,6 +344,9 @@ def __init__( password: bool = False, max_length: int | None = None, on_change: Callable[[str], None] | None = None, + on_submit: Callable[[str], object] | None = None, + keyboard: str | None = None, + ime_action: str | None = None, **kwargs: Any, ) -> None: # Deprecated alias: maxlength (HTML style) -> max_length @@ -310,6 +362,36 @@ def __init__( ) max_length = kwargs.pop("maxlength") super().__init__(**kwargs) + if keyboard is not None: + if not isinstance(keyboard, str) or keyboard.lower() not in KEYBOARD_TYPES: + raise ValueError( + f"invalid keyboard {keyboard!r}; expected one of: " + ", ".join(KEYBOARD_TYPES) + ) + keyboard = keyboard.lower() + # ``password`` and ``multiline`` keep working as they always did; a + # keyboard that contradicts them is a mistake worth naming rather + # than silently preferring one of the two. + if keyboard == "password" and multiline: + raise ValueError("a multiline field cannot use the password keyboard") + if keyboard != "password" and password: + raise ValueError("password=True and keyboard=… disagree; pick one") + if keyboard != "multiline" and multiline: + raise ValueError("multiline=True and keyboard=… disagree; pick one") + password = password or keyboard == "password" + multiline = multiline or keyboard == "multiline" + if ime_action is not None: + if not isinstance(ime_action, str) or ime_action.lower() not in IME_ACTIONS: + raise ValueError( + f"invalid ime_action {ime_action!r}; expected one of: " + ", ".join(IME_ACTIONS) + ) + ime_action = ime_action.lower() + if ime_action != "none" and on_submit is None: + # The key would be relabelled and then do nothing, which reads + # as a broken button rather than a missing callback. + raise ValueError( + f"ime_action={ime_action!r} relabels the keyboard's action key; " + "pass on_submit=… so that key does something" + ) if max_length is not None and max_length <= 0: raise ValueError("max_length must be positive") # None means "empty field", not the four characters of str(None): the @@ -324,6 +406,9 @@ def __init__( self.password = password self.max_length = max_length self.on_change = on_change + self.on_submit = on_submit + self.keyboard = keyboard + self.ime_action = ime_action # Bumped whenever the value is changed by code rather than by typing, # so the device renderer knows to apply it even to a focused field. self._revision = 0 @@ -335,6 +420,7 @@ def value(self) -> str: @value.setter def value(self, value: str) -> None: + """The text in the field; assigning it behaves like a user edit.""" self.set_value(value) def set_value(self, value: str) -> None: @@ -376,7 +462,32 @@ def clear(self) -> None: """Empty the field (also while it has focus on the device).""" self.set_value("") + def capture_state(self) -> dict[str, Any]: + """Keep what the user typed across a rebuild of the screen.""" + if not self._value: + # An empty field is the default; replaying it would only risk + # overwriting a value the new build deliberately set. + return {} + return {"value": self._value} + + def restore_state(self, state: Mapping[str, Any]) -> None: + """Take back the text a rebuilt screen's new field should show.""" + value = state.get("value") + if isinstance(value, str) and value != self._value: + self._apply(value, from_ui=True) + + def submit(self) -> None: + """Run the submit handler as the keyboard's action key would. + + A disabled field does not submit: the key is not reachable from the + device either, and a stale handler firing would be a surprise. + """ + if not self.enabled or self.on_submit is None: + return + self.on_submit(self._value) + def props(self) -> dict[str, Any]: + """The serialised props: value, placeholder, keyboard, submit action and limits.""" return { **super().props(), "value": self._value, @@ -385,6 +496,9 @@ def props(self) -> dict[str, Any]: "password": self.password, "max_length": self.max_length, "on_change": callback_name(self.on_change), + "on_submit": callback_name(self.on_submit), + "keyboard": self.keyboard or ("multiline" if self.multiline else "text"), + "ime_action": self.ime_action, "revision": self._revision, } @@ -434,6 +548,7 @@ def source(self) -> str: @source.setter def source(self, value: str) -> None: + """The image address: ``asset://``, ``file://``, ``http(s)://`` or a data URI.""" if not value: raise ValueError("image source must not be empty") self._validate_source(value) @@ -448,6 +563,7 @@ def fit(self) -> str: @fit.setter def fit(self, value: str) -> None: + """How the picture fills its box: cover, contain, fill, none or scale-down.""" if value not in self.FITS: raise ValueError(f"fit must be one of {', '.join(self.FITS)}") if value != self._fit: @@ -509,6 +625,7 @@ def _validate_source(self, source: str) -> None: ) def props(self) -> dict[str, Any]: + """The serialised props: source, fit mode, caption and the decorative flag.""" props = {**super().props(), "source": self.source, "fit": self.fit} if self.decorative: props["decorative"] = True @@ -539,6 +656,15 @@ def toggle(self) -> bool: self.set_checked(not self.checked) return self.checked + def capture_state(self) -> dict[str, Any]: + """Carry the toggle across a rebuild of the screen.""" + return {"checked": self._checked} if self._checked else {} + + def restore_state(self, state: Mapping[str, Any]) -> None: + """Re-apply a toggle the rebuilt screen's new switch should show.""" + if state.get("checked") is True: + self.set_checked(True) + @property def checked(self) -> bool: """Whether the switch is on; assigning to it schedules a redraw.""" @@ -546,6 +672,7 @@ def checked(self) -> bool: @checked.setter def checked(self, value: bool) -> None: + """Whether the switch is on; assigning it behaves like a user toggle.""" self.set_checked(value) def set_checked(self, checked: bool) -> None: @@ -565,6 +692,7 @@ def set_checked(self, checked: bool) -> None: self.on_toggle(checked) def props(self) -> dict[str, Any]: + """The serialised props: the on/off state and the toggle callback.""" return { **super().props(), "checked": self._checked, @@ -603,6 +731,7 @@ def value(self) -> float: @value.setter def value(self, value: float) -> None: + """How far the bar has filled; assigning it behaves like a progress update.""" self.set_value(value) def set_value(self, value: float) -> None: @@ -618,6 +747,7 @@ def fraction(self) -> float: return self._value / self.maximum def props(self) -> dict[str, Any]: + """The serialised props: value, maximum and the indeterminate flag.""" return { **super().props(), "value": self._value, @@ -639,6 +769,7 @@ def __init__(self, size: int = 8, **kwargs: Any) -> None: self.size = size def props(self) -> dict[str, Any]: + """The serialised props: the space the spacer takes.""" return {**super().props(), "size": self.size} @@ -705,6 +836,7 @@ def value(self) -> float: @value.setter def value(self, value: float) -> None: + """The position of the handle; assigning it behaves like a drag.""" self.set_value(value) @property @@ -721,7 +853,18 @@ def set_value(self, value: float) -> None: if self.on_change is not None and not in_build_scope(): self.on_change(clamped) + def capture_state(self) -> dict[str, Any]: + """Carry the thumb position across a rebuild of the screen.""" + return {"value": self._value} + + def restore_state(self, state: Mapping[str, Any]) -> None: + """Put a rebuilt screen's new slider where the old one was.""" + value = state.get("value") + if isinstance(value, (int, float)) and not isinstance(value, bool): + self.set_value(float(value)) + def props(self) -> dict[str, Any]: + """The serialised props: value plus the bounds, step and change callback.""" return { **super().props(), "value": self._value, @@ -762,11 +905,21 @@ def text(self) -> str: @text.setter def text(self, value: str) -> None: + """The caption beside the box.""" value = str(value) if self._text != value: self._text = value self.invalidate() + def capture_state(self) -> dict[str, Any]: + """Carry the tick across a rebuild of the screen.""" + return {"checked": self._checked} if self._checked else {} + + def restore_state(self, state: Mapping[str, Any]) -> None: + """Re-apply a tick the rebuilt screen's new box should show.""" + if state.get("checked") is True: + self.set_checked(True) + @property def checked(self) -> bool: """Whether the box is ticked; assigning to it schedules a redraw.""" @@ -774,6 +927,7 @@ def checked(self) -> bool: @checked.setter def checked(self, value: bool) -> None: + """Whether the box is ticked; assigning it behaves like a click.""" self.set_checked(value) def set_checked(self, checked: bool) -> None: @@ -797,6 +951,7 @@ def toggle(self) -> bool: return self._checked def props(self) -> dict[str, Any]: + """The serialised props: the caption, the ticked state and the toggle callback.""" return { **super().props(), "checked": self._checked, @@ -842,6 +997,7 @@ def rating(self) -> float: @rating.setter def rating(self, value: float) -> None: + """How many stars are filled; assigning it behaves like a rating change.""" self.set_value(value) @property @@ -851,6 +1007,7 @@ def value(self) -> float: @value.setter def value(self, value: float) -> None: + """How many stars are filled (the bridge's name for :attr:`rating`).""" self.set_value(value) def set_value(self, value: float) -> None: @@ -863,6 +1020,7 @@ def set_value(self, value: float) -> None: self.on_change(clamped) def props(self) -> dict[str, Any]: + """The serialised props: the rating, the star count and the change callback.""" return { **super().props(), "rating": self._rating, @@ -881,7 +1039,7 @@ class Dropdown(Widget): or a ``(value, label)`` pair — the stable machine-readable value is what :attr:`value` carries (and what ``on_select`` receives), while ``label`` is the text rendered. This keeps localised labels from leaking into - program logic (П-11). + program logic. """ type_name = "Dropdown" @@ -913,6 +1071,7 @@ def value(self) -> str: @value.setter def value(self, value: str) -> None: + """The value of the chosen option; assigning it behaves like picking it.""" self.select(value) def select(self, value: str) -> None: @@ -929,10 +1088,21 @@ def set_value(self, value: str) -> None: """Generic setter used by the app's ``change`` event handler.""" self.select(value) + def capture_state(self) -> dict[str, Any]: + """Carry the choice across a rebuild of the screen.""" + return {"value": self._value} + + def restore_state(self, state: Mapping[str, Any]) -> None: + """Re-select a rebuilt screen's new dropdown, when the option still exists.""" + value = state.get("value") + if isinstance(value, str) and value in self.options: + self.select(value) + def props(self) -> dict[str, Any]: + """The serialised props: the option values, their labels and the select callback.""" return { **super().props(), - # П-11: ``options`` stays the list of *values* (backwards compatible), + # ``options`` stays the list of *values* (backwards compatible), # ``labels`` is the matching list of visible, possibly localised # labels — renderers fall back to the value when no label is given # (a plain string option means value == label). @@ -969,6 +1139,7 @@ def text(self) -> str: @text.setter def text(self, value: str) -> None: + """The caption inside the chip.""" if value != self._text: self._text = value self.invalidate() @@ -980,9 +1151,11 @@ def selected(self) -> bool: @selected.setter def selected(self, value: bool) -> None: + """Whether the chip is in its selected look.""" self.set_selected(value) def set_selected(self, value: bool) -> None: + """Select or deselect the chip and re-render it.""" if value != self._selected: self._selected = value self.invalidate() @@ -993,6 +1166,7 @@ def press(self) -> None: self.on_press() def props(self) -> dict[str, Any]: + """The serialised props: the caption, the selected state and the press callback.""" return { **super().props(), "text": self._text, @@ -1027,17 +1201,20 @@ def text(self) -> str: @text.setter def text(self, value: str | int) -> None: + """The short text or number on the badge.""" value = str(value) if value != self._text: self._text = value self.invalidate() def to_dict(self) -> WidgetNode: + """The serialised badge, sized around its text.""" node = super().to_dict() node["style"] = {**{"width": "wrap", "corner_radius": 999}, **node.get("style", {})} return node def props(self) -> dict[str, Any]: + """The serialised props: text and the two colours, corrected for contrast.""" return { **super().props(), "text": self._text, @@ -1091,6 +1268,7 @@ def value(self) -> int: @value.setter def value(self, value: int) -> None: + """The number in the stepper; assigning it behaves like pressing plus or minus.""" self.set_value(value) def set_value(self, value: int) -> None: @@ -1113,6 +1291,7 @@ def decrement(self) -> int: return self._value def props(self) -> dict[str, Any]: + """The serialised props: the number plus the bounds, step and change callback.""" return { **super().props(), "value": self._value, @@ -1156,9 +1335,11 @@ def value(self) -> str: @value.setter def value(self, value: str) -> None: + """The text in the search field; assigning it updates the field.""" self.set_value(value) def set_value(self, value: str) -> None: + """Put ``value`` in the field, raising the change event but not the search one.""" self._apply(value, from_ui=False) def _ui_set_value(self, value: str) -> None: @@ -1189,6 +1370,7 @@ def clear(self) -> None: self.set_value("") def props(self) -> dict[str, Any]: + """The serialised props: the query, the placeholder, the revision and the two callbacks.""" return { **super().props(), "value": self._value, @@ -1225,6 +1407,7 @@ def text(self) -> str: @text.setter def text(self, value: str) -> None: + """The caption beside the radio button.""" if value != self._text: self._text = value self.invalidate() @@ -1236,9 +1419,11 @@ def selected(self) -> bool: @selected.setter def selected(self, value: bool) -> None: + """Whether this radio button is the chosen one.""" self.set_selected(value) def set_selected(self, value: bool) -> None: + """Mark the radio button as chosen or not, and re-render it.""" if value != self._selected: self._selected = value self.invalidate() @@ -1258,7 +1443,17 @@ def press(self) -> None: if self.on_press is not None: self.on_press() + def capture_state(self) -> dict[str, Any]: + """Carry the choice across a rebuild of the screen.""" + return {"selected": True} if self._selected else {} + + def restore_state(self, state: Mapping[str, Any]) -> None: + """Re-select a rebuilt screen's new radio.""" + if state.get("selected") is True: + self.set_selected(True) + def props(self) -> dict[str, Any]: + """The serialised props: the caption, the chosen state and the press callback.""" return { **super().props(), "text": self._text, @@ -1327,7 +1522,7 @@ def _choose(self, chosen: RadioButton) -> None: self._select_silent(chosen) self.invalidate() # A selection made while the tree is being built (build()) stays - # silent, like every other set_value() in this module (BUG-25). + # silent, like every other set_value() in this module. if self.on_select is not None and not in_build_scope(): self.on_select(chosen.text) @@ -1362,11 +1557,13 @@ def set_value(self, value: str) -> None: self.select(value) def add(self, child: Widget) -> Widget: + """Add a radio button to the group; anything else is rejected.""" if not isinstance(child, RadioButton): raise ValueError("RadioGroup children must be RadioButton instances") return super().add(child) def props(self) -> dict[str, Any]: + """The serialised props: the chosen index and value of the group.""" return {**super().props(), "value": self.value, "selected_index": self.selected_index} @@ -1376,7 +1573,7 @@ class SegmentedButtons(Widget): ``options`` is the ordered list of choices; ``value`` is the selected one. ``on_select`` fires when the selection changes (``on_change`` is a deprecated alias of it). Options support ``(value, label)`` pairs for - stable values with localised labels (П-11). + stable values with localised labels. **Long labels.** The options share one line, each as wide as its text. When they do not fit — five translated labels on a 360 dp phone — the bar scrolls @@ -1416,6 +1613,7 @@ def value(self) -> str: @value.setter def value(self, value: str) -> None: + """The value of the chosen segment; assigning it behaves like picking it.""" self.select(value) def select(self, value: str) -> None: @@ -1429,9 +1627,21 @@ def select(self, value: str) -> None: self.on_select(value) def set_value(self, value: str) -> None: + """Choose the segment called ``value`` (the bridge's name for :meth:`select`).""" self.select(value) + def capture_state(self) -> dict[str, Any]: + """Carry the selected segment across a rebuild of the screen.""" + return {"value": self._value} + + def restore_state(self, state: Mapping[str, Any]) -> None: + """Re-select a rebuilt screen's new segment, when it still exists.""" + value = state.get("value") + if isinstance(value, str) and value in self.options: + self.select(value) + def props(self) -> dict[str, Any]: + """The serialised props: the segments, their labels and the select callback.""" return { **super().props(), "options": list(self.options), @@ -1483,9 +1693,11 @@ def value(self) -> float: @value.setter def value(self, value: float) -> None: + """How far the bar has filled, clamped to the allowed range.""" self.set_value(value) def set_value(self, value: float) -> None: + """Move the bar to ``value``, clamped to ``minimum``..``maximum``, and re-render it.""" clamped = max(0.0, min(float(value), self.maximum)) if clamped != self._value: self._value = clamped @@ -1516,6 +1728,7 @@ def text(self) -> str: return f"{self.label} {body}".strip() if self.label else body def props(self) -> dict[str, Any]: + """The serialised props: the value, the bounds, the format string and the caption.""" return { **super().props(), "value": self._value, @@ -1526,8 +1739,48 @@ def props(self) -> dict[str, Any]: } +#: Schemes a Link may carry. Data from a server or a text field ends up in +#: ``url`` sooner or later, and everything outside this list — ``javascript:``, +#: ``file:``, ``intent:`` — is a way to run something instead of opening a page. +LINK_SCHEMES = frozenset({"http", "https", "mailto", "tel", "sms", "geo"}) + + +def _validated_url(url: str) -> str: + """Return ``url`` if its scheme is allowed, else raise ``ValueError``. + + A URL with no scheme is a relative path (``/help``, ``docs/index.html``) + and stays allowed: apps use those against the packaged assets. Anything + with a scheme has to be one of :data:`LINK_SCHEMES`. + """ + text = str(url).strip() + if not text: + return "" + scheme, separator, _ = text.partition(":") + if not separator: + return text + # A Windows path (``C:\notes``) and a relative path are not schemes. + normalised = scheme.strip().lower() + if normalised in LINK_SCHEMES: + return text + if len(normalised) == 1 and normalised.isalpha(): # a drive letter + return text + raise ValueError( + f"refusing to open {text!r}: a Link may use " + + ", ".join(sorted(scheme + ":" for scheme in LINK_SCHEMES)) + + " or a relative path. Pass the value through your own check if the " + "scheme really is intended, and open it with app.bridge.open_url()." + ) + + class Link(Widget): - """A tappable text styled as a hyperlink.""" + """A tappable text styled as a hyperlink. + + ``url`` accepts ``http``/``https``/``mailto``/``tel``/``sms``/``geo`` and + relative paths. Any other scheme is refused when the widget is built: a URL + that came from a server or a text field should not be able to decide that + the "link" runs ``javascript:`` — the preview wrote it into ``href`` and a + tap opened ``intent:`` URLs on the device. + """ type_name = "Link" __slots__ = ("_text", "url", "on_press") @@ -1542,7 +1795,7 @@ def __init__( ) -> None: super().__init__(**kwargs) self._text = text - self.url = url + self.url = _validated_url(url) self.on_press = on_press @property @@ -1552,6 +1805,7 @@ def text(self) -> str: @text.setter def text(self, value: str) -> None: + """The caption the user sees and taps.""" if value != self._text: self._text = value self.invalidate() @@ -1580,6 +1834,7 @@ def press(self) -> None: self.on_press() def props(self) -> dict[str, Any]: + """The serialised props: the caption, the validated URL and the press callback.""" return { **super().props(), "text": self._text, @@ -1637,6 +1892,7 @@ def add_row(self, row: Sequence[Any]) -> None: self.invalidate() def props(self) -> dict[str, Any]: + """The serialised props: the header cells and the rows.""" return { **super().props(), "headers": list(self.headers), @@ -1728,6 +1984,7 @@ def __init__( self.background = Color.validate(background) if background is not None else None def to_dict(self) -> WidgetNode: + """The serialised avatar, sized by its diameter.""" node = super().to_dict() node["style"] = { **{"width": self.size, "height": self.size, "corner_radius": self.size / 2}, @@ -1736,6 +1993,7 @@ def to_dict(self) -> WidgetNode: return node def props(self) -> dict[str, Any]: + """The serialised props: the photo, the initials, the size and the colours.""" return { **super().props(), "source": self.source, diff --git a/pymobile/core/ui/contract.py b/pymobile/core/ui/contract.py index 76abf26..1492130 100644 --- a/pymobile/core/ui/contract.py +++ b/pymobile/core/ui/contract.py @@ -19,6 +19,8 @@ def text_value(value: object) -> str: and widgets coerce their own text props on the way in. """ return "" if value is None else str(value) + + WidgetProps: TypeAlias = dict[str, SerializedValue] StyleNode: TypeAlias = dict[str, SerializedValue] diff --git a/pymobile/core/ui/controls.py b/pymobile/core/ui/controls.py index ab1b0e3..e805899 100644 --- a/pymobile/core/ui/controls.py +++ b/pymobile/core/ui/controls.py @@ -41,16 +41,19 @@ def __init__( @property def name(self) -> str: + """The icon name, one of :data:`~pymobile.core.ui.drawing.ICON_NAMES`.""" return self._name @name.setter def name(self, value: str) -> None: + """The icon name, one of :data:`~pymobile.core.ui.drawing.ICON_NAMES`.""" icon_drawing(value) if value != self._name: self._name = value self.invalidate() def props(self) -> dict[str, Any]: + """The serialised props: the name, the colour and the size, plus the drawing to paint.""" positive_int(self.size, "size") color = self.color or self.style.color or theme_color(self, "TEXT") return { @@ -62,6 +65,7 @@ def props(self) -> dict[str, Any]: } def to_dict(self) -> WidgetNode: + """The serialised icon, sized like its square artwork.""" node = super().to_dict() if node["type"] == self.type_name: node["style"] = {"width": self.size, "height": self.size, **node.get("style", {})} @@ -101,16 +105,19 @@ def __init__( @property def name(self) -> str: + """The icon name drawn inside the button.""" return self._name @name.setter def name(self, value: str) -> None: + """The icon name drawn inside the button.""" icon_drawing(value) if value != self._name: self._name = value self.invalidate() def props(self) -> dict[str, Any]: + """The serialised props: the drawing, the size and the background colour.""" if positive_int(self.size, "size") < 48: raise ValueError("IconButton size must be at least 48 dp") if not self.label.strip(): @@ -126,6 +133,7 @@ def props(self) -> dict[str, Any]: } def to_dict(self) -> WidgetNode: + """The serialised button; it raises when there is no accessible label.""" node = super().to_dict() if node["type"] == self.type_name: node["style"] = { @@ -147,12 +155,14 @@ def __init__(self, name: str = "add", *, size: int = 56, **kwargs: Any) -> None: super().__init__(name, size=size, **kwargs) def props(self) -> dict[str, Any]: + """The serialised props: the drawing, its size and the background colour.""" props = super().props() props["background"] = self.background or theme_color(self, "PRIMARY") props["drawing"] = icon_drawing(self.name, self.color or "#FFFFFF") return props def to_dict(self) -> WidgetNode: + """The serialised action button, with the elevation a FAB is drawn at.""" node = super().to_dict() node.setdefault("style", {}).setdefault("elevation", 6) return node @@ -193,25 +203,30 @@ def _validate_options(options: Sequence[str]) -> tuple[str, ...]: @property def options(self) -> tuple[str, ...]: + """The suggestions to offer, in the order they are shown.""" return self._options @options.setter def options(self, value: Sequence[str]) -> None: + """The suggestions to offer, in the order they are shown.""" self.set_options(value) def set_options(self, options: Sequence[str]) -> None: + """Replace the suggestions, re-rendering the field.""" values = self._validate_options(options) if values != self._options: self._options = values self.invalidate() def suggestions(self, query: str | None = None) -> tuple[str, ...]: + """The options that match ``query``, or all of them when it is empty.""" text = self.value if query is None else query if len(text) < self.threshold: return () return tuple(o for o in self.options if text.casefold() in o.casefold()) def select(self, value: str) -> None: + """Choose one of the suggestions and notify ``on_select``.""" if value not in self.options: raise ValueError(f"{value!r} is not an autocomplete option") self.set_value(value) @@ -227,6 +242,7 @@ def _ui_set_value(self, value: str) -> None: super()._ui_set_value(value) def props(self) -> dict[str, Any]: + """The serialised props: value, suggestions, threshold and the select callback.""" positive_int(self.threshold, "threshold") return { **super().props(), @@ -272,14 +288,17 @@ def __init__( @property def minimum(self) -> float: + """The lowest value either handle can take.""" return self._minimum @property def maximum(self) -> float: + """The highest value either handle can take.""" return self._maximum @property def step(self) -> float: + """The distance between the values a handle can take.""" return self._step def _snap(self, value: float) -> float: @@ -299,21 +318,26 @@ def _normalise(self, value: Sequence[float]) -> tuple[float, float]: @property def value(self) -> tuple[float, float]: + """The chosen range as ``(low, high)``.""" return self._value @value.setter def value(self, value: Sequence[float]) -> None: + """The chosen range as ``(low, high)``.""" self.set_value(value) @property def low(self) -> float: + """The lower end of the range.""" return self._value[0] @property def high(self) -> float: + """The upper end of the range.""" return self._value[1] def set_value(self, value: Sequence[float]) -> None: + """Set both ends of the range, keeping them inside the bounds and ordered.""" new = self._normalise(value) if new != self._value: self._value = new @@ -330,6 +354,7 @@ def _ui_set_value(self, value: str) -> None: self.set_value(decoded) def props(self) -> dict[str, Any]: + """The serialised props: both ends, the bounds and the change callback.""" return { **super().props(), "low": self.low, @@ -342,6 +367,7 @@ def props(self) -> dict[str, Any]: } def to_dict(self) -> WidgetNode: + """The serialised slider, full width and tall enough for its handles.""" node = super().to_dict() node["style"] = {"height": 64, **node.get("style", {})} return node @@ -398,14 +424,17 @@ def __init__( @property def item_count(self) -> int: + """How many pages the view holds.""" return self._count @property def value(self) -> int: + """The index of the page on screen.""" return self._value @value.setter def value(self, value: int) -> None: + """The index of the page on screen.""" self.select(value) def _validate_index(self, value: int) -> int: @@ -422,6 +451,7 @@ def _page(self, index: int) -> Widget: return page def select(self, index: int) -> None: + """Show the page at ``index`` and notify ``on_select``.""" index = self._validate_index(index) if index == self._value: return @@ -439,15 +469,18 @@ def select(self, index: int) -> None: self.on_select(index) def set_value(self, value: int) -> None: + """Show the page at ``value`` (the bridge's name for :meth:`select`).""" self.select(value) def next(self) -> None: + """Swipe to the next page, if there is one.""" if self.value < self.item_count - 1: self.select(self.value + 1) elif self.loop: self.select(0) def previous(self) -> None: + """Swipe to the previous page, if there is one.""" if self.value > 0: self.select(self.value - 1) elif self.loop: @@ -461,12 +494,15 @@ def _ui_set_value(self, value: str) -> None: raise ValueError("page index is out of range") from None def add(self, child: Widget) -> Widget: + """Add a page after the current ones.""" raise ValueError("PageView owns its pages; construct a new pager to replace the page set") def clear(self) -> None: + """Remove every page, leaving the view empty.""" raise ValueError("PageView needs a page; use select()") def props(self) -> dict[str, Any]: + """The serialised props: the page count, the index and the select callback.""" positive_int(self.height, "height") return { **super().props(), @@ -479,6 +515,7 @@ def props(self) -> dict[str, Any]: def to_dict(self) -> WidgetNode: # Screen.refresh() detaches the old tree. Restore ownership of a kept pager. + """The serialised view; it keeps only the page on screen.""" for node in self.walk(): for child in node.children: child._parent = node diff --git a/pymobile/core/ui/dialogs.py b/pymobile/core/ui/dialogs.py index ec1da91..a4eb484 100644 --- a/pymobile/core/ui/dialogs.py +++ b/pymobile/core/ui/dialogs.py @@ -71,6 +71,7 @@ def title(self) -> str: @title.setter def title(self, value: str) -> None: + """The heading shown at the top of the dialog.""" if value != self._title: self._title = value self.invalidate() @@ -98,6 +99,7 @@ def dismiss(self) -> None: self.close() def props(self) -> dict[str, Any]: + """The serialised props: the title, the spacing and the sheet flag.""" props = {**super().props(), "title": self._title, "sheet": self.sheet} if not props.get("spacing"): props.pop("spacing", None) @@ -135,10 +137,12 @@ def __init__( @property def message(self) -> str: + """The message inside the alert.""" return self._message_label.text @message.setter def message(self, value: str) -> None: + """The message inside the alert.""" self._message_label.text = value def acknowledge(self) -> None: @@ -156,6 +160,7 @@ def acknowledge(self) -> None: self.on_acknowledge() def dismiss(self) -> None: + """Close the alert as if the user had acknowledged it.""" self.acknowledge() @@ -204,10 +209,12 @@ def __init__( @property def message(self) -> str: + """The question the dialog asks.""" return self._message_label.text @message.setter def message(self, value: str) -> None: + """The question the dialog asks.""" self._message_label.text = value def confirm(self) -> None: @@ -235,6 +242,7 @@ def cancel(self) -> None: self.on_cancel() def dismiss(self) -> None: + """Close the dialog as if the user had cancelled.""" self.cancel() diff --git a/pymobile/core/ui/drawing.py b/pymobile/core/ui/drawing.py index eda8f2d..bdbb2e0 100644 --- a/pymobile/core/ui/drawing.py +++ b/pymobile/core/ui/drawing.py @@ -40,10 +40,62 @@ "calendar", "user", "download", + # -- second batch: the everyday half of a Material icon set ------------- + "upload", + "phone", + "mail", + "lock", + "unlock", + "eye", + "eye_off", + "camera", + "image", + "bell", + "bookmark", + "cart", + "clock", + "filter", + "location", + "play", + "pause", + "stop", + "wifi", + "cloud", + "folder", + "file", + "copy", + "undo", + "redo", + "plus_circle", + "minus_circle", + "check_circle", + "close_circle", + "warning", + "help", + "logout", + "login", + "grid", + "list", + "more", + "drag", + "sort", + "sync", + "print", + "mic", + "volume", + "battery", + "signal", + "flag", + "tag", + "gift", + "music", + "video", + "qr", ) def finite_number(value: object, name: str) -> float: + """``value`` as a float, rejecting bools, non-numbers and infinities.""" if isinstance(value, bool): raise TypeError(f"{name} must be a finite number, not bool") try: @@ -56,6 +108,7 @@ def finite_number(value: object, name: str) -> float: def positive_int(value: int, name: str) -> int: + """``value`` as an int of at least one, rejecting bools and smaller numbers.""" if isinstance(value, bool) or not isinstance(value, int): raise TypeError(f"{name} must be an int") if value < 1: @@ -64,6 +117,7 @@ def positive_int(value: int, name: str) -> int: def theme_color(widget: Widget, key: str) -> str: + """The theme colour called ``key``, from the mounted screen or the default theme.""" screen = widget.screen if screen is not None and screen.mounted: return screen.app.theme[key] @@ -71,10 +125,12 @@ def theme_color(widget: Widget, key: str) -> str: def line(points: list[tuple[float, float]], color: str, width: float = 2) -> dict[str, Any]: + """A drawing made of a single line through ``points``.""" return {"type": "line", "points": [list(p) for p in points], "color": color, "width": width} def icon_drawing(name: str, color: str = "#212121") -> dict[str, Any]: + """The built-in shapes for ``name`` drawn in ``color``.""" if name not in ICON_NAMES: raise ValueError(f"unknown icon {name!r}; choose from: {', '.join(ICON_NAMES)}") Color.validate(color) @@ -83,6 +139,35 @@ def icon_drawing(name: str, color: str = "#212121") -> dict[str, Any]: def stroke(*points: tuple[float, float]) -> None: shapes.append(line(list(points), color)) + def polygon(*points: tuple[float, float], filled: bool = False) -> None: + shapes.append( + { + "type": "polygon", + "points": [list(p) for p in points], + "color": color, + "fill": filled, + "width": 2, + } + ) + + def arc(x: float, y: float, radius: float, start: float, sweep: float) -> None: + """A stroked arc, emitted as a polyline. + + A filled ``sector`` is the only arc every renderer already draws, and a + sector is a wedge: the shackle of a lock and the waves of a Wi-Fi icon + came out as black crescents. A polyline is stroke-only, so the same + points draw a line everywhere. + """ + steps = max(2, int(abs(sweep) / 12) + 2) + points = [ + ( + x + radius * math.cos(math.radians(start + sweep * index / steps)), + y + radius * math.sin(math.radians(start + sweep * index / steps)), + ) + for index in range(steps + 1) + ] + stroke(*points) + def circle(x: float, y: float, radius: float, *, filled: bool = False) -> None: shapes.append( { @@ -188,6 +273,190 @@ def circle(x: float, y: float, radius: float, *, filled: bool = False) -> None: stroke((12, 3), (12, 16)) stroke((6, 10), (12, 16), (18, 10)) stroke((4, 17), (4, 21), (20, 21), (20, 17)) + elif name == "upload": + stroke((12, 16), (12, 3)) + stroke((6, 9), (12, 3), (18, 9)) + stroke((4, 17), (4, 21), (20, 21), (20, 17)) + elif name == "phone": + stroke( + (7, 2), + (4, 5), + (6, 12), + (12, 18), + (19, 20), + (22, 17), + (19, 13), + (16, 15), + (12, 10), + (9, 8), + (11, 5), + (7, 2), + ) + elif name == "mail": + stroke((2, 5), (22, 5), (22, 19), (2, 19), (2, 5)) + stroke((2, 6), (12, 13), (22, 6)) + elif name == "lock": + stroke((5, 11), (19, 11), (19, 21), (5, 21), (5, 11)) + arc(12, 10, 5, 180, 180) + circle(12, 16, 1.5, filled=True) + elif name == "unlock": + stroke((5, 11), (19, 11), (19, 21), (5, 21), (5, 11)) + arc(12, 7, 5, 180, 180) + circle(12, 16, 1.5, filled=True) + elif name in ("eye", "eye_off"): + stroke((2, 12), (6, 7), (12, 5), (18, 7), (22, 12)) + stroke((2, 12), (6, 17), (12, 19), (18, 17), (22, 12)) + circle(12, 12, 3.5) + if name == "eye_off": + stroke((4, 20), (20, 4)) + elif name == "camera": + stroke((3, 7), (8, 7), (9, 4), (15, 4), (16, 7), (21, 7), (21, 20), (3, 20), (3, 7)) + circle(12, 13, 4) + elif name == "image": + stroke((3, 4), (21, 4), (21, 20), (3, 20), (3, 4)) + circle(8, 9, 1.8, filled=True) + stroke((4, 18), (9, 12), (14, 17), (17, 13), (20, 17)) + elif name == "bell": + stroke((5, 17), (6, 10), (9, 5), (12, 4), (15, 5), (18, 10), (19, 17), (5, 17)) + stroke((4, 17), (20, 17)) + stroke((10, 20), (12, 22), (14, 20)) + elif name == "bookmark": + stroke((6, 3), (18, 3), (18, 21), (12, 16), (6, 21), (6, 3)) + elif name == "cart": + circle(9, 20, 1.6, filled=True) + circle(18, 20, 1.6, filled=True) + stroke((2, 4), (5, 4), (8, 15), (19, 15), (22, 7), (6, 7)) + elif name == "clock": + circle(12, 12, 9) + stroke((12, 6), (12, 12), (16, 15)) + elif name == "filter": + stroke((3, 5), (21, 5), (14, 13), (14, 20), (10, 18), (10, 13), (3, 5)) + elif name == "location": + stroke((12, 22), (6, 13), (5, 9), (8, 4), (12, 3), (16, 4), (19, 9), (18, 13), (12, 22)) + circle(12, 10, 2.8) + elif name == "play": + polygon((8, 5), (20, 12), (8, 19), filled=True) + elif name == "pause": + stroke((9, 5), (9, 19)) + stroke((15, 5), (15, 19)) + elif name == "stop": + stroke((6, 6), (18, 6), (18, 18), (6, 18), (6, 6)) + elif name == "wifi": + arc(12, 20, 10, 200, 140) + arc(12, 20, 6, 200, 140) + circle(12, 19, 1.8, filled=True) + elif name == "cloud": + stroke((7, 18), (5, 14), (7, 10), (11, 9), (15, 10), (18, 13), (19, 18), (7, 18)) + elif name == "folder": + stroke((2, 6), (9, 6), (11, 9), (22, 9), (22, 20), (2, 20), (2, 6)) + elif name == "file": + stroke((5, 2), (14, 2), (19, 7), (19, 22), (5, 22), (5, 2)) + stroke((14, 2), (14, 7), (19, 7)) + elif name == "copy": + stroke((8, 3), (20, 3), (20, 15), (8, 15), (8, 3)) + stroke((4, 7), (4, 21), (16, 21), (16, 17)) + elif name == "undo": + arc(12, 12, 7, 0, 200) + stroke((5, 8), (4, 13), (8, 16)) + elif name == "redo": + arc(12, 12, 7, 340, 200) + stroke((19, 8), (20, 13), (16, 16)) + elif name == "plus_circle": + circle(12, 12, 9) + stroke((12, 7), (12, 17)) + stroke((7, 12), (17, 12)) + elif name == "minus_circle": + circle(12, 12, 9) + stroke((7, 12), (17, 12)) + elif name == "check_circle": + circle(12, 12, 9) + stroke((7, 12), (11, 16), (17, 8)) + elif name == "close_circle": + circle(12, 12, 9) + stroke((9, 9), (15, 15)) + stroke((15, 9), (9, 15)) + elif name == "warning": + stroke((12, 3), (22, 20), (2, 20), (12, 3)) + stroke((12, 9), (12, 14)) + circle(12, 17, 1.2, filled=True) + elif name == "help": + circle(12, 12, 9) + stroke((9, 9), (10, 7), (13, 6), (15, 8), (14, 11), (12, 13), (12, 15)) + circle(12, 18, 1.2, filled=True) + elif name in ("logout", "login"): + stroke((10, 4), (4, 4), (4, 20), (10, 20)) + arrow = (3, 12) if name == "logout" else (21, 12) + tip = (2, 12) if name == "logout" else (22, 12) + stroke((3, 12), (21, 12)) + stroke((17, 8), (21, 12), (17, 16) if name == "logout" else (17, 8)) + del arrow, tip + elif name == "grid": + for x0, y0 in ((3, 3), (13, 3), (3, 13), (13, 13)): + stroke((x0, y0), (x0 + 8, y0), (x0 + 8, y0 + 8), (x0, y0 + 8), (x0, y0)) + elif name == "list": + for y in (6, 12, 18): + circle(5, y, 1.4, filled=True) + stroke((9, y), (21, y)) + elif name == "more": + circle(5, 12, 1.8, filled=True) + circle(12, 12, 1.8, filled=True) + circle(19, 12, 1.8, filled=True) + elif name == "drag": + for x, y in ((9, 8), (15, 8), (9, 12), (15, 12), (9, 16), (15, 16)): + circle(x, y, 1.3, filled=True) + elif name == "sort": + stroke((4, 7), (16, 7)) + stroke((4, 12), (12, 12)) + stroke((4, 17), (8, 17)) + stroke((18, 4), (18, 20)) + stroke((15, 17), (18, 20), (21, 17)) + elif name == "sync": + arc(12, 12, 8, 300, 260) + stroke((20, 4), (20, 9), (15, 9)) + elif name == "print": + stroke((7, 3), (17, 3), (17, 8), (7, 8), (7, 3)) + stroke((3, 8), (21, 8), (21, 16), (17, 16), (17, 21), (7, 21), (7, 16), (3, 16), (3, 8)) + stroke((7, 16), (17, 16)) + elif name == "mic": + stroke((9, 5), (9, 10), (12, 13), (15, 10), (15, 5), (12, 2), (9, 5)) + stroke((5, 11), (7, 15), (12, 17), (17, 15), (19, 11)) + stroke((12, 17), (12, 21)) + stroke((9, 21), (15, 21)) + elif name == "volume": + polygon((4, 9), (8, 9), (13, 5), (13, 19), (8, 15), (4, 15), filled=True) + arc(15, 12, 6, 320, 80) + arc(15, 12, 9, 320, 80) + elif name == "battery": + stroke((2, 7), (19, 7), (19, 17), (2, 17), (2, 7)) + stroke((20, 10), (22, 10), (22, 14), (20, 14)) + stroke((5, 10), (9, 10), (9, 14), (5, 14), (5, 10)) + elif name == "signal": + stroke((3, 20), (6, 15), (10, 18), (14, 9), (18, 12), (21, 4)) + elif name == "flag": + stroke((5, 3), (5, 21)) + stroke((5, 4), (18, 4), (15, 8), (18, 12), (5, 12), (5, 4)) + elif name == "tag": + stroke((3, 11), (11, 3), (21, 3), (21, 13), (13, 21), (3, 11)) + circle(17, 7, 1.5, filled=True) + elif name == "gift": + stroke((3, 8), (21, 8), (21, 12), (3, 12), (3, 8)) + stroke((5, 12), (5, 21), (19, 21), (19, 12)) + stroke((12, 8), (12, 21)) + stroke((12, 8), (8, 8), (7, 5), (10, 4), (12, 8)) + stroke((12, 8), (16, 8), (17, 5), (14, 4), (12, 8)) + elif name == "music": + stroke((9, 18), (9, 5), (20, 3), (20, 16)) + circle(6.5, 18, 2.6, filled=True) + circle(17.5, 16, 2.6, filled=True) + elif name == "video": + stroke((2, 6), (15, 6), (15, 18), (2, 18), (2, 6)) + polygon((15, 11), (22, 7), (22, 17), (15, 13), filled=True) + elif name == "qr": + stroke((3, 3), (9, 3), (9, 9), (3, 9), (3, 3)) + stroke((15, 3), (21, 3), (21, 9), (15, 9), (15, 3)) + stroke((3, 15), (9, 15), (9, 21), (3, 21), (3, 15)) + stroke((15, 15), (15, 21)) + stroke((18, 15), (21, 15), (21, 21), (18, 21), (18, 15)) return {"width": 24, "height": 24, "shapes": shapes} diff --git a/pymobile/core/ui/extra_widgets.py b/pymobile/core/ui/extra_widgets.py index 8e07b95..181f57a 100644 --- a/pymobile/core/ui/extra_widgets.py +++ b/pymobile/core/ui/extra_widgets.py @@ -286,6 +286,7 @@ def remaining(self) -> float: @property def running(self) -> bool: + """Whether the countdown is still ticking.""" return self._job is not None def start(self) -> None: @@ -491,6 +492,7 @@ def __init__( super().__init__(**kwargs) def props(self) -> WidgetProps: + """The serialised props: the strokes, their colour and width.""" return { **super().props(), "height": self.pad_height, @@ -507,6 +509,7 @@ def strokes(self) -> list[Stroke]: @property def is_empty(self) -> bool: + """Whether the pad has no strokes yet.""" return not self._strokes def clear(self) -> None: diff --git a/pymobile/core/ui/extras_preview.py b/pymobile/core/ui/extras_preview.py index 65e3cb7..15e045f 100644 --- a/pymobile/core/ui/extras_preview.py +++ b/pymobile/core/ui/extras_preview.py @@ -74,6 +74,7 @@ def render_extra_html( node: dict[str, Any], render: Callable[[dict[str, Any]], str], css: str ) -> str: + """The browser markup for the widget types the main renderer cannot draw.""" kind, props = node["type"], node.get("props", {}) wid = escape(str(node.get("id", "")), quote=True) disabled = "" if node.get("enabled", True) else " disabled" @@ -195,10 +196,63 @@ def render_extra_html( "share": "⇧", "star": "★", "user": "👤", + # The second batch: a plain glyph for every bundled icon, so the text + # preview says "bell" with a bell and not with ``[icon:bell]``. + "battery": "▮", + "bell": "🔔", + "bookmark": "🔖", + "camera": "📷", + "cart": "🛒", + "check_circle": "✔", + "clock": "🕒", + "cloud": "☁", + "close_circle": "⊗", + "copy": "⧉", + "drag": "⠿", + "eye": "👁", + "eye_off": "🚫", + "file": "🗋", + "filter": "⏷", + "flag": "⚑", + "folder": "📁", + "gift": "🎁", + "grid": "▦", + "help": "?", + "image": "🖼", + "list": "☷", + "location": "📍", + "lock": "🔒", + "login": "⇥", + "logout": "⇤", + "mail": "✉", + "mic": "🎤", + "minus_circle": "⊖", + "more": "⋯", + "music": "♪", + "pause": "❚❚", + "phone": "📞", + "play": "▶", + "plus_circle": "⊕", + "print": "🖨", + "qr": "▩", + "redo": "↷", + "signal": "▁▄▂", + "sort": "⇅", + "stop": "■", + "sync": "⟲", + "tag": "🏷", + "undo": "↶", + "unlock": "🔓", + "upload": "⤒", + "video": "🎬", + "volume": "🔊", + "warning": "⚠", + "wifi": "📶", } def extra_ascii(node: dict[str, Any]) -> list[str]: + """The text-preview lines for the widget types the text renderer cannot draw.""" kind, props = node["type"], node.get("props", {}) if kind == "Icon": name = str(props.get("name", "")) @@ -273,6 +327,7 @@ def _tk_color(color: str, fallback: str) -> str: def paint_tk( canvas: Any, drawing: dict[str, Any], width: float, height: float, *, button: bool = False ) -> None: + """Draw ``drawing`` onto a Tk canvas, scaled to fit the space it was given.""" canvas.delete("drawing") logical_w, logical_h = float(drawing["width"]), float(drawing["height"]) scale = min(width / logical_w, height / logical_h) @@ -349,6 +404,7 @@ def xy(x: float, y: float) -> tuple[float, float]: def build_extra_gui(preview: Any, parent: Any, node: dict[str, Any], background: str) -> None: + """Create the Tk widgets for the widget types the main Tk renderer cannot draw.""" tk, props, kind = preview._tk, node.get("props", {}), node["type"] wid = str(node["id"]) enabled = bool(node.get("enabled", True)) @@ -553,6 +609,7 @@ def key(event: Any) -> None: def patch_extra_gui(preview: Any, node: dict[str, Any]) -> None: + """Update an already built extras widget in place instead of rebuilding it.""" wid, props = str(node["id"]), node.get("props", {}) data = preview._extra_states.get(wid) if data is None: @@ -586,6 +643,7 @@ def patch_extra_gui(preview: Any, node: dict[str, Any]) -> None: def extra_mockup(layout: Any, kind: str, node: dict[str, Any], w: float, fill: bool) -> Any: + """The PNG-mockup box for the widget types the main mockup painter cannot draw.""" from .mockup import _Box, _rgba props, style = node.get("props", {}), node.get("style", {}) diff --git a/pymobile/core/ui/gui.py b/pymobile/core/ui/gui.py index 7802f36..07d66cf 100644 --- a/pymobile/core/ui/gui.py +++ b/pymobile/core/ui/gui.py @@ -21,7 +21,7 @@ from collections.abc import Callable from pathlib import Path -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING, Any, NamedTuple from ...log import get_logger from .contract import text_value @@ -54,6 +54,17 @@ } #: Containers that simply stack their children vertically in the preview. +#: Widget types the Tk preview draws through the shared extras renderer. +_EXTRA_GUI_KINDS = ( + "Icon", + "IconButton", + "AutoComplete", + "RangeSlider", + "PageView", + "Chart", + "Canvas", +) + _VERTICAL = ("Column", "Container", "SafeArea", "Expanded", "Flexible") @@ -154,6 +165,21 @@ def skeleton(node: dict[str, Any]) -> tuple[Any, ...]: ) +class _BuildContext(NamedTuple): + """What a ``_build_*`` method reads about the node it draws.""" + + parent: tk.Misc + node: dict[str, Any] + kind: str + props: dict[str, Any] + style: dict[str, Any] + enabled: bool + widget_id: str + background: str + pad: int + tk: Any + + class GuiPreview: """Renders an :class:`~pymobile.core.app.App` into a Tk window. @@ -476,7 +502,12 @@ def _clear_toast(self) -> None: # -- widget construction ---------------------------------------------- def _build(self, parent: tk.Misc, node: dict[str, Any]) -> None: - """Create the Tk widget for ``node`` and pack it into ``parent``.""" + """Create the Tk widget for ``node`` and pack it into ``parent``. + + The drawing lives in the ``_build_*`` methods below, one per widget + family; this method keeps the prologue, the custom-renderer hook and + the ``_TK_BUILDERS`` lookup. + """ if not node.get("visible", True): return @@ -507,28 +538,45 @@ def _build(self, parent: tk.Misc, node: dict[str, Any]) -> None: bg=background, ).pack(anchor="w") return - - if kind == "ScrollView": - if props.get("horizontal"): - # No horizontal scrolling in the preview; a plain row keeps the - # arrangement honest, which is what the picture is for. - self._build_row(parent, node, background) - else: - self._build_scroll(parent, node, background) + ctx = _BuildContext( + parent, node, kind, props, style, enabled, widget_id, background, pad, tk + ) + if kind in _EXTRA_GUI_KINDS: + build_extra_gui(self, parent, node, background) return - if kind in ( - "Icon", - "IconButton", - "AutoComplete", - "RangeSlider", - "PageView", - "Chart", - "Canvas", - ): - build_extra_gui(self, parent, node, background) + builder = _TK_BUILDERS.get(kind) + if builder is not None and builder(self, ctx): return + tk.Label(parent, text=f"<{kind}>", fg=self.palette["muted"], bg=background).pack(anchor="w") + + def _build_scroll_view(self, ctx: _BuildContext) -> bool: + """A scroll area, or a plain row when it scrolls sideways.""" + parent = ctx.parent + node = ctx.node + props = ctx.props + background = ctx.background + if props.get("horizontal"): + # No horizontal scrolling in the preview; a plain row keeps the + # arrangement honest, which is what the picture is for. + self._build_row(parent, node, background) + else: + self._build_scroll(parent, node, background) + return True + return True + + def _build_layout(self, ctx: _BuildContext) -> bool: + """The containers: Stack, the columns, a row, a grid and a wrap.""" + parent = ctx.parent + node = ctx.node + kind = ctx.kind + props = ctx.props + style = ctx.style + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk if kind == "Stack": frame = tk.Frame(parent, bg=background) frame.pack(fill="x", pady=pad) @@ -557,8 +605,7 @@ def size_stack(_event: object = None) -> None: frame.after_idle(size_stack) self._widgets[widget_id] = frame self._bind_tap(frame, node, widget_id) - return - + return True if kind in _VERTICAL: frame = tk.Frame(parent, bg=background) frame.pack(fill="both" if kind != "Column" else "x", expand=kind != "Column", pady=pad) @@ -566,54 +613,97 @@ def size_stack(_event: object = None) -> None: # C-3: a tappable container is clickable in the Tk window too, so # the preview shows the same interaction as the phone. self._bind_tap(frame, node, widget_id) - return - + return True if kind == "Row": self._build_row(parent, node, background) - return - + return True if kind == "Grid": self._build_grid(parent, node, props, background) - return - + return True if kind == "Wrap": self._build_wrap(parent, node, props, background) - return + return True + if kind == "RadioGroup": + frame = tk.Frame(parent, bg=background) + frame.pack(fill="x", pady=pad) + self._build_children(frame, node, background) + return True + return False + def _build_ornament(self, ctx: _BuildContext) -> bool: + """Non-interactive decoration: a divider and a spacer.""" + parent = ctx.parent + kind = ctx.kind + props = ctx.props + background = ctx.background + tk = ctx.tk if kind == "Divider": thickness = max(1, int(props.get("thickness", 1))) colour = self.palette["line"] tk.Frame(parent, height=thickness, bg=colour).pack(fill="x", pady=6) - return + return True + if kind == "Spacer": + tk.Frame(parent, height=int(props.get("size", 8)), bg=background).pack() + return True + return False - if kind == "Label": - label = tk.Label( - parent, - text=text_value(props.get("text", "")), - bg=background, - fg=self._colour(style.get("color"), self.palette["text"]), - font=self._font(style), - justify="left", - anchor="w", - wraplength=340, - ) - label.pack(fill="x", pady=pad) - self._widgets[widget_id] = label - return + def _build_label(self, ctx: _BuildContext) -> bool: + """A label.""" + parent = ctx.parent + props = ctx.props + style = ctx.style + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk + label = tk.Label( + parent, + text=text_value(props.get("text", "")), + bg=background, + fg=self._colour(style.get("color"), self.palette["text"]), + font=self._font(style), + justify="left", + anchor="w", + wraplength=340, + ) + label.pack(fill="x", pady=pad) + self._widgets[widget_id] = label + return True + return True - if kind == "Button": - button = tk.Button( - parent, - text=text_value(props.get("text", "")), - font=self._font(style), - state="normal" if enabled else "disabled", - command=lambda: self._dispatch(widget_id, "press", ""), - ) - self._button_colour(button, node) - button.pack(fill="x", pady=pad) - self._widgets[widget_id] = button - return + def _build_button(self, ctx: _BuildContext) -> bool: + """A button.""" + parent = ctx.parent + node = ctx.node + props = ctx.props + style = ctx.style + enabled = ctx.enabled + widget_id = ctx.widget_id + pad = ctx.pad + tk = ctx.tk + button = tk.Button( + parent, + text=text_value(props.get("text", "")), + font=self._font(style), + state="normal" if enabled else "disabled", + command=lambda: self._dispatch(widget_id, "press", ""), + ) + self._button_colour(button, node) + button.pack(fill="x", pady=pad) + self._widgets[widget_id] = button + return True + return True + def _build_text_input(self, ctx: _BuildContext) -> bool: + """Text entry: the text field, the search bar and the pickers.""" + parent = ctx.parent + kind = ctx.kind + props = ctx.props + style = ctx.style + enabled = ctx.enabled + widget_id = ctx.widget_id + pad = ctx.pad + tk = ctx.tk if kind == "TextInput": variable = tk.StringVar(master=self.root, value=text_value(props.get("value", ""))) entry = tk.Entry( @@ -633,8 +723,40 @@ def size_stack(_event: object = None) -> None: self._revisions[widget_id] = int(props.get("revision", 0)) if props.get("placeholder") and not props.get("value"): self._show_placeholder(entry, str(props["placeholder"])) - return + return True + if kind == "SearchBar": + variable = tk.StringVar(master=self.root, value=text_value(props.get("value", ""))) + entry = tk.Entry( + parent, textvariable=variable, state="normal" if enabled else "disabled" + ) + entry.pack(fill="x", pady=pad) + variable.trace_add( + "write", lambda *_: self._dispatch(widget_id, "change", variable.get()) + ) + self._widgets[widget_id] = entry + self._variables[widget_id] = variable + return True + if kind in ("DatePicker", "TimePicker"): + entry = tk.Entry(parent, width=14) + entry.insert(0, text_value(props.get("value", ""))) + entry.bind( + "", + lambda _event, entry=entry: self._dispatch(widget_id, "change", entry.get()), + ) + entry.pack(anchor="w", pady=pad) + return True + return False + def _build_choice(self, ctx: _BuildContext) -> bool: + """On/off choices: a switch, a checkbox and a radio button.""" + parent = ctx.parent + kind = ctx.kind + props = ctx.props + enabled = ctx.enabled + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk if kind == "Switch": variable = tk.BooleanVar(master=self.root, value=bool(props.get("checked"))) toggle = tk.Checkbutton( @@ -651,41 +773,7 @@ def size_stack(_event: object = None) -> None: toggle.pack(fill="x", pady=pad) self._widgets[widget_id] = toggle self._variables[widget_id] = variable - return - - if kind == "ProgressBar": - from tkinter import ttk - - maximum = float(props.get("maximum", 100)) or 100.0 - bar = ttk.Progressbar( - parent, - style="PyMobile.Horizontal.TProgressbar", - maximum=maximum, - value=float(props.get("value", 0)), - mode="indeterminate" if props.get("indeterminate") else "determinate", - ) - bar.pack(fill="x", pady=pad) - if props.get("indeterminate"): - bar.start(60) - self._widgets[widget_id] = bar - return - - if kind == "Image": - image = tk.Label( - parent, - text=f"🖼 {props.get('source', '')}", - fg=self.palette["muted"], - bg=background, - anchor="w", - ) - image.pack(fill="x", pady=pad) - self._widgets[widget_id] = image - return - - if kind == "Spacer": - tk.Frame(parent, height=int(props.get("size", 8)), bg=background).pack() - return - + return True if kind in ("Checkbox",): variable = tk.BooleanVar(master=self.root, value=bool(props.get("checked"))) box = tk.Checkbutton( @@ -701,48 +789,157 @@ def size_stack(_event: object = None) -> None: box.pack(fill="x", pady=pad) self._widgets[widget_id] = box self._variables[widget_id] = variable - return - - if kind == "Slider": - variable = tk.DoubleVar(master=self.root, value=float(props.get("value", 0))) - scale = tk.Scale( + return True + if kind == "RadioButton": + variable = tk.IntVar(master=self.root, value=int(bool(props.get("selected")))) + radio = tk.Radiobutton( parent, - from_=float(props.get("minimum", 0)), - to=float(props.get("maximum", 100)), - orient="horizontal", - resolution=float(props.get("step") or -1), - state="normal" if enabled else "disabled", + text=text_value(props.get("text")), variable=variable, - command=lambda v: self._dispatch(widget_id, "change", str(v)), + value=1, + bg=background, + state="normal" if enabled else "disabled", + command=lambda: self._dispatch(widget_id, "press", ""), ) - scale.pack(fill="x", pady=pad) - self._widgets[widget_id] = scale + radio.pack(anchor="w") self._variables[widget_id] = variable - return + self._widgets[widget_id] = radio + return True + return False + + def _build_indicator(self, ctx: _BuildContext) -> bool: + """Progress, as a bar or as a bar with its text.""" + parent = ctx.parent + kind = ctx.kind + props = ctx.props + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk + if kind == "ProgressBar": + from tkinter import ttk + + maximum = float(props.get("maximum", 100)) or 100.0 + bar = ttk.Progressbar( + parent, + style="PyMobile.Horizontal.TProgressbar", + maximum=maximum, + value=float(props.get("value", 0)), + mode="indeterminate" if props.get("indeterminate") else "determinate", + ) + bar.pack(fill="x", pady=pad) + if props.get("indeterminate"): + bar.start(60) + self._widgets[widget_id] = bar + return True + if kind == "ProgressText": + from tkinter import ttk - if kind == "RatingBar": - maximum = max(1, int(props.get("maximum", 5) or 5)) frame = tk.Frame(parent, bg=background) - frame.pack(anchor="w", pady=pad) - colour = self._colour(style.get("color"), self.palette["text"]) - stars: list[Any] = [] - for number in range(1, maximum + 1): - star = tk.Label(frame, bg=background, fg=colour, font=("TkDefaultFont", 18)) - star.pack(side="left") - if node.get("enabled", True): - star.bind( - "", - lambda _event, n=number: self._dispatch(widget_id, "change", str(float(n))), - ) - stars.append(star) - frame.stars = stars # type: ignore[attr-defined] - self._paint_stars(frame, props.get("rating", 0)) + frame.pack(fill="x", pady=pad) + bar = ttk.Progressbar( + frame, + maximum=float(props.get("maximum", 100)) or 100, + value=float(props.get("value", 0)), + style="PyMobile.Horizontal.TProgressbar", + ) + bar.pack(fill="x") + label = tk.Label(frame, text=text_value(props.get("text")), bg=background, anchor="w") + label.pack(fill="x") + frame.bar = bar + frame.label = label self._widgets[widget_id] = frame - return + return True + return False + + def _build_image(self, ctx: _BuildContext) -> bool: + """A picture placeholder.""" + parent = ctx.parent + props = ctx.props + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk + image = tk.Label( + parent, + text=f"🖼 {props.get('source', '')}", + fg=self.palette["muted"], + bg=background, + anchor="w", + ) + image.pack(fill="x", pady=pad) + self._widgets[widget_id] = image + return True + return True + + def _build_slider(self, ctx: _BuildContext) -> bool: + """A slider.""" + parent = ctx.parent + props = ctx.props + enabled = ctx.enabled + widget_id = ctx.widget_id + pad = ctx.pad + tk = ctx.tk + variable = tk.DoubleVar(master=self.root, value=float(props.get("value", 0))) + scale = tk.Scale( + parent, + from_=float(props.get("minimum", 0)), + to=float(props.get("maximum", 100)), + orient="horizontal", + resolution=float(props.get("step") or -1), + state="normal" if enabled else "disabled", + variable=variable, + command=lambda v: self._dispatch(widget_id, "change", str(v)), + ) + scale.pack(fill="x", pady=pad) + self._widgets[widget_id] = scale + self._variables[widget_id] = variable + return True + return True + def _build_rating(self, ctx: _BuildContext) -> bool: + """A rating bar as a row of stars.""" + parent = ctx.parent + node = ctx.node + props = ctx.props + style = ctx.style + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk + maximum = max(1, int(props.get("maximum", 5) or 5)) + frame = tk.Frame(parent, bg=background) + frame.pack(anchor="w", pady=pad) + colour = self._colour(style.get("color"), self.palette["text"]) + stars: list[Any] = [] + for number in range(1, maximum + 1): + star = tk.Label(frame, bg=background, fg=colour, font=("TkDefaultFont", 18)) + star.pack(side="left") + if node.get("enabled", True): + star.bind( + "", + lambda _event, n=number: self._dispatch(widget_id, "change", str(float(n))), + ) + stars.append(star) + frame.stars = stars # type: ignore[attr-defined] + self._paint_stars(frame, props.get("rating", 0)) + self._widgets[widget_id] = frame + return True + return True + + def _build_options(self, ctx: _BuildContext) -> bool: + """A fixed list of options: a drop-down and segmented buttons.""" + parent = ctx.parent + kind = ctx.kind + props = ctx.props + enabled = ctx.enabled + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk if kind == "Dropdown": - # П-11: ``options`` is the list of values; ``labels`` is the - # parallel list of visible strings (falls back to the value). + # ``options`` is the list of values; ``labels`` is the parallel + # list of visible strings (falls back to the value). option_values = [str(o) for o in (props.get("options") or [])] option_labels = [str(lbl) for lbl in (props.get("labels") or option_values)] while len(option_labels) < len(option_values): @@ -770,86 +967,7 @@ def _pick( menu.pack(fill="x", pady=pad) self._widgets[widget_id] = menu self._variables[widget_id] = variable - return - - if kind == "Chip": - button = tk.Button( - parent, - text=text_value(props.get("text")), - state="normal" if enabled else "disabled", - command=lambda: self._dispatch(widget_id, "press", ""), - ) - self._chip_colour(button, node) - button.pack(anchor="w", pady=pad) - self._widgets[widget_id] = button - return - - if kind in ("Badge", "Avatar"): - canvas = tk.Canvas(parent, bg=background, highlightthickness=0) - canvas.pack(anchor="w", pady=pad) - self._widgets[widget_id] = canvas - self._paint_identity(canvas, node) - return - - if kind == "Stepper": - frame = tk.Frame(parent, bg=background) - frame.pack(fill="x", pady=pad) - minus = tk.Button( - frame, - text="-", - state="normal" if enabled else "disabled", - command=lambda: self._dispatch(widget_id, "decrement", ""), - ) - minus.pack(side="left") - label = tk.Label(frame, text=text_value(props.get("value", 0)), bg=background) - label.pack(side="left", padx=8) - plus = tk.Button( - frame, - text="+", - state="normal" if enabled else "disabled", - command=lambda: self._dispatch(widget_id, "increment", ""), - ) - plus.pack(side="left") - frame.label = label - frame.buttons = [minus, plus] - self._widgets[widget_id] = frame - return - - if kind == "SearchBar": - variable = tk.StringVar(master=self.root, value=text_value(props.get("value", ""))) - entry = tk.Entry( - parent, textvariable=variable, state="normal" if enabled else "disabled" - ) - entry.pack(fill="x", pady=pad) - variable.trace_add( - "write", lambda *_: self._dispatch(widget_id, "change", variable.get()) - ) - self._widgets[widget_id] = entry - self._variables[widget_id] = variable - return - - if kind == "RadioButton": - variable = tk.IntVar(master=self.root, value=int(bool(props.get("selected")))) - radio = tk.Radiobutton( - parent, - text=text_value(props.get("text")), - variable=variable, - value=1, - bg=background, - state="normal" if enabled else "disabled", - command=lambda: self._dispatch(widget_id, "press", ""), - ) - radio.pack(anchor="w") - self._variables[widget_id] = variable - self._widgets[widget_id] = radio - return - - if kind == "RadioGroup": - frame = tk.Frame(parent, bg=background) - frame.pack(fill="x", pady=pad) - self._build_children(frame, node, background) - return - + return True if kind == "SegmentedButtons": frame = tk.Frame(parent, bg=background) frame.pack(fill="x", pady=pad) @@ -875,152 +993,231 @@ def _pick( self._widgets[widget_id] = frame if wrap: self._flow(frame, buttons, 0, 0, "start") - return + return True + return False - if kind == "ProgressText": - from tkinter import ttk + def _build_chip(self, ctx: _BuildContext) -> bool: + """A chip.""" + parent = ctx.parent + node = ctx.node + props = ctx.props + enabled = ctx.enabled + widget_id = ctx.widget_id + pad = ctx.pad + tk = ctx.tk + button = tk.Button( + parent, + text=text_value(props.get("text")), + state="normal" if enabled else "disabled", + command=lambda: self._dispatch(widget_id, "press", ""), + ) + self._chip_colour(button, node) + button.pack(anchor="w", pady=pad) + self._widgets[widget_id] = button + return True + return True - frame = tk.Frame(parent, bg=background) - frame.pack(fill="x", pady=pad) - bar = ttk.Progressbar( - frame, - maximum=float(props.get("maximum", 100)) or 100, - value=float(props.get("value", 0)), - style="PyMobile.Horizontal.TProgressbar", - ) - bar.pack(fill="x") - label = tk.Label(frame, text=text_value(props.get("text")), bg=background, anchor="w") - label.pack(fill="x") - frame.bar = bar - frame.label = label - self._widgets[widget_id] = frame - return + def _build_identity(self, ctx: _BuildContext) -> bool: + """A badge or an avatar, painted on a canvas.""" + parent = ctx.parent + node = ctx.node + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk + canvas = tk.Canvas(parent, bg=background, highlightthickness=0) + canvas.pack(anchor="w", pady=pad) + self._widgets[widget_id] = canvas + self._paint_identity(canvas, node) + return True + return True - if kind == "Link": - tk.Button( - parent, - text=text_value(props.get("text", "")), - fg="#3F51B5", - relief="flat", - command=lambda: self._dispatch(widget_id, "press", ""), - ).pack(anchor="w") - return + def _build_stepper(self, ctx: _BuildContext) -> bool: + """A stepper with its minus and plus buttons.""" + parent = ctx.parent + props = ctx.props + enabled = ctx.enabled + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk + frame = tk.Frame(parent, bg=background) + frame.pack(fill="x", pady=pad) + minus = tk.Button( + frame, + text="-", + state="normal" if enabled else "disabled", + command=lambda: self._dispatch(widget_id, "decrement", ""), + ) + minus.pack(side="left") + label = tk.Label(frame, text=text_value(props.get("value", 0)), bg=background) + label.pack(side="left", padx=8) + plus = tk.Button( + frame, + text="+", + state="normal" if enabled else "disabled", + command=lambda: self._dispatch(widget_id, "increment", ""), + ) + plus.pack(side="left") + frame.label = label + frame.buttons = [minus, plus] + self._widgets[widget_id] = frame + return True + return True + + def _build_link(self, ctx: _BuildContext) -> bool: + """A link.""" + parent = ctx.parent + props = ctx.props + widget_id = ctx.widget_id + tk = ctx.tk + tk.Button( + parent, + text=text_value(props.get("text", "")), + fg="#3F51B5", + relief="flat", + command=lambda: self._dispatch(widget_id, "press", ""), + ).pack(anchor="w") + return True + return True - if kind == "DataTable": - headers = " | ".join(str(h) for h in (props.get("headers") or [])) + def _build_data_table(self, ctx: _BuildContext) -> bool: + """A data table: a header line and one line per record.""" + parent = ctx.parent + props = ctx.props + background = ctx.background + tk = ctx.tk + headers = " | ".join(str(h) for h in (props.get("headers") or [])) + tk.Label( + parent, + text=headers, + bg=background, + anchor="w", + font=("TkDefaultFont", 9, "bold"), + ).pack(fill="x") + for row in props.get("rows") or []: tk.Label( parent, - text=headers, + text=" | ".join(str(c) for c in row), bg=background, anchor="w", - font=("TkDefaultFont", 9, "bold"), ).pack(fill="x") - for row in props.get("rows") or []: - tk.Label( - parent, - text=" | ".join(str(c) for c in row), - bg=background, - anchor="w", - ).pack(fill="x") - return + return True + return True - if kind in ("List", "ListTile"): - if kind == "List": - frame = tk.Frame(parent, bg=background) - frame.pack(fill="both", expand=True, pady=pad) - if props.get("refreshable"): - # A mouse cannot pull: the gesture becomes a button. - refreshing = bool(props.get("refreshing")) - tk.Button( - frame, - text="⟳ Refreshing…" if refreshing else "↻ Pull to refresh", - state="disabled" if refreshing else "normal", - command=lambda: self._dispatch(widget_id, "refresh", ""), - ).pack(fill="x", pady=pad) - self._build_children(frame, node, background) - if props.get("has_more"): - loaded = text_value(props.get("loaded", len(node.get("children", ())))) + def _build_list(self, ctx: _BuildContext) -> bool: + """A list, and the list rows it is made of.""" + parent = ctx.parent + node = ctx.node + kind = ctx.kind + props = ctx.props + enabled = ctx.enabled + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk + if kind == "List": + frame = tk.Frame(parent, bg=background) + frame.pack(fill="both", expand=True, pady=pad) + if props.get("refreshable"): + # A mouse cannot pull: the gesture becomes a button. + refreshing = bool(props.get("refreshing")) + tk.Button( + frame, + text="⟳ Refreshing…" if refreshing else "↻ Pull to refresh", + state="disabled" if refreshing else "normal", + command=lambda: self._dispatch(widget_id, "refresh", ""), + ).pack(fill="x", pady=pad) + self._build_children(frame, node, background) + if props.get("has_more"): + loaded = text_value(props.get("loaded", len(node.get("children", ())))) + tk.Button( + frame, + text=f"Load more ({loaded} of {props.get('item_count', '?')})", + command=lambda: self._dispatch(widget_id, "load_more", loaded), + ).pack(fill="x", pady=pad) + return True + holder = parent + if props.get("swipe_left") or props.get("swipe_right"): + holder = tk.Frame(parent, bg=background) + holder.pack(fill="x", pady=pad) + for direction, arrow in (("left", "⟵"), ("right", "⟶")): + if props.get(f"swipe_{direction}"): tk.Button( - frame, - text=f"Load more ({loaded} of {props.get('item_count', '?')})", - command=lambda: self._dispatch(widget_id, "load_more", loaded), - ).pack(fill="x", pady=pad) - return - holder = parent - if props.get("swipe_left") or props.get("swipe_right"): - holder = tk.Frame(parent, bg=background) - holder.pack(fill="x", pady=pad) - for direction, arrow in (("left", "⟵"), ("right", "⟶")): - if props.get(f"swipe_{direction}"): - tk.Button( - holder, - text=arrow, - bg=self._colour(props.get(f"swipe_{direction}_color"), "#757575"), - fg="#FFFFFF", - command=lambda d=direction: self._dispatch(widget_id, "swipe", d), - ).pack(side="right") - tile = tk.Button( - holder, - text=self._tile_text(props), - state="normal" if enabled else "disabled", - command=lambda: self._dispatch(widget_id, "press", ""), - anchor="w", - ) - self._widgets[widget_id] = tile - if holder is parent: - tile.pack(fill="x", pady=pad) - else: - tile.pack(side="left", fill="x", expand=True) - if props.get("long_pressable"): - # Right click stands in for touch-and-hold in the Tk window. - tile.bind( - "", - lambda _event, wid=widget_id: self._dispatch(wid, "long_press", ""), - ) - return - - if kind == "BottomNavigation": - bar = tk.Frame(parent, bg=background) - bar.pack(fill="x", pady=pad) - option_values = [str(o) for o in (props.get("options") or [])] - option_labels = [str(lbl) for lbl in (props.get("labels") or option_values)] - while len(option_labels) < len(option_values): - option_labels.append(option_values[len(option_labels)]) - buttons = [] - for val, lbl in zip(option_values, option_labels, strict=False): - selected = val == props.get("value") - button = tk.Button( - bar, - text=lbl, - relief="sunken" if selected else "raised", - command=lambda v=val: self._dispatch(widget_id, "change", v), - ) - button.pack(side="left", expand=True, fill="x") - buttons.append(button) - bar.buttons = buttons - self._selection(bar, props, "normal" if enabled else "disabled") - self._widgets[widget_id] = bar - return - - if kind == "Dialog": - box = tk.LabelFrame( - parent, text=text_value(props.get("title", "")), bg=background, padx=8, pady=8 + holder, + text=arrow, + bg=self._colour(props.get(f"swipe_{direction}_color"), "#757575"), + fg="#FFFFFF", + command=lambda d=direction: self._dispatch(widget_id, "swipe", d), + ).pack(side="right") + tile = tk.Button( + holder, + text=self._tile_text(props), + state="normal" if enabled else "disabled", + command=lambda: self._dispatch(widget_id, "press", ""), + anchor="w", + ) + self._widgets[widget_id] = tile + if holder is parent: + tile.pack(fill="x", pady=pad) + else: + tile.pack(side="left", fill="x", expand=True) + if props.get("long_pressable"): + # Right click stands in for touch-and-hold in the Tk window. + tile.bind( + "", + lambda _event, wid=widget_id: self._dispatch(wid, "long_press", ""), ) - box.pack(fill="x", pady=pad, side="bottom" if props.get("sheet") else "top") - self._build_children(box, node, background) - return + return True + return True - if kind in ("DatePicker", "TimePicker"): - entry = tk.Entry(parent, width=14) - entry.insert(0, text_value(props.get("value", ""))) - entry.bind( - "", - lambda _event, entry=entry: self._dispatch(widget_id, "change", entry.get()), + def _build_bottom_navigation(self, ctx: _BuildContext) -> bool: + """The bottom navigation bar and its tabs.""" + parent = ctx.parent + props = ctx.props + enabled = ctx.enabled + widget_id = ctx.widget_id + background = ctx.background + pad = ctx.pad + tk = ctx.tk + bar = tk.Frame(parent, bg=background) + bar.pack(fill="x", pady=pad) + option_values = [str(o) for o in (props.get("options") or [])] + option_labels = [str(lbl) for lbl in (props.get("labels") or option_values)] + while len(option_labels) < len(option_values): + option_labels.append(option_values[len(option_labels)]) + buttons = [] + for val, lbl in zip(option_values, option_labels, strict=False): + selected = val == props.get("value") + button = tk.Button( + bar, + text=lbl, + relief="sunken" if selected else "raised", + command=lambda v=val: self._dispatch(widget_id, "change", v), ) - entry.pack(anchor="w", pady=pad) - return + button.pack(side="left", expand=True, fill="x") + buttons.append(button) + bar.buttons = buttons + self._selection(bar, props, "normal" if enabled else "disabled") + self._widgets[widget_id] = bar + return True + return True - tk.Label(parent, text=f"<{kind}>", fg=self.palette["muted"], bg=background).pack(anchor="w") + def _build_dialog(self, ctx: _BuildContext) -> bool: + """A dialog or a sheet, drawn as a framed box.""" + parent = ctx.parent + node = ctx.node + props = ctx.props + background = ctx.background + pad = ctx.pad + tk = ctx.tk + box = tk.LabelFrame( + parent, text=text_value(props.get("title", "")), bg=background, padx=8, pady=8 + ) + box.pack(fill="x", pady=pad, side="bottom" if props.get("sheet") else "top") + self._build_children(box, node, background) + return True + return True def _build_children(self, frame: tk.Misc, node: dict[str, Any], background: str) -> None: """Stack children vertically, honouring the container's spacing.""" @@ -1175,10 +1372,70 @@ def _flex_of(self, node: dict[str, Any]) -> int: weight = node.get("style", {}).get("weight") return int(weight) if weight else 0 - def _font(self, style: dict[str, Any]) -> tuple[str, int, str]: + def _font(self, style: dict[str, Any]) -> tuple[Any, ...]: + """The Tk font descriptor for a serialised Style. + + A named family has to be a *real* installed family: Tk silently keeps + the previous font otherwise, and a mockup that quietly ignores + ``font_family`` is worse than one that does not offer it. So the family + is resolved through ``tkinter.font.families()`` and an unknown name + falls back to the default — with the slant and underline flags Python + always supported and the desktop window never applied. + """ size = int(style.get("font_size", 11)) weight = "bold" if style.get("bold") else "normal" - return ("TkDefaultFont", max(7, size), weight) + slant = "italic" if style.get("italic") else "roman" + underline = bool(style.get("underline")) + strike = bool(style.get("strikethrough")) + family = self._family(style.get("font_family")) + needs_options = slant != "roman" or underline or strike + if needs_options: + overstrike = 1 if strike else 0 + return (family, max(7, size), weight, slant, int(underline), overstrike) + return ( + (family, max(7, size), weight) + if family != "TkDefaultFont" + else ( + "TkDefaultFont", + max(7, size), + weight, + ) + ) + + def _family(self, requested: Any) -> str: + """Resolve ``Style(font_family=…)`` against the families Tk really has.""" + if not isinstance(requested, str) or not requested.strip(): + return "TkDefaultFont" + from tkinter import font as tkfont + + try: + available = {name.lower(): name for name in tkfont.families(self.root)} + except Exception: # pragma: no cover - a Tk without font support + return "TkDefaultFont" + for name in requested.split(","): + wanted = name.strip().strip("'\"").lower() + if not wanted: + continue + if wanted in available: + return available[wanted] + without_spaces = {name.replace(" ", "").lower(): name for name in available} + if wanted.replace(" ", "") in without_spaces: + return without_spaces[wanted.replace(" ", "")] + # Tk reports family names with spaces ("DejaVu Serif"), so compare + # without them: a lookup table of squashed names never matched. + squashed = {name.replace(" ", "").lower(): name for name in available} + alias = { + "serif": ("dejavuserif", "times", "georgia", "liberationserif", "notoserif"), + "monospace": ("dejavusansmono", "courier", "consolas", "liberationmono"), + "sans-serif": ("dejavusans", "arial", "helvetica", "liberationsans"), + }.get(wanted, ()) + for candidate in alias: + if candidate in squashed: + return squashed[candidate] + for candidate in alias: + if candidate in available: + return available[candidate] + return "TkDefaultFont" def _colour(self, value: Any, fallback: str) -> str: """Translate a framework colour into one Tk understands.""" @@ -1192,6 +1449,7 @@ def _background(self, style: dict[str, Any]) -> str: @property def palette(self) -> dict[str, str]: + """The colours of the current preview theme.""" return getattr(self, "_palette", _PALETTE) def _sync_theme(self) -> bool: @@ -1405,3 +1663,48 @@ def run_gui( on_ready(preview) preview.run() return preview + + +#: Which ``_build_*`` method draws which widget type. A method that draws +#: several kinds keeps one guard per kind and returns False for the rest. +_TK_BUILDERS: dict[str, Callable[[GuiPreview, _BuildContext], bool]] = { + "ScrollView": GuiPreview._build_scroll_view, + "Stack": GuiPreview._build_layout, + "Column": GuiPreview._build_layout, + "Container": GuiPreview._build_layout, + "SafeArea": GuiPreview._build_layout, + "Expanded": GuiPreview._build_layout, + "Flexible": GuiPreview._build_layout, + "Row": GuiPreview._build_layout, + "Grid": GuiPreview._build_layout, + "Wrap": GuiPreview._build_layout, + "RadioGroup": GuiPreview._build_layout, + "Divider": GuiPreview._build_ornament, + "Spacer": GuiPreview._build_ornament, + "Label": GuiPreview._build_label, + "Button": GuiPreview._build_button, + "TextInput": GuiPreview._build_text_input, + "SearchBar": GuiPreview._build_text_input, + "DatePicker": GuiPreview._build_text_input, + "TimePicker": GuiPreview._build_text_input, + "Switch": GuiPreview._build_choice, + "Checkbox": GuiPreview._build_choice, + "RadioButton": GuiPreview._build_choice, + "ProgressBar": GuiPreview._build_indicator, + "ProgressText": GuiPreview._build_indicator, + "Image": GuiPreview._build_image, + "Slider": GuiPreview._build_slider, + "RatingBar": GuiPreview._build_rating, + "Dropdown": GuiPreview._build_options, + "SegmentedButtons": GuiPreview._build_options, + "Chip": GuiPreview._build_chip, + "Badge": GuiPreview._build_identity, + "Avatar": GuiPreview._build_identity, + "Stepper": GuiPreview._build_stepper, + "Link": GuiPreview._build_link, + "DataTable": GuiPreview._build_data_table, + "List": GuiPreview._build_list, + "ListTile": GuiPreview._build_list, + "BottomNavigation": GuiPreview._build_bottom_navigation, + "Dialog": GuiPreview._build_dialog, +} diff --git a/pymobile/core/ui/layout.py b/pymobile/core/ui/layout.py index 377ae09..32f96c7 100644 --- a/pymobile/core/ui/layout.py +++ b/pymobile/core/ui/layout.py @@ -68,6 +68,7 @@ def __init__( super().__init__(*children, **kwargs) def props(self) -> dict[str, Any]: + """The serialised props: spacing and the two alignments.""" props = {**super().props(), "spacing": self.spacing, "align": self.align} if self.cross_align is not None: props["cross_align"] = self.cross_align @@ -113,6 +114,7 @@ def __init__( super().__init__(*children, **kwargs) def props(self) -> dict[str, Any]: + """The serialised props: the spacing and the scroll direction.""" return {**super().props(), "horizontal": self.horizontal, "spacing": self.spacing} @@ -172,6 +174,7 @@ def rows(self) -> int: return -(-len(self.children) // self.columns) # ceil division def props(self) -> dict[str, Any]: + """The serialised props: the column count and both gaps.""" return { **super().props(), "columns": self.columns, @@ -222,6 +225,7 @@ def __init__( super().__init__(*children, **kwargs) def props(self) -> dict[str, Any]: + """The serialised props: the gaps and the alignment of each run.""" return { **super().props(), "spacing": self.spacing, @@ -265,6 +269,7 @@ def child(self) -> Widget: return self.children[0] def props(self) -> dict[str, Any]: + """The serialised props: the flex factor and the fit mode.""" return {**super().props(), "flex": self.flex, "fit": self.fit} @@ -329,6 +334,7 @@ def __init__( self.vertical = vertical def props(self) -> dict[str, Any]: + """The serialised props: thickness, inset, colour and orientation.""" return { **super().props(), "thickness": self.thickness, @@ -375,6 +381,7 @@ def __init__( super().__init__(*children, **kwargs) def props(self) -> dict[str, Any]: + """The serialised props: which edges to inset and by how much.""" return { **super().props(), "top": self.top, diff --git a/pymobile/core/ui/list.py b/pymobile/core/ui/list.py index 5b16e49..9e71191 100644 --- a/pymobile/core/ui/list.py +++ b/pymobile/core/ui/list.py @@ -98,7 +98,7 @@ def __init__( #: Number of rows built so far (set before item_count: its setter clamps it). self._window = 0 self._item_count = 0 - self.item_count = item_count # validated by the property setter + self.item_count = item_count # validated by the property setter self.spacing = spacing self.visible_count = visible_count self._window = min(item_count, visible_count) @@ -136,6 +136,7 @@ def item_count(self) -> int: @item_count.setter def item_count(self, value: int) -> None: + """How many rows the list holds in total, including the ones not built yet.""" if isinstance(value, bool) or not isinstance(value, int): raise TypeError(f"item_count must be an int, got {type(value).__name__}") if value < 0: @@ -190,9 +191,11 @@ def _ui_load_more(self, value: str = "") -> None: # Override add/clear so users cannot disturb the lazily built children. def add(self, child: Widget) -> Widget: # pragma: no cover - defensive + """Append a row to the list.""" raise ValueError("List builds its rows itself; set item_count and call refresh()") def clear(self) -> None: # pragma: no cover - defensive + """Remove every row from the list.""" raise ValueError("List builds its rows itself; set item_count and call refresh()") def refresh(self) -> None: @@ -239,6 +242,7 @@ def refreshing(self) -> bool: @refreshing.setter def refreshing(self, value: bool) -> None: + """Whether the pull-to-refresh indicator is showing.""" value = bool(value) if value != self._refreshing: self._refreshing = value @@ -283,6 +287,7 @@ def _ui_refresh(self, value: str = "") -> None: self.pull_to_refresh() def props(self) -> dict[str, Any]: + """The serialised props: paging, refresh state and the refresh callback.""" return { **super().props(), "item_count": self.item_count, @@ -371,6 +376,7 @@ def title(self) -> str: @title.setter def title(self, value: str) -> None: + """The main line of the row.""" value = text_value(value) if value != self._title: self._title = value @@ -387,6 +393,7 @@ def subtitle(self) -> str: @subtitle.setter def subtitle(self, value: str) -> None: + """The second line of the row.""" value = text_value(value) if value != self._subtitle: self._subtitle = value @@ -399,6 +406,7 @@ def trailing(self) -> str: @trailing.setter def trailing(self, value: str) -> None: + """The short text at the end of the row.""" value = text_value(value) if value != self._trailing: self._trailing = value @@ -433,6 +441,7 @@ def _ui_swipe(self, value: str) -> None: raise ValueError(f"unknown swipe direction {value!r}") def props(self) -> dict[str, Any]: + """The serialised props: the three lines, the swipes and the two callbacks.""" return { **super().props(), "title": self._title, diff --git a/pymobile/core/ui/navigation.py b/pymobile/core/ui/navigation.py index 132b073..5048ebf 100644 --- a/pymobile/core/ui/navigation.py +++ b/pymobile/core/ui/navigation.py @@ -32,7 +32,7 @@ class BottomNavigation(Widget): ) Options may also be ``(value, label)`` pairs for stable identifiers with - localised labels (П-11). + localised labels. """ type_name = "BottomNavigation" @@ -64,6 +64,7 @@ def value(self) -> str: @value.setter def value(self, value: str) -> None: + """The key of the selected tab; assigning it behaves like tapping it.""" self.select(value) @property @@ -85,7 +86,7 @@ def select(self, value: str) -> None: self._value = value self.invalidate() # Picking the initial tab while build() assembles the shell must not - # call the handler: it is the trap BUG-25 removed everywhere else. + # call the handler: the same trap that is closed everywhere else. if self.on_select is not None and not in_build_scope(): self.on_select(value) @@ -94,6 +95,7 @@ def set_value(self, value: str) -> None: self.select(value) def props(self) -> dict[str, Any]: + """The serialised props: the tabs, their labels, the selection and the callback.""" return { **super().props(), "options": list(self.options), diff --git a/pymobile/core/ui/patterns.py b/pymobile/core/ui/patterns.py index dd4e623..89c895d 100644 --- a/pymobile/core/ui/patterns.py +++ b/pymobile/core/ui/patterns.py @@ -105,6 +105,7 @@ def _repair(self) -> None: child._parent = node def to_dict(self) -> WidgetNode: + """The serialised node, after closing any holes left by a removed child.""" self._repair() node = super().to_dict() if not self.enabled: @@ -151,6 +152,7 @@ def __init__( super().__init__(*contents, style=resolved, **kwargs) def to_dict(self) -> WidgetNode: + """The serialised card, with its title, actions and corner radius.""" node = super().to_dict() if self._theme_background and self.style.background is None: node.setdefault("style", {})["background"] = theme_color(self, "SURFACE") @@ -244,25 +246,31 @@ def __init__( @property def value(self) -> str: + """The text the user has typed so far.""" return self.input.value @value.setter def value(self, value: str) -> None: + """The text the user has typed so far.""" self.input.value = value def set_value(self, value: str) -> None: + """Replace the field's text without running the change callbacks.""" self.value = value @property def error(self) -> str: + """The error message shown under the field, or an empty string.""" return self._error @property def dirty(self) -> bool: + """Whether the value differs from the one the field started with.""" return self._dirty @property def touched(self) -> bool: + """Whether the user has edited the field at least once.""" return self._touched def _sync(self) -> None: @@ -274,6 +282,7 @@ def _sync(self) -> None: self._error_widget._visible = bool(self.error) def set_error(self, error: str | None) -> None: + """Show ``error`` under the field, or clear it when it is ``None``.""" text = "" if error is None else str(error) if text != self._error: self._error = text @@ -302,6 +311,7 @@ def validate(self) -> bool: return not errors def reset(self, value: str | None = None) -> None: + """Return the field to ``value`` (or the value it started with) and clear its flags.""" text = self._initial if value is None else str(value) if self.input.max_length is not None: text = text[: self.input.max_length] @@ -312,6 +322,7 @@ def reset(self, value: str | None = None) -> None: self.invalidate() def to_dict(self) -> WidgetNode: + """The serialised field: its label, hint, control and current error.""" self._sync() node = super().to_dict() for child in node.get("children", []): @@ -367,10 +378,12 @@ def __init__( @property def values(self) -> dict[str, str]: + """The current value of every field, keyed by field name.""" return {field.name: field.value for field in self.fields} @property def errors(self) -> dict[str, str]: + """The current validation errors, keyed by field name.""" return dict(self._errors) def set_errors(self, errors: Mapping[str, str]) -> None: @@ -414,6 +427,7 @@ def _field_changed(self, name: str, _value: str) -> None: self.validate() def validate(self) -> bool: + """Run every rule and the form validator, show the errors it found, and report validity.""" local_errors = self.validator.validate(self.values) errors = {**local_errors, **self._external_errors} with self._batch(): @@ -425,6 +439,7 @@ def validate(self) -> bool: return not errors def submit(self) -> bool: + """Validate the form and, when it is valid, call ``on_submit`` with the values.""" if not self.enabled or not self.validate(): return False if self.on_submit is not None and not in_build_scope(): @@ -432,6 +447,7 @@ def submit(self) -> bool: return True def reset(self, values: Mapping[str, str] | None = None) -> None: + """Clear every field and error, optionally writing ``values`` first.""" if values is not None and set(values) - {field.name for field in self.fields}: raise ValueError("reset contains unknown field names") with self._batch(): @@ -444,6 +460,7 @@ def reset(self, values: Mapping[str, str] | None = None) -> None: def to_dict(self) -> WidgetNode: # Re-evaluate existing messages when the language changes, without # changing touched state or firing callbacks during rendering. + """The serialised form, including one child per field.""" if self._errors or self._external_errors: local_errors = self.validator.validate(self.values) self._errors = {**local_errors, **self._external_errors} @@ -494,10 +511,12 @@ def __init__( @property def value(self) -> str: + """The key of the tab that is currently open.""" return self._value @value.setter def value(self, value: str) -> None: + """The key of the tab that is currently open.""" self.select(value) def _update_labels(self, labels: Mapping[str, str]) -> None: @@ -506,6 +525,7 @@ def _update_labels(self, labels: Mapping[str, str]) -> None: self._labels.update({key: str(label) for key, label in labels.items()}) def set_labels(self, labels: Mapping[str, str]) -> None: + """Rename the tabs; every key in ``labels`` must already be a tab.""" self._update_labels(labels) self._rebuild() @@ -538,6 +558,7 @@ def _rebuild(self, *, notify: bool = True, content: Widget | None = None) -> Non self._replace((header, page), notify=notify) def select(self, key: str) -> None: + """Open the tab called ``key`` and notify ``on_select``.""" if key not in self._tabs: raise ValueError(f"unknown tab key {key!r}") if key == self._value: @@ -551,6 +572,7 @@ def select(self, key: str) -> None: self.on_select(key) def set_value(self, value: str) -> None: + """Open the tab called ``value`` (the bridge's name for :meth:`select`).""" self.select(value) def _ui_set_value(self, value: str) -> None: @@ -559,6 +581,7 @@ def _ui_set_value(self, value: str) -> None: def to_dict(self) -> WidgetNode: # Recolor kept tab headers without recreating the content/state. + """The serialised tab view: the label row, then the open page.""" header = self.children[0] for button, key in zip(header.children[0].children, self._tabs, strict=True): object.__setattr__( @@ -612,10 +635,12 @@ def __init__( @property def expanded(self) -> bool: + """Whether the panel is open.""" return self._expanded @expanded.setter def expanded(self, value: bool) -> None: + """Whether the panel is open.""" self.set_expanded(value) def _sync(self) -> None: @@ -623,6 +648,7 @@ def _sync(self) -> None: self._content._visible = self.expanded def set_expanded(self, value: bool, *, notify: bool = True) -> None: + """Open or close the panel, rebuilding it and notifying ``on_toggle``.""" if not isinstance(value, bool): raise TypeError("expanded must be a bool") if value != self._expanded: @@ -633,10 +659,12 @@ def set_expanded(self, value: bool, *, notify: bool = True) -> None: self.on_toggle(value) def toggle(self) -> None: + """Flip the panel between open and closed.""" if self.enabled: self.set_expanded(not self.expanded) def to_dict(self) -> WidgetNode: + """The serialised panel, with its title updated to the open state.""" self._sync() return super().to_dict() @@ -673,6 +701,7 @@ def __init__( @property def expanded(self) -> tuple[str, ...]: + """The ids of the panels that are currently open.""" return tuple(panel.id for panel in self.panels if panel.expanded) def _panel_changed( @@ -744,6 +773,7 @@ def __init__( super().__init__(*children, **kwargs) def to_dict(self) -> WidgetNode: + """The serialised placeholder, with one bar per line.""" node = super().to_dict() screen = self.screen dark = screen is not None and screen.mounted and screen.app.theme.is_dark @@ -804,13 +834,16 @@ def _normalise(self, value: Sequence[str]) -> tuple[str, ...]: @property def value(self) -> tuple[str, ...]: + """The keys of the options that are selected, in selection order.""" return self._value @value.setter def value(self, value: Sequence[str]) -> None: + """The keys of the options that are selected, in selection order.""" self.set_value(value) def set_value(self, value: Sequence[str]) -> None: + """Select the options named in ``value`` and notify ``on_change``.""" new = self._normalise(value) if new != self._value: self._value = new @@ -821,6 +854,7 @@ def set_value(self, value: Sequence[str]) -> None: self.on_change(new) def toggle(self, key: str) -> None: + """Select the option ``key`` if it is not selected, otherwise deselect it.""" if not self.enabled: return if key not in self._options: @@ -835,9 +869,11 @@ def toggle(self, key: str) -> None: self.set_value(tuple(selected)) def clear_selection(self) -> None: + """Deselect every option.""" self.set_value(()) def set_labels(self, labels: Mapping[str, str]) -> None: + """Rename the options; every key in ``labels`` must already be an option.""" if set(labels) - set(self._options): raise ValueError("labels contains unknown option keys") with self._batch(): @@ -932,17 +968,21 @@ def __init__( @property def value(self) -> str: + """The selected date as ``YYYY-MM-DD``, or an empty string.""" return self._value @value.setter def value(self, value: str) -> None: + """The selected date as ``YYYY-MM-DD``, or an empty string.""" self.set_value(value) @property def month(self) -> str: + """The month on screen as ``YYYY-MM``.""" return self._month.isoformat()[:7] def is_disabled(self, date: _dt.date) -> bool: + """Whether ``date`` falls on a disabled day or outside the allowed range.""" return bool( (self.minimum and date < self.minimum) or (self.maximum and date > self.maximum) @@ -950,6 +990,7 @@ def is_disabled(self, date: _dt.date) -> bool: ) def set_value(self, value: str) -> None: + """Select an ISO date, refresh the grid and notify ``on_change``.""" if value: parsed = _iso(value) if self.is_disabled(parsed): @@ -969,6 +1010,7 @@ def _choose(self, value: str) -> None: self.on_select(value) def show_month(self, year: int, month: int) -> None: + """Scroll the grid to the given month without changing the selection.""" if isinstance(year, bool) or isinstance(month, bool): raise TypeError("year and month must be ints") new = _dt.date(year, month, 1) @@ -1062,6 +1104,7 @@ def _rebuild(self, *, notify: bool = True) -> None: def to_dict(self) -> WidgetNode: # Fresh locale/theme descriptions, stable explicit ids and unchanged state. + """The serialised calendar, rebuilt for the month on screen.""" self._rebuild(notify=False) return super().to_dict() @@ -1145,14 +1188,17 @@ def _normalise(self, value: Sequence[str]) -> tuple[str, str]: @property def value(self) -> tuple[str, str]: + """The chosen range: one ISO date, or two when both ends are picked.""" return self._value @value.setter def value(self, value: Sequence[str]) -> None: + """The chosen range: one ISO date, or two when both ends are picked.""" self.set_value(value) @property def complete(self) -> bool: + """Whether both ends of the range have been chosen.""" return bool(self._value[0] and self._value[1]) def _sync(self) -> None: @@ -1165,6 +1211,7 @@ def _sync(self) -> None: self.calendar._rebuild(notify=False) def set_value(self, value: Sequence[str]) -> None: + """Set the range, refresh the calendar and notify ``on_change``.""" new = self._normalise(value) if new != self._value: self._value = new @@ -1174,6 +1221,7 @@ def set_value(self, value: Sequence[str]) -> None: self.on_change(new) def select_date(self, value: str) -> None: + """Add an ISO date to the range, which closes it once it has two ends.""" if not self.enabled: return _iso(value) @@ -1189,9 +1237,11 @@ def _date_chosen(self, value: str) -> None: raise def clear_selection(self) -> None: + """Forget both ends of the range.""" self.set_value(("", "")) def to_dict(self) -> WidgetNode: + """The serialised picker, with the chosen ends marked in the grid.""" self._summary._text = ( f"{self.value[0]} — {self.value[1] or '…'}" if self.value[0] else self.empty_text ) @@ -1244,13 +1294,16 @@ def __init__( @property def value(self) -> int: + """The index of the slide on screen.""" return self.pager.value @value.setter def value(self, value: int) -> None: + """The index of the slide on screen.""" self.pager.select(value) def set_value(self, value: int) -> None: + """Show the slide at ``value``, clamped to the slides that exist.""" self.value = value def _sync(self) -> None: @@ -1265,14 +1318,17 @@ def _selected(self, value: int) -> None: self.on_select(value) def next(self) -> None: + """Move to the next slide, wrapping around at the end.""" if self.enabled: self.pager.next() def previous(self) -> None: + """Move to the previous slide, wrapping around at the start.""" if self.enabled: self.pager.previous() def to_dict(self) -> WidgetNode: + """The serialised carousel, showing the current slide.""" self._sync() return super().to_dict() @@ -1495,10 +1551,12 @@ def select(self, page: int) -> None: self.on_change(page) def next(self) -> None: + """Go to the next page, if there is one.""" if self.enabled and self.current < self.total_pages: self.select(self.current + 1) def previous(self) -> None: + """Go to the previous page, if there is one.""" if self.enabled and self.current > 1: self.select(self.current - 1) diff --git a/pymobile/core/ui/pickers.py b/pymobile/core/ui/pickers.py index 2abd3de..282e38d 100644 --- a/pymobile/core/ui/pickers.py +++ b/pymobile/core/ui/pickers.py @@ -49,7 +49,7 @@ def _parse_time(value: str) -> _dt.time: # as a defence-in-depth fallback for older interpreters. if text.startswith("24:"): raise ValueError(f"{value!r} is not a valid wall-clock time (hour 24)") - if len(text) == 4 and text[1] == ":": # "7:05" -> "07:05" + if len(text) == 4 and text[1] == ":": # "7:05" -> "07:05" text = f"0{text}" try: parsed = _dt.time.fromisoformat(text) @@ -95,6 +95,7 @@ def value(self) -> str: @value.setter def value(self, value: str) -> None: + """The chosen date as ``YYYY-MM-DD``; assigning it behaves like picking one.""" self.set_value(value) def _normalise(self, value: str) -> str: @@ -113,11 +114,12 @@ def set_value(self, value: str) -> None: self.invalidate() # A value set while the tree is being built (build()) stays silent, # exactly like Slider/Switch/Checkbox/Dropdown: the handler would - # otherwise run against widgets that do not exist yet (BUG-25). + # otherwise run against widgets that do not exist yet. if self.on_change is not None and not in_build_scope(): self.on_change(text) def props(self) -> dict[str, Any]: + """The serialised props: the date plus the allowed range and the callback.""" return { **super().props(), "value": self._value, @@ -152,12 +154,14 @@ def value(self) -> str: @value.setter def value(self, value: str) -> None: + """The chosen time as ``HH:MM``; assigning it behaves like picking one.""" self.set_value(value) def _normalise(self, value: str) -> str: return _parse_time(value).strftime("%H:%M") def set_value(self, value: str) -> None: + """Choose ``value``, normalised to ``HH:MM``, and notify ``on_change``.""" text = self._normalise(value) if text != self._value: self._value = text @@ -167,6 +171,7 @@ def set_value(self, value: str) -> None: self.on_change(text) def props(self) -> dict[str, Any]: + """The serialised props: the time and the change callback.""" return { **super().props(), "value": self._value, diff --git a/pymobile/core/ui/preview.py b/pymobile/core/ui/preview.py index 2f8e386..50d55ff 100644 --- a/pymobile/core/ui/preview.py +++ b/pymobile/core/ui/preview.py @@ -95,7 +95,7 @@ def ascii_picture(widget_or_tree: Any, **kwargs: Any) -> str: # alias #: A plane-16 noncharacter: no font may define it, so rendering it always #: yields the face's ``.notdef`` glyph — our probe for "has no glyph for ch". -_NOTDEF_PROBE = "\U0010FFFE" +_NOTDEF_PROBE = "\U0010fffe" _glyph_cache: dict[tuple[Any, Any, str], bool | bytes] = {} @@ -286,7 +286,7 @@ def _as_node(widget_or_tree: Any) -> dict[str, Any]: def _zip_options_labels(props: dict[str, Any]) -> list[tuple[str, str]]: - """П-11: zip ``options`` (values) with ``labels`` (visible text).""" + """Zip ``options`` (values) with ``labels`` (visible text).""" option_values = [str(o) for o in (props.get("options") or [])] option_labels = [str(lbl) for lbl in (props.get("labels") or option_values)] while len(option_labels) < len(option_values): @@ -564,7 +564,14 @@ def _leaf_lines(node: dict[str, Any], show_ids: bool = False) -> list[str]: return [f"[{''.join(slider_bar)}] {value:g}"] if node_type == "Checkbox": - return ["[✓] on" if props.get("checked") else "[ ] off"] + # The label is the point of a check box; the state is what it holds. + # This printed the literal word "off" for every unticked box and dropped + # `text=` entirely. + label = text_value(props.get("text", "")) + mark = "[✓]" if props.get("checked") else "[ ]" + # An unlabelled box has nothing else to say, so it falls back to the + # state word the preview always used ("off"/"on"). + return [f"{mark} {label or ('on' if props.get('checked') else 'off')}"] if node_type == "RatingBar": rating = max(0.0, min(float(props.get("rating", 0)), int(props.get("maximum", 5)))) @@ -574,7 +581,7 @@ def _leaf_lines(node: dict[str, Any], show_ids: bool = False) -> list[str]: return [f"{rating_filled}{empty} {rating:g}/{maximum}"] if node_type == "Dropdown": - # П-11: show the currently selected *label*, not the internal value, + # Show the currently selected *label*, not the internal value, # so a localised dropdown reads as it does on device. option_values = [str(o) for o in (props.get("options") or [])] option_labels = [str(lbl) for lbl in (props.get("labels") or option_values)] diff --git a/pymobile/core/ui/registry.py b/pymobile/core/ui/registry.py index aa0890f..e05c59a 100644 --- a/pymobile/core/ui/registry.py +++ b/pymobile/core/ui/registry.py @@ -163,9 +163,7 @@ class BarChart(Widget): raise ValueError("type_name must be a non-empty string") if type_name in widget_types(): raise ValueError(f"{type_name!r} is a built-in widget type") - capability = WidgetCapability( - type_name, android=android, web=web, gui=gui, ascii=ascii - ) + capability = WidgetCapability(type_name, android=android, web=web, gui=gui, ascii=ascii) _declared[type_name] = capability return capability @@ -184,9 +182,7 @@ def supported_by(renderer: str) -> frozenset[str]: raise ValueError(f"unknown renderer: {renderer!r}") capabilities = (*WIDGET_CAPABILITIES, *_declared.values()) return frozenset( - capability.type_name - for capability in capabilities - if bool(getattr(capability, renderer)) + capability.type_name for capability in capabilities if bool(getattr(capability, renderer)) ) @@ -289,8 +285,7 @@ def badge_tk(preview, parent, node): raise ValueError("type_name must be a non-empty string") if renderer not in PREVIEW_RENDERERS: raise ValueError( - f"unknown preview renderer {renderer!r}; expected one of " - f"{', '.join(PREVIEW_RENDERERS)}" + f"unknown preview renderer {renderer!r}; expected one of {', '.join(PREVIEW_RENDERERS)}" ) if not callable(draw): raise TypeError( @@ -320,8 +315,7 @@ def preview_renderer(type_name: str, renderer: str) -> Callable[..., Any] | None """The function registered for ``type_name`` in ``renderer``, or ``None``.""" if renderer not in PREVIEW_RENDERERS: raise ValueError( - f"unknown preview renderer {renderer!r}; expected one of " - f"{', '.join(PREVIEW_RENDERERS)}" + f"unknown preview renderer {renderer!r}; expected one of {', '.join(PREVIEW_RENDERERS)}" ) return _preview.get((type_name, renderer)) diff --git a/pymobile/core/ui/screen.py b/pymobile/core/ui/screen.py index f9d8e2e..c7c697a 100644 --- a/pymobile/core/ui/screen.py +++ b/pymobile/core/ui/screen.py @@ -91,7 +91,7 @@ def __init__(self, title: str | None = None, *, title_key: str | None = None) -> #: cannot call ``build()`` again without recursing. self._building = False self._mounted = False - # П-10: set to True by Navigator._discard() once the screen has been + # Set to True by Navigator._discard() once the screen has been # popped. The ``app`` property raises for *new* accesses after the # stack settles, but stays usable from code that is mid-handler # (where the pop itself happened) so ``self.app.pop(); do(self.app)`` @@ -123,7 +123,7 @@ def leave(self): application of a screen that no longer exists is a bug that used to fail three lines later with a cryptic ``AttributeError`` on ``None``. """ - # П-10: during the UI dispatch that popped this screen we leave the + # During the UI dispatch that popped this screen we leave the # app reference intact so the handler can still use ``self.app`` # after calling pop(). Once the dispatch finishes _app is nulled and # we raise again for any truly stale access. @@ -156,6 +156,35 @@ def on_data(self, rows): return self._is_current # -- construction ------------------------------------------------------ + def __getattr__(self, name: str) -> Any: + """Explain a missing initialiser instead of naming a private attribute. + + A screen whose ``__init__`` forgets ``super().__init__()`` reaches the + framework with no state, and the first thing it touches is ``_root``: + the developer saw ``'Home' object has no attribute '_root'``, a name + they never wrote. The attribute stays missing (nothing is invented at + access time), but the message names the real cause and the fix. + """ + try: + object.__getattribute__(self, "_root") + except AttributeError: + pass + else: + # The screen was set up; this is an ordinary missing attribute + # (``self.titel``, a property that raised), not a missing super(). + # Checked through ``object.__getattribute__``: ``hasattr`` inside + # ``__getattr__`` calls ``__getattr__`` again and recurses. + raise AttributeError(name) from None + raise AttributeError( + f"{type(self).__name__}.__init__() did not call super().__init__(), so this " + f"screen was never set up (the framework then looked for {name!r}, which it " + "creates in its own initialiser). Add the call first:\n\n" + f" class {type(self).__name__}(Screen):\n" + " def __init__(self):\n" + " super().__init__()\n" + ' self.title = "..."\n' + ) from None + def build(self) -> Widget: """Return the widget tree for this screen.""" raise NotImplementedError(f"{type(self).__name__} must implement build()") @@ -312,6 +341,40 @@ def mounted(self) -> bool: """Whether the screen is currently attached to a navigator.""" return self._mounted + def _snapshot_state(self) -> dict[str, dict[str, Any]]: + """Interactive state of the tree that is about to be retired. + + Keyed by widget id, because the new tree is made of new objects: the + ids are what the two builds have in common. Only widgets that actually + changed something are recorded, so a form with ten empty fields keeps + no snapshot at all. + """ + if self._root is None: + return {} + snapshot: dict[str, dict[str, Any]] = {} + for node in self._root.walk(): + try: + state = node.capture_state() + except Exception: # pragma: no cover - a user widget must not break a rebuild + _log.exception("capturing the state of %s failed", node.id) + continue + if state: + snapshot[node.id] = state + return snapshot + + def _restore_state(self, snapshot: dict[str, dict[str, Any]]) -> None: + """Replay a snapshot onto the widgets the new build produced.""" + if not snapshot or self._root is None: + return + for node in self._root.walk(): + state = snapshot.get(node.id) + if not state: + continue + try: + node.restore_state(state) + except Exception: # pragma: no cover - a user widget must not break a rebuild + _log.exception("restoring the state of %s failed", node.id) + def _detach_tree(self) -> None: """Release the built tree so ``build()`` can attach its widgets again. @@ -362,8 +425,13 @@ def add(self) -> None: # the retired tree is all that is left to do. self._detach_tree() return + # Take the state of the old tree before letting go of it, and hand it + # to the widgets that come back with the same id: text the user typed + # survives a refresh, a theme switch and a language switch. + snapshot = self._snapshot_state() self._detach_tree() self.root # noqa: B018 - builds and validates the tree + self._restore_state(snapshot) def refresh(self) -> None: """Rebuild the tree from ``build()`` and re-render immediately. @@ -539,9 +607,34 @@ def on_show(self) -> None: def on_hide(self) -> None: """Called when another screen covers this one.""" + def on_start(self) -> None: + """Called when a new window adopts a screen that stayed in memory. + + The counterpart of :meth:`on_stop`: the app was never restarted, so + this is where a paused timer resumes and a restored draft is applied. + """ + def on_unmount(self) -> None: """Called once when the screen is popped.""" + def on_stop(self) -> None: + """Called when the window goes away but the app keeps running. + + An Activity that is destroyed and recreated — back on the root screen + followed by a relaunch, a configuration change outside + ``configChanges``, a low-memory process restart — no longer restarts + the interpreter (Android 7.0+ keeps the process and PyMobile keeps + Python alive in it). The screen instead gets this call before the + window is torn down, and once more on ``on_start`` when a new window + adopts it. + + Use it for what must survive the gap: a draft, a scroll position, a + timer that should not keep running while nothing is visible. The + framework already writes the widget state it tracks (a field's text, a + switch's position) through :meth:`App.save_state`; override this method + for the application's own data. + """ + def __repr__(self) -> str: # pragma: no cover - debugging aid return f"" @@ -632,7 +725,7 @@ def _discard(screen: Screen) -> None: screen.on_unmount() finally: screen._cancel_subscriptions() - # П-10: defer clearing ``screen._app`` until the currently + # Defer clearing ``screen._app`` until the currently # running UI event finishes. A button handler that calls # ``self.app.pop()`` and then reads ``self.app`` one more time # must not get ``PyMobileError("screen is no longer on the stack")`` @@ -751,7 +844,7 @@ def dispose(self) -> None: except Exception: _log.exception("on_hide of %s raised; disposing anyway", current.title) # Every screen is unmounted even when one hook raises: stopping the app - # must not stop at the first broken on_unmount (PM-12). + # must not stop at the first broken on_unmount. while self._stack: screen = self._stack.pop() try: diff --git a/pymobile/core/ui/state.py b/pymobile/core/ui/state.py new file mode 100644 index 0000000..e4d90eb --- /dev/null +++ b/pymobile/core/ui/state.py @@ -0,0 +1,349 @@ +"""Observable state: values a widget can follow instead of being rebuilt. + +The framework's own story used to be "keep the state in a field of the screen +and call ``refresh()``", which rebuilds the whole tree for one changed number. +A :class:`Value` is the small piece that was missing: it holds a value, tells +whoever is interested when that value changes, and can push itself straight +into a widget:: + + class Counter(Screen): + def __init__(self) -> None: + super().__init__() + self.taps = Value(0) + self.label = Label("0") + self.taps.bind(self.label, "text", transform=lambda n: f"Taps: {n}") + + def build(self) -> Widget: + return Column(self.label, Button("+1", on_press=self.increment)) + + def increment(self) -> None: + self.taps.value += 1 # the label redraws itself + +:class:`Computed` derives a value from other values and stays correct without +anyone remembering to update it. Both are deliberately small: no widget +re-creation, no diffing, no global store — a value, its dependents, and a +subscription that returns its own unsubscribe call. +""" + +from __future__ import annotations + +from collections.abc import Callable, Iterator +from contextlib import contextmanager, suppress +from contextvars import ContextVar +from typing import Any, Generic, TypeVar + +from ...log import get_logger + +__all__ = ["Value", "Computed"] + +T = TypeVar("T") + +_log = get_logger("ui.state") + +#: The Computed whose function is running, so the Values it reads can be +#: recorded as its sources. One ContextVar keeps concurrent builds apart. +_tracking: ContextVar[list[_Trackable] | None] = ContextVar("pymobile_state_tracking", default=None) + + +class _Trackable: + """Something that can be read by another value and notify it on change.""" + + __slots__ = ("_dependents",) + + def __init__(self) -> None: + self._dependents: list[Callable[[], None]] = [] + + def _notify(self) -> None: + for dependent in list(self._dependents): + dependent() + + def _depend(self, callback: Callable[[], None]) -> Callable[[], None]: + """Register ``callback``; the returned call removes it again. + + Membership is by identity: ``Value.__eq__`` compares the values inside, + so two equal values would otherwise look like the same dependency. + """ + if not any(existing is callback for existing in self._dependents): + self._dependents.append(callback) + + def unsubscribe() -> None: + with suppress(ValueError): # already gone + self._dependents.remove(callback) + + return unsubscribe + + +@contextmanager +def _collecting(sink: list[_Trackable]) -> Iterator[None]: + """Record every Value read inside the block into ``sink``.""" + token = _tracking.set(sink) + try: + yield + finally: + _tracking.reset(token) + + +class Value(_Trackable, Generic[T]): + """A value that notifies its dependents when it changes. + + ``Value(5)`` behaves like a box around ``5``: ``.value`` reads and writes it, + ``+= 1`` works, and ``bind()`` writes it into a widget. Assigning the value + it already holds notifies nobody, so a loop that recomputes ``0`` does not + schedule a redraw. + """ + + __slots__ = ("_value", "_name") + + def __init__(self, value: T, *, name: str = "") -> None: + super().__init__() + self._value = value + self._name = name + + # -- reading ----------------------------------------------------------- + @property + def value(self) -> T: + """The current value; reading it inside a :class:`Computed` links them.""" + tracked = _tracking.get() + if tracked is not None and not any(item is self for item in tracked): + tracked.append(self) + return self._value + + @value.setter + def value(self, value: T) -> None: + """The current value; assigning it publishes the change.""" + self.set(value) + + def get(self) -> T: + """The current value (the explicit spelling of ``.value``).""" + return self.value + + def __repr__(self) -> str: # pragma: no cover - debugging aid + name = f" {self._name!r}" if self._name else "" + return f"" + + # -- writing ----------------------------------------------------------- + def set(self, value: T) -> None: + """Assign, notifying dependents only when the value really changed.""" + if _same(self._value, value): + return + self._value = value + self._notify() + + def update(self, function: Callable[[T], T]) -> T: + """Replace the value with ``function(current)``; return the new one.""" + new = function(self._value) + self.set(new) + return self._value + + def toggle(self) -> bool: + """Flip a boolean value (``Value(False).toggle()`` → ``True``).""" + if not isinstance(self._value, bool): + raise TypeError("toggle() needs a bool value") + self.set(not self._value) # type: ignore[arg-type] + return bool(self._value) + + def __add__(self, other: Any) -> Any: + # ``self.taps += 1`` on a Value is a += on the *box*, so these two + # operators make the arithmetic spellings work on the value inside. + return self._value + other # type: ignore[operator] + + def __radd__(self, other: Any) -> Any: + return other + self._value # type: ignore[operator] + + def __sub__(self, other: Any) -> Any: + return self._value - other # type: ignore[operator] + + def __iadd__(self, other: Any) -> Value[T]: + self.set(self._value + other) # type: ignore[operator] + return self + + def __isub__(self, other: Any) -> Value[T]: + self.set(self._value - other) # type: ignore[operator] + return self + + def __eq__(self, other: object) -> bool: + if isinstance(other, Value): + return bool(self._value == other._value) + return bool(self._value == other) + + def __bool__(self) -> bool: + return bool(self._value) + + __hash__ = object.__hash__ + + # -- binding ----------------------------------------------------------- + def subscribe(self, callback: Callable[[T], None]) -> Callable[[], None]: + """Call ``callback(value)`` on every change; returns the unsubscribe.""" + + def handler() -> None: + callback(self._value) + + return self._depend(handler) + + def bind( + self, + widget: Any, + attribute: str = "text", + *, + transform: Callable[[T], Any] | None = None, + ) -> Value[T]: + """Write this value into ``widget.attribute`` now and on every change. + + The widget redraws itself when its attribute is set (that is what + :meth:`Widget.__setattr__` does), so binding one label to one value + costs one property assignment per change — no ``refresh()``, no rebuilt + tree, and no lost text in a neighbouring input:: + + self.taps.bind(self.label, "text", transform=lambda n: f"Taps: {n}") + self.visible.bind(self.spinner, "visible") + + Returns ``self`` so bindings can be chained. + """ + + def apply(value: T) -> None: + try: + setattr(widget, attribute, transform(value) if transform else value) + except Exception: # pragma: no cover - a bad binding must not crash a click + _log.exception( + "binding %r to %s.%s failed", + self._name or "value", + type(widget).__name__, + attribute, + ) + + apply(self._value) + self.subscribe(apply) + return self + + def bind_get( + self, widget: Any, attribute: str, *, transform: Callable[[Any], T] | None = None + ) -> Value[T]: + """Follow ``widget.attribute`` as a *source*: it becomes the value. + + The other direction of :meth:`bind`, for a field the user types into: + ``self.query.bind_get(self.search, "value")`` keeps ``self.query`` in + step with the input without a callback of its own. The widget is read + once immediately, so the value starts out correct. + """ + value = getattr(widget, attribute, None) + if value is not None: + self.set(transform(value) if transform else value) + return self + + +class Computed(_Trackable, Generic[T]): + """A value derived from others, recomputed when they change. + + The function runs once to find its sources, then again lazily whenever one + of them changes:: + + total = Computed(lambda: sum(item.price for item in cart.value)) + total.bind(total_label, "text", transform=lambda n: f"{n:.2f} грн") + + Reading a :class:`Value` (or another :class:`Computed`) inside the function + is what links the two; nothing has to be declared. A source that was not + read the first time is not watched — a derived value that branches on a + condition re-runs whenever the condition itself changes, so the branch it + takes is re-evaluated with it. + """ + + __slots__ = ("_compute", "_value", "_sources", "_dirty", "_recomputing") + + def __init__(self, compute: Callable[[], T]) -> None: + super().__init__() + self._compute = compute + self._sources: list[tuple[_Trackable, Callable[[], None]]] = [] + self._dirty = True + self._recomputing = False + self._value: T = self._recompute() + + def _invalidate(self) -> None: + """A source changed: recompute now, then tell our own dependents. + + Recomputing eagerly (rather than on the next read) is what makes a + binding update the label the moment a source changes; a lazy recompute + left the screen showing the previous number until something else asked + for the value. + """ + if self._recomputing: + # A cycle (``a = Computed(lambda: b.value)``, ``b`` reading ``a``): + # stop here rather than recursing forever. + self._dirty = True + return + self._recomputing = True + try: + previous = self._value + self._recompute() + if not _same(previous, self._value): + self._notify() + finally: + self._recomputing = False + + def _recompute(self) -> T: + for _source, unsubscribe in self._sources: + unsubscribe() + collected: list[_Trackable] = [] + with _collecting(collected): + value = self._compute() + for source in collected: + self._sources.append((source, source._depend(self._invalidate))) + self._dirty = False + self._value = value + return value + + @property + def value(self) -> T: + """The derived value, recomputed first if a source changed.""" + if self._dirty and not self._recomputing: + # A read from inside this value's own function (a genuine cycle) + # sees the last value instead of recursing: stale beats a crash. + self._recompute() + tracked = _tracking.get() + if tracked is not None and not any(item is self for item in tracked): + tracked.append(self) + return self._value + + def get(self) -> T: + """The derived value (the explicit spelling of ``.value``).""" + return self.value + + def map(self, function: Callable[[T], Any]) -> Computed[Any]: + """A second derived value: ``total.map(lambda n: f"{n:.2f}")``.""" + return Computed(lambda: function(self.value)) + + def bind( + self, + widget: Any, + attribute: str = "text", + *, + transform: Callable[[T], Any] | None = None, + ) -> Computed[T]: + """Write the derived value into a widget now and on every recompute.""" + + def apply() -> None: + try: + value = self.value + setattr(widget, attribute, transform(value) if transform else value) + except Exception: # pragma: no cover - a bad binding must not crash a click + _log.exception( + "binding a computed value to %s.%s failed", + type(widget).__name__, + attribute, + ) + + apply() + self._depend(apply) + return self + + def __repr__(self) -> str: # pragma: no cover - debugging aid + return f"" + + +def _same(left: Any, right: Any) -> bool: + """Whether two values count as unchanged (identity first, like a dict).""" + if left is right: + return True + try: + return bool(left == right) + except Exception: # pragma: no cover - exotic __eq__ + return False diff --git a/pymobile/core/ui/style.py b/pymobile/core/ui/style.py index d69b5ed..ff62a33 100644 --- a/pymobile/core/ui/style.py +++ b/pymobile/core/ui/style.py @@ -12,13 +12,47 @@ from dataclasses import asdict, dataclass, replace from typing import Any -__all__ = ["Style", "Color", "Align", "EdgeInsets"] +__all__ = ["Style", "Color", "Align", "EdgeInsets", "Border", "Gradient"] _HEX_COLOR = re.compile(r"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$") #: Named sizes a Style width/height accepts (mirrors the native renderer). _DIMENSION_WORDS = frozenset({"match", "fill", "wrap", "match_parent", "wrap_content"}) +#: A font family is a comma-separated list of plain names (``"Georgia, serif"``). +#: Quoted names and ``;`` are refused: the value is written into the device's +#: ``Typeface.create`` and into inline CSS, where punctuation would break out. +_FONT_NAME = r"[A-Za-z0-9][A-Za-z0-9 \-]{0,63}" +_FONT_FAMILY = re.compile(rf"^{_FONT_NAME}(?: *, *{_FONT_NAME})*$") + +#: Gradient directions, each mapped to CSS ``linear-gradient`` corner points. +#: Android draws its gradients top-to-bottom unless told otherwise, so every +#: renderer needs the same vocabulary to agree on the picture. +GRADIENT_DIRECTIONS: dict[str, tuple[float, float, float, float]] = { + "to_bottom": (0.5, 0.0, 0.5, 1.0), + "to_top": (0.5, 1.0, 0.5, 0.0), + "to_right": (0.0, 0.5, 1.0, 0.5), + "to_left": (1.0, 0.5, 0.0, 0.5), + "to_bottom_right": (0.0, 0.0, 1.0, 1.0), + "to_top_right": (0.0, 1.0, 1.0, 0.0), + "to_bottom_left": (1.0, 0.0, 0.0, 1.0), + "to_top_left": (1.0, 1.0, 0.0, 0.0), +} + +#: ``text_transform`` values; the same four CSS offers, spelled the same way. +TEXT_TRANSFORMS = ("none", "uppercase", "lowercase", "capitalize") + +#: ``text_overflow`` values. ``ellipsis`` clips a word that does not fit and +#: marks the cut with "…"; ``clip`` just cuts. The CSS spellings are accepted +#: as aliases because that is what people type first. +TEXT_OVERFLOWS = { + "ellipsis": "ellipsis", + "clip": "clip", + "text-ellipsis": "ellipsis", + "text-clip": "clip", + "fade": "ellipsis", +} + class Color: """Named colours plus validation for ``#RGB``/``#RRGGBB``/``#AARRGGBB``.""" @@ -81,6 +115,139 @@ def validate_cross(cls, value: str) -> str: return value +@dataclass(frozen=True, slots=True) +class Border: + """A stroke drawn around a widget. + + ``width`` is in dp and is measured inside the widget's own box, the way + Android's ``GradientDrawable.setStroke`` does it, so adding a border never + changes a layout: ``Border(color="#E0E0E0")`` is a hairline, and + ``Border(width=2, color=…)`` a heavier one. + + ``sides`` restricts the stroke to a subset (``Border(color=…, sides="bottom")``) + for the "row with a rule under it" case; the default draws all four. + """ + + width: float = 1 + color: str = "#E0E0E0" + #: Any combination of ``top``, ``right``, ``bottom``, ``left``. + sides: str = "top right bottom left" + + def __post_init__(self) -> None: + if isinstance(self.width, bool) or not isinstance(self.width, (int, float)): + raise TypeError(f"border width must be a number of dp, got {self.width!r}") + if self.width < 0: + raise ValueError("border width must not be negative") + if not isinstance(self.color, str): + raise TypeError(f"border color must be a hex string, got {self.color!r}") + Color.validate(self.color) + + @property + def side_set(self) -> frozenset[str]: + """The sides named, normalised; an empty border names none.""" + if self.width == 0: + return frozenset() + words = self.sides.replace(",", " ").split() + unknown = [word for word in words if word not in ("top", "right", "bottom", "left")] + if unknown: + raise ValueError( + f"unknown border side {unknown[0]!r}; expected a mix of " + "top, right, bottom, left (all four by default)" + ) + return frozenset(words) + + def to_dict(self) -> dict[str, Any]: + """Serialise to the JSON the renderers read.""" + return { + "width": self.width, + "color": Color.validate(self.color), + "sides": sorted(self.side_set), + } + + +@dataclass(frozen=True, slots=True) +class Gradient: + """A linear colour ramp, interpolated in sRGB. + + Two colours are the common case (``Gradient("#3F51B5", "#1A237E")``); a + third may be added to hold the middle of the ramp, and ``stops`` gives the + full control when the app has real design values:: + + Gradient("#FFFFFF", "#3F51B5", direction="to_bottom_right") + Gradient(stops=((0.0, "#FFFFFF"), (0.6, "#E8EAF6"), (1.0, "#3F51B5"))) + + ``direction`` is one of :data:`GRADIENT_DIRECTIONS` — ``to_bottom`` when + omitted, which is also what Android draws by default. + """ + + #: Positional spelling: the first two are the ends, the third the middle. + start: str = "" + end: str = "" + middle: str | None = None + #: ``((offset, colour), ...)`` with offsets from 0 to 1; overrides the three + #: positional colours when given. + stops: tuple[tuple[float, str], ...] | None = None + direction: str = "to_bottom" + + def __post_init__(self) -> None: + direction = str(self.direction).replace("-", "_").lower().strip() + if direction not in GRADIENT_DIRECTIONS: + raise ValueError( + f"invalid gradient direction {self.direction!r}; expected one of: " + + ", ".join(GRADIENT_DIRECTIONS) + ) + object.__setattr__(self, "direction", direction) + if self.stops is not None: + pairs: list[tuple[float, str]] = [] + for index, stop in enumerate(self.stops): + if len(stop) != 2: # type: ignore[arg-type] + raise TypeError(f"gradient stop {index} must be (offset, colour), got {stop!r}") + offset, colour = stop + if isinstance(offset, bool) or not isinstance(offset, (int, float)): + raise TypeError( + f"gradient stop {index}: offset must be a number, got {offset!r}" + ) + if not 0 <= offset <= 1: + raise ValueError(f"gradient stop {index}: offset must be from 0 to 1") + if not isinstance(colour, str): + raise TypeError(f"gradient stop {index}: colour must be a hex string") + Color.validate(colour) + pairs.append((float(offset), colour)) + if len(pairs) < 2: + raise ValueError("a gradient needs at least two stops") + pairs.sort(key=lambda pair: pair[0]) + if pairs[0][0] != 0.0 or pairs[-1][0] != 1.0: + raise ValueError( + "gradient stops must start at 0 and end at 1; without an end " + "colour the last one is stretched, which hides the mistake" + ) + object.__setattr__(self, "stops", tuple(pairs)) + return + if not self.start or not self.end: + raise TypeError( + "Gradient needs a start and an end colour: " + "Gradient('#FFFFFF', '#3F51B5') or Gradient(stops=((0, '#FFFFFF'), (1, '#3F51B5')))" + ) + for value in (self.start, self.end, self.middle): + if value is not None: + Color.validate(value) + + def ramp(self) -> tuple[tuple[float, str], ...]: + """The stops as ``((offset, colour), ...)``, whatever spelling was used.""" + if self.stops is not None: + return self.stops + if self.middle: + return ((0.0, self.start), (0.5, self.middle), (1.0, self.end)) + return ((0.0, self.start), (1.0, self.end)) + + def to_dict(self) -> dict[str, Any]: + """Serialise to the JSON the renderers read.""" + return { + "stops": [[offset, Color.validate(colour)] for offset, colour in self.ramp()], + "direction": self.direction, + } + + class _FieldInsteadOfMethod(TypeError): """A dataclass field called like a constructor: ``EdgeInsets.top(8)``. @@ -291,13 +458,7 @@ def _coerce_insets(name: str, value: object) -> EdgeInsets | None: @dataclass(frozen=True, slots=True) class Style: - """Visual attributes of a widget; ``None`` means "inherit the default". - - Besides the fixed ``width``/``height`` there is a set of constraints — - ``min_width``, ``max_width``, ``min_height``, ``max_height`` and - ``aspect_ratio`` — for the common "at least this big, never bigger than - that" card, and for images that must keep a 16:9 shape. - """ + """Visual attributes of a widget; ``None`` means "inherit the default".""" background: str | None = None color: str | None = None @@ -319,12 +480,44 @@ class Style: corner_radius: int | None = None elevation: int | None = None weight: float | None = None + # -- surface ----------------------------------------------------------- + #: ``0`` is fully transparent: for a whole screen it means "no background + #: of my own", so a themed parent shows through. + opacity: float | None = None + #: Stroke around the widget; width ``0`` means no border. + border: Border | None = None + #: A two-colour gradient. ``background`` keeps winning when both are set: + #: one of the two has to be the sRGB value the previews fall back on. + gradient: Gradient | None = None + # -- type -------------------------------------------------------------- + #: Extra space between lines, in dp (not a multiplier, unlike CSS). + line_height: float | None = None + #: Extra space between letters, in dp; may be negative to tighten. + letter_spacing: float | None = None + #: Typographic name: ``"serif"``, ``"monospace"``, ``"sans-serif"`` or a + #: system family list such as ``"Georgia, serif"``. + font_family: str | None = None + #: ``"none"``, ``"uppercase"``, ``"lowercase"`` or ``"capitalize"``. + text_transform: str | None = None + #: How much of the text may be shown where the line ends (see + #: :meth:`truncate`); also accepts the CSS spellings. + text_overflow: str | None = None + max_lines: int | None = None + underline: bool = False + strikethrough: bool = False def __post_init__(self) -> None: # Frozen dataclass: normalise through object.__setattr__. Without this # Style(padding=8) was accepted and then crashed in to_dict(). for name in ("padding", "margin"): object.__setattr__(self, name, _coerce_insets(name, getattr(self, name))) + for name in ("border", "gradient"): + value = getattr(self, name) + if value is not None and not isinstance(value, (Border, Gradient)): + raise TypeError( + f"{name} must be a {name.title()}, got {type(value).__name__!r}; " + f"write Style({name}={name.title()}(...))" + ) for value in (self.background, self.color): if value is not None: if not isinstance(value, str): @@ -388,11 +581,82 @@ def __post_init__(self) -> None: raise ValueError("elevation must not be negative") if self.corner_radius is not None and self.corner_radius < 0: raise ValueError("corner_radius must not be negative") + if self.opacity is not None: + if isinstance(self.opacity, bool) or not _is_number(self.opacity): + raise TypeError(f"opacity must be a number from 0 to 1, got {self.opacity!r}") + if not 0 <= float(self.opacity) <= 1: + raise ValueError("opacity must be from 0 (invisible) to 1 (opaque)") + for name in ("line_height", "letter_spacing"): + value = getattr(self, name) + if value is None: + continue + if isinstance(value, bool) or not _is_number(value): + raise TypeError(f"{name} must be a number of dp, got {value!r}") + if name == "line_height" and float(value) < 0: + raise ValueError("line_height must not be negative") + if self.font_family is not None: + if not isinstance(self.font_family, str) or not _FONT_FAMILY.match(self.font_family): + raise ValueError( + f"invalid font_family {self.font_family!r}; expected a font name or a " + "comma-separated list of names, e.g. 'serif' or 'Georgia, serif'" + ) + object.__setattr__(self, "font_family", self.font_family.strip()) + if self.text_transform is not None: + transform = str(self.text_transform).lower().strip() + if transform not in TEXT_TRANSFORMS: + raise ValueError( + f"invalid text_transform {self.text_transform!r}; expected one of: " + + ", ".join(TEXT_TRANSFORMS) + ) + object.__setattr__(self, "text_transform", transform) + if self.text_overflow is not None: + overflow = TEXT_OVERFLOWS.get(str(self.text_overflow).lower().strip()) + if overflow is None: + raise ValueError( + f"invalid text_overflow {self.text_overflow!r}; expected one of: ellipsis, clip" + ) + object.__setattr__(self, "text_overflow", overflow) + if self.max_lines is not None: + if isinstance(self.max_lines, bool) or not isinstance(self.max_lines, int): + raise TypeError(f"max_lines must be an int, got {self.max_lines!r}") + if self.max_lines < 1: + raise ValueError("max_lines must be at least 1") + if self.text_overflow is None: + # Cutting a paragraph short without saying how is what the + # device does anyway; say it out loud and the previews agree. + object.__setattr__(self, "text_overflow", "ellipsis") + for name in ("underline", "strikethrough"): + if not isinstance(getattr(self, name), bool): + raise TypeError(f"{name} must be a bool") def merge(self, **overrides: Any) -> Style: """Return a copy with some attributes replaced.""" return replace(self, **overrides) + def derive(self, **overrides: Any) -> Style: + """Alias of :meth:`merge`, named the way design systems talk. + + ``base.derive(background=brand)`` reads better than + ``base.merge(background=brand)`` at a call site, and both keep the rest + of the style intact. + """ + return replace(self, **overrides) + + @property + def url(self) -> str | None: + """The colour a preview would paint behind this widget, if any. + + ``Gradient`` wins by design: it is the more specific instruction, and a + flat colour is what the app falls back on where gradients are absent. + """ + if self.gradient is not None: + return self.gradient.ramp()[0][1] + if self.background is not None: + return self.background + if self.border is not None and self.border.width: + return self.border.color + return None + def to_dict(self) -> dict[str, Any]: """Serialise, skipping unset and falsy-default fields.""" raw = asdict(self) @@ -405,5 +669,15 @@ def to_dict(self) -> dict[str, Any]: if insets: result[key] = insets.to_list() continue + if key == "border": + border = self.border + if border is not None and border.width and border.side_set: + result[key] = border.to_dict() + continue + if key == "gradient": + gradient = self.gradient + if gradient is not None: + result[key] = gradient.to_dict() + continue result[key] = value return result diff --git a/pymobile/core/ui/web.py b/pymobile/core/ui/web.py index d21cec0..7025660 100644 --- a/pymobile/core/ui/web.py +++ b/pymobile/core/ui/web.py @@ -18,17 +18,18 @@ import mimetypes import secrets import threading -from collections.abc import Sequence +from collections.abc import Callable, Sequence from html import escape from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer from pathlib import Path -from typing import TYPE_CHECKING, Any, Protocol +from typing import TYPE_CHECKING, Any, NamedTuple, Protocol from urllib.parse import unquote, urlsplit from ...log import get_logger from .contract import text_value from .extras_preview import EXTRA_SCRIPT, render_extra_html from .registry import preview_renderer +from .style import GRADIENT_DIRECTIONS if TYPE_CHECKING: # pragma: no cover - typing only from ..app import App @@ -58,7 +59,11 @@ class _Readable(Protocol): """What draining needs: ``BinaryIO`` refuses ``BufferedIOBase.read``.""" - def read(self, size: int = ..., /) -> bytes | None: ... # pragma: no cover + """Read up to ``size`` bytes, or to the end of the stream.""" + + def read(self, size: int = ..., /) -> bytes | None: + """Read up to ``size`` bytes, or to the end of the stream.""" + ... # pragma: no cover def _drain_body(rfile: _Readable, length: int, limit: int = DRAIN_LIMIT) -> int: @@ -83,6 +88,46 @@ def _is_loopback(host: str) -> bool: return text in LOOPBACK_HOSTS or text.startswith("127.") +def _host_header_allowed(header: str, port: int, allow_hosts: Sequence[str] = ()) -> str | None: + """Whether a ``Host`` header may reach a loopback preview; ``None`` if not. + + The loopback preview carries no token, so the *only* thing standing between + a hostile page and the developer's screen was ``Origin`` — and a DNS-rebinding + attack never sends one: the browser believes it is talking to + ``evil.example``, so it sends ``Host: evil.example:8765`` and no ``Origin`` + on a top-level GET. The name resolves to 127.0.0.1, the request is served, + and the attacker reads the screen and presses its buttons. + + A request addressed to this machine by name therefore has to *name* this + machine: ``localhost``, ``127.0.0.1`` or ``[::1]``, with any port. Anything + else is refused unless it was added to ``allow_hosts`` (a preview behind a + reverse proxy legitimately sees its own public name here; that is also why + the check is skipped for an exposed preview, which carries a token instead). + + Returns a short reason when the header is refused, so the caller can say + which name was rejected. + """ + if not header: + # HTTP/1.0 clients and tests may omit it; nothing to verify. + return None + name = header.strip() + hostname, _, port_text = name.rpartition(":") + if not hostname: # a bare host without a port + hostname, port_text = name, "" + if port_text and port_text.isdigit() and int(port_text) != port: + return f"Host {name!r} names port {port_text}, not {port}" + allowed_names = {allowed.lower() for allowed in allow_hosts} + if allow_hosts and (name.lower() in allowed_names or hostname.lower() in allowed_names): + return None + if hostname.lower() in LOOPBACK_HOSTS or hostname.startswith("127."): + return None + return ( + f"Host {name!r} is not a loopback name. A local preview answers to " + "localhost, 127.0.0.1 and [::1] only, so a DNS name that resolves here " + "cannot reach it." + ) + + def browser_url(host: str, port: int, token: str = "") -> str: """A URL a human can actually open in a browser. @@ -309,6 +354,32 @@ def browser_url(host: str, port: int, token: str = "") -> str: """ +def _input_type(keyboard: str, password: bool) -> str: + """The ```` a ``TextInput(keyboard=…)`` maps to.""" + if password or keyboard == "password": + return "password" + return { + "email": "email", + "phone": "tel", + "url": "url", + "number": "number", + "decimal": "number", + "search": "search", + }.get(keyboard, "text") + + +def _input_mode(keyboard: str) -> str: + """``inputmode`` gives a phone browser the right keys where ``type`` cannot.""" + return { + "email": "email", + "phone": "tel", + "url": "url", + "number": "numeric", + "decimal": "decimal", + "search": "search", + }.get(keyboard, "text") + + def _style_css(style: dict[str, Any]) -> str: """Translate a serialised Style into inline CSS.""" parts: list[str] = [] @@ -350,9 +421,77 @@ def _style_css(style: dict[str, Any]) -> str: if style.get("elevation"): depth = int(style["elevation"]) parts.append(f"box-shadow:0 {depth}px {depth * 2}px rgba(0,0,0,.2)") + # -- surface ---------------------------------------------------------- + if style.get("opacity") is not None: + parts.append(f"opacity:{float(style['opacity']):.3f}".rstrip("0").rstrip(".")) + gradient = style.get("gradient") + if isinstance(gradient, dict) and gradient.get("stops"): + parts.append(f"background:{_gradient_css(gradient)}") + border = style.get("border") + if isinstance(border, dict) and border.get("sides"): + width = border.get("width", 1) + colour = _css_colour(str(border.get("color", "#E0E0E0"))) + sides = border.get("sides") or [] + if len(sides) == 4: + parts.append(f"border:{width}px solid {colour}") + else: + for side in sides: + parts.append(f"border-{side}:{width}px solid {colour}") + # -- type ------------------------------------------------------------- + if style.get("line_height") is not None: + parts.append(f"line-height:{style['line_height']}px") + if style.get("letter_spacing") is not None: + parts.append(f"letter-spacing:{style['letter_spacing']}px") + if style.get("font_family"): + # A family list carries its own fallbacks (``Georgia, serif``), so it is + # written as-is; names with a space are quoted the way CSS wants. + families = [] + for name in str(style["font_family"]).split(","): + name = name.strip() + quoted = " " in name and not name.startswith(("'", '"')) + families.append(f"'{name}'" if quoted else name) + parts.append("font-family:" + ",".join(families)) + if style.get("text_transform"): + parts.append(f"text-transform:{style['text_transform']}") + if style.get("underline"): + parts.append("text-decoration-line:underline") + if style.get("strikethrough"): + parts.append("text-decoration-line:line-through") + if style.get("underline") and style.get("strikethrough"): + parts[-1] = "text-decoration-line:underline line-through" + if style.get("max_lines"): + parts.append(f"-webkit-line-clamp:{int(style['max_lines'])}") + parts.append("display:-webkit-box") + parts.append("-webkit-box-orient:vertical") + parts.append("overflow:hidden") + elif style.get("text_overflow"): + parts.append(f"text-overflow:{style['text_overflow']}") + parts.append("white-space:nowrap") + parts.append("overflow:hidden") return ";".join(parts) +def _gradient_css(gradient: dict[str, Any]) -> str: + """A ``linear-gradient`` aimed the way the serializer recorded it. + + CSS measures the angle from "to top" clockwise, so the direction table of + :data:`~pymobile.core.ui.style.GRADIENT_DIRECTIONS` is turned into a vector + and then into that angle — the same arithmetic the Pillow and Java + renderers do, which is what keeps the preview honest. + """ + from math import atan2, degrees + + start_x, start_y, end_x, end_y = GRADIENT_DIRECTIONS.get( + str(gradient.get("direction", "to_bottom")), GRADIENT_DIRECTIONS["to_bottom"] + ) + angle = (degrees(atan2(end_x - start_x, start_y - end_y)) + 360) % 360 + stops = ", ".join( + f"{_css_colour(str(colour))} {float(offset) * 100:.4g}%" + for offset, colour in gradient["stops"] + ) + return f"linear-gradient({angle:.4g}deg, {stops})" + + def _css_colour(value: str) -> str: """#AARRGGBB is an Android convention; CSS wants #RRGGBBAA.""" if len(value) == 9 and value.startswith("#"): @@ -389,8 +528,27 @@ def _js_value(value: str) -> str: ) +class _RenderContext(NamedTuple): + """Everything an ``_html_*`` helper reads about the node it draws.""" + + node: dict[str, Any] + kind: str + props: dict[str, Any] + style: dict[str, Any] + css: str + widget_id: str + disabled: str + children: Sequence[Any] + inner: str + + def _render_html_node(node: dict[str, Any]) -> str: - """Render one serialised widget node (and its children) as HTML.""" + """Render one serialised widget node (and its children) as HTML. + + The drawing itself lives in the ``_html_*`` helpers below, one per widget + family; this function keeps the shared prologue, the custom-renderer hook + and the ``_HTML_RENDERERS`` lookup. + """ if not node.get("visible", True): return "" @@ -424,7 +582,51 @@ def _render_html_node(node: dict[str, Any]) -> str: return markup inner = "".join(render_html(child) for child in children) + ctx = _RenderContext(node, kind, props, style, css, widget_id, disabled, children, inner) + # A helper that draws several kinds keeps one guard per kind, so it returns + # None for the kinds it did not draw; the table above sends it the right one. + handler = _HTML_RENDERERS.get(kind) + if handler is not None: + markup = handler(ctx) + if markup is not None: + return markup + return f'
<{escape(kind)}>
' + + +_SELECTED_CSS = ( + "font-weight:700;background:var(--primary);color:var(--on-primary);border-color:var(--primary);" +) + +#: Colours of the five ButtonVariant roles in the browser preview. +_BUTTON_VARIANTS = { + "primary": ( + "background:var(--primary);color:var(--on-primary);border:1px solid var(--primary);" + "box-shadow:0 1px 3px rgba(0,0,0,.24);" + ), + "tonal": ( + "background:var(--bar-bg);" + "background:color-mix(in srgb,var(--primary) 18%,var(--bar-bg));" + "color:var(--text);border:1px solid var(--primary);" + ), + "outlined": "background:transparent;color:var(--primary);border:1px solid var(--primary);", + "text": "background:transparent;color:var(--primary);border:1px solid transparent;", + "danger": ( + "background:#C62828;color:#fff;border:1px solid #C62828;" + "box-shadow:0 1px 3px rgba(0,0,0,.24);" + ), +} + + +def _html_list(ctx: _RenderContext) -> str | None: + """A List: numbered rows, pull-to-refresh and paging.""" + kind = ctx.kind + props = ctx.props + css = ctx.css + widget_id = ctx.widget_id + disabled = ctx.disabled + children = ctx.children + inner = ctx.inner if kind == "List": # Rows are numbered so List.scroll_to() can find its target, and the # pull gesture becomes a button (a mouse cannot pull). @@ -464,7 +666,17 @@ def _render_html_node(node: dict[str, Any]) -> str: f'
{inner}
' ) + return None + +def _html_layout(ctx: _RenderContext) -> str | None: + """The plain containers: Stack and the column-like ones.""" + kind = ctx.kind + props = ctx.props + css = ctx.css + widget_id = ctx.widget_id + disabled = ctx.disabled + inner = ctx.inner if kind == "Stack": tap = _tap_attributes(kind, props, widget_id, disabled) access = ' role="button" tabindex="0"' if tap else "" @@ -481,7 +693,17 @@ def _render_html_node(node: dict[str, Any]) -> str: extra += ";cursor:pointer" return f'
{inner}
' return f'
{inner}
' + return None + +def _html_flow(ctx: _RenderContext) -> str | None: + """Layouts that flow their children: scroll, row, grid, wrap, flex.""" + kind = ctx.kind + props = ctx.props + css = ctx.css + widget_id = ctx.widget_id + disabled = ctx.disabled + inner = ctx.inner if kind == "ScrollView": gap = props.get("spacing", 0) horizontal = props.get("horizontal") @@ -530,7 +752,15 @@ def _render_html_node(node: dict[str, Any]) -> str: flex = int(props.get("flex", 1)) basis = "0" if props.get("fit", "tight") == "tight" else "auto" return f'
{inner}
' + return None + +def _html_ornament(ctx: _RenderContext) -> str | None: + """Non-interactive decoration: a divider, a spacer, a badge.""" + kind = ctx.kind + props = ctx.props + css = ctx.css + widget_id = ctx.widget_id if kind == "Divider": thickness = props.get("thickness", 1) inset = props.get("inset", 0) @@ -547,25 +777,68 @@ def _render_html_node(node: dict[str, Any]) -> str: f'margin:8px {inset}px;width:calc(100% - {2 * inset}px);{css}">' ) - if kind == "Label": - # The id is carried through so the browser inspector shows which - # widget a node is — the same readable ids find() uses. - text = escape(text_value(props.get("text", ""))) - return f'
{text}
' + if kind == "Spacer": + return f'
' - if kind == "Button": + if kind == "Badge": label = escape(text_value(props.get("text", ""))) - look = _button_css(props.get("variant")) + bg = _css_colour(text_value(props.get("background", "var(--primary)"))) + fg = _css_colour(text_value(props.get("color", "#FFFFFF"))) return ( - f'" + f'' + f"{label}" ) + return None + + +def _html_label(ctx: _RenderContext) -> str | None: + """A label: its text, transform and overflow.""" + props = ctx.props + css = ctx.css + widget_id = ctx.widget_id + # The id is carried through so the browser inspector shows which + # widget a node is — the same readable ids find() uses. + text = escape(text_value(props.get("text", ""))) + return f'
{text}
' + + +def _html_button(ctx: _RenderContext) -> str | None: + """A button, styled by variant.""" + props = ctx.props + css = ctx.css + widget_id = ctx.widget_id + disabled = ctx.disabled + label = escape(text_value(props.get("text", ""))) + look = _button_css(props.get("variant")) + return ( + f'" + ) + +def _html_text_field(ctx: _RenderContext) -> str | None: + """Text entry: the text field and the search bar.""" + kind = ctx.kind + props = ctx.props + css = ctx.css + widget_id = ctx.widget_id + disabled = ctx.disabled if kind == "TextInput": value = escape(text_value(props.get("value", "")), quote=True) placeholder = escape(text_value(props.get("placeholder", "")), quote=True) - kind_attr = "password" if props.get("password") else "text" - if props.get("multiline"): + keyboard = text_value(props.get("keyboard", "text")) + kind_attr = _input_type(keyboard, bool(props.get("password"))) + submit = "" + if props.get("on_submit"): + # The keyboard's action key is Enter in a browser: one submit event + # per press, and the page does not reload. + submit = ( + " onkeydown=\"if(event.key==='Enter'&&!event.shiftKey){event.preventDefault();" + "send(this.dataset.wid,'submit',this.value)}\"" + ) + if props.get("multiline") or keyboard == "multiline": body = escape(text_value(props.get("value", ""))) return ( f'