runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- uses: astral-sh/setup-uv@v10.0.1

with:

enable-cache: true

python-version: '3.11'

# `uv sync` installs the project itself, which mkdocstrings needs in

# order to import and introspect it.

- name: Install docs deps

run: uv sync --locked --group docs

- name: Build site

run: uv run mkdocs build --strict

- name: Deploy to GitHub Pages

if: github.event_name == 'push' && github.ref == 'refs/heads/main'

uses: peaceiris/actions-gh-pages@v3

- name: Checkout

uses: actions/checkout@v4

- name: Set up uv

uses: astral-sh/setup-uv@v10.0.1

with:

enable-cache: true

python-version: '3.11'

- name: Set up Java 17

java-version: '17'

- name: Install PythonNative

run: uv sync --locked

- name: Install Maestro

run: |

# The emulator step runs its script through a login shell, which

# sources /etc/profile and can rewrite PATH. Confirm uv survives that

# here, in seconds, rather than after a multi-minute emulator boot.

- name: Verify uv is reachable in a login shell

run: bash -lc 'command -v uv && uv --version'

- name: Build, install, and run E2E tests

uses: reactivecircus/android-emulator-runner@v2

with:

api-level: 31

arch: x86_64

script: bash -lc "uv run ./scripts/run-e2e.sh android ${{ matrix.suites }}"

# Maestro writes per-flow debug output (command log, view-hierarchy

# dumps, failure screenshots) under ~/.maestro/tests. Surface it when

- name: Checkout

uses: actions/checkout@v4

- name: Set up uv

uses: astral-sh/setup-uv@v10.0.1

with:

enable-cache: true

python-version: '3.11'

- name: Install PythonNative

run: uv sync --locked

# Maestro drives iOS simulators with its own bundled XCTest

# runner; idb-companion (once installed here) hasn't been needed

- name: Build and run E2E tests

run: uv run ./scripts/run-e2e.sh ios ${{ matrix.suites }}

env:

GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

with:

fetch-depth: 0

- name: Set up uv

uses: astral-sh/setup-uv@v10.0.1

with:

enable-cache: true

python-version: '3.12'

# TEMPORARY: inlined replacement for the

# python-semantic-release/python-semantic-release@v9 action. That

# action builds its Docker image at job time with GitPython

run: |

# The distributions come from `build_command` in

# [tool.semantic_release], which runs `uv build` after PSR stamps the

# new version, so there is no separate build step here.

- name: Publish to PyPI

if: steps.release.outputs.released == 'true'

uses: pypa/gh-action-pypi-publish@release/v1

Development uses Python ≥ 3.10 and [uv](https://docs.astral.sh/uv/) as the

only prerequisite. `uv sync` creates and updates `.venv` itself, so there's no

virtual environment to make and nothing to activate.

uv sync --locked --group dev

./scripts/check.sh

uv run pytest -q

uv run ruff check .

uv run black src examples tests

Dependencies are pinned in `uv.lock`, which is committed, so local runs and CI

resolve identically. `--locked` fails rather than silently re-resolving if the

lockfile has drifted from `pyproject.toml`. Upgrading a dependency is a

deliberate `uv lock --upgrade-package <name>` in its own commit.

Common library and CLI entry points. `uv run` puts `.venv/bin` on the path

for one command, so `pn` resolves without activating anything. Each block

starts from the repository root.

uv run pn --help

uv run pn init my_app

cd my_app

uv run pn run android

`uv run` looks upward for the nearest project, so it keeps using the

repository's `.venv` from a subdirectory. The bundled example works the same

way:

cd examples/hello-world && uv run pn run android

Common commands:

./scripts/check.sh # run all CI checks (mirrors ci.yml)

uv sync --locked --group dev # install/refresh .venv from the lockfile

uv run pytest -q # run tests

uv run ruff check . # lint

uv run black src examples tests # format

uv run --group docs mkdocs serve # preview the docs site locally

- PR title: Conventional Commits format (CI-enforced by `pr-lint.yml`).

- Tests: added/updated; `uv run pytest` passes.

- Lint/format: `uv run ruff check .` and `uv run black --check src examples tests` pass.

- Docs: update `README.md` if behavior changes.

- Templates: update `src/pythonnative/templates/` if generator output changes.

- No generated artifacts committed.

uv run ./scripts/run-e2e.sh android

uv run ./scripts/run-e2e.sh ios

For tight iteration, run a single category instead of the full pass:

uv run ./scripts/run-e2e.sh android hooks

uv run ./scripts/run-e2e.sh ios components

Available categories: `components`, `hooks`, `navigation`, `layout`, `styling`, `animations`, `misc`.

2. Append a `DemoEntry` in `examples/e2e-suite/app/registry.py`.

3. Add a Maestro flow at `tests/e2e/flows/<category>/<name>.yaml`.

4. Append the flow to the top-level `tests/e2e/android.yaml`, `tests/e2e/ios.yaml`, and the matching `tests/e2e/suites/<category>.yaml`.

5. Confirm `uv run python scripts/check-e2e-coverage.py` exits 0.

`tests/e2e/AGENTS.md` is the deeper reference (label conventions, failure triage, naming rules); AI agents should read it before touching the suite. The `e2e.yml` workflow runs the suite automatically on pushes to `main` and PRs.

build = [

"Pillow>=10.0",

]

[dependency-groups]

dev = [

"black>=24.0",

"ruff>=0.5",

"mypy>=1.10",

"pytest>=8.0",

"pytest-asyncio>=0.23",

"Pillow>=10.0",

# `pn run ios` shells out to `sys.executable -m pip` to vendor

# rubicon-objc (project/builder.py), and the test suite exercises that

# path. `uv sync` does not seed pip the way `uv venv --seed` did.

"pip>=24.0",

]

docs = [

"mkdocs>=1.5",

"mkdocs-material[imaging]>=9.5",

"mkdocstrings[python]>=0.24",

"mkdocs-autorefs>=1.0",

"pymdown-extensions>=10.7",

]

[project.scripts]

[tool.semantic_release]

build_command = """

version_toml = ["pyproject.toml:project.version"]

version_variables = ["src/pythonnative/__init__.py:__version__"]

commit_message = "chore(release): v{version}"