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'