CLI (pn)

Reference for the pn console script. The implementation lives in pythonnative.cli.pn; this page renders its docstrings directly so the documented behavior never drifts from the code.

Subcommands

• pn init [name]: scaffold a new project (creates app/, pythonnative.json, requirements.txt, .gitignore).
• pn run android|ios: build and run on a connected device or simulator. Flags: --prepare-only, --hot-reload, --no-logs.
• pn clean: remove the local build/ directory.

pn CLI: scaffold, run, and clean PythonNative projects.

The console script pn (declared in pyproject.toml under [project.scripts]) dispatches to one of three subcommands:

• pn init [name]: scaffold a new project in the current directory.
• pn run android|ios: stage code into a native template, build it, install it, and stream logs back to the terminal.
• pn clean: remove the local build/ directory.

The implementation here is intentionally side-effect heavy: it shells out to gradle, xcodebuild, adb, and xcrun simctl. Errors from those tools are usually surfaced inline so the developer sees the underlying message.

Functions:

Name	Description
init_project	Scaffold a new PythonNative project in the current directory.
create_android_project	Stage the bundled Android template into destination.
create_ios_project	Stage the bundled iOS template into destination.
run_project	Build and run the project on the requested platform.
clean_project	Remove the local build/ directory.
main	Entry point for the pn console script.

init_project

init_project(args: Namespace) -> None

Scaffold a new PythonNative project in the current directory.

Creates app/main_page.py, pythonnative.json, requirements.txt, and .gitignore. Refuses to overwrite existing files unless --force is passed.

Parameters:

Name	Type	Description	Default
args	Namespace	The parsed argparse namespace. Recognized attributes: name (str, optional): Project name (defaults to the current directory name). force (bool): Overwrite existing files.	required

create_android_project

create_android_project(project_name: str, destination: str) -> None

Stage the bundled Android template into destination.

Parameters:

Name	Type	Description	Default
project_name	str	Project name (currently informational; the template uses fixed package IDs).	required
destination	str	Directory to receive the staged project.	required

create_ios_project

create_ios_project(project_name: str, destination: str) -> None

Stage the bundled iOS template into destination.

Parameters:

Name	Type	Description	Default
project_name	str	Project name (currently informational; the template uses fixed bundle IDs).	required
destination	str	Directory to receive the staged project.	required

run_project

run_project(args: Namespace) -> None

Build and run the project on the requested platform.

Stages templates, copies the user's app/ into the platform project, optionally installs Python requirements, and (unless --prepare-only is set) builds and launches the app on a connected device or simulator. With --hot-reload, also watches app/ for changes and pushes updates to the device.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed argparse namespace. Recognized attributes: platform ("android" | "ios"): Build target. prepare_only (bool): Stage files but skip the build. hot_reload (bool): Watch app/ and push changes. no_logs (bool): Don't stream device logs after launch.	required

clean_project

clean_project(args: Namespace) -> None

Remove the local build/ directory.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed argparse namespace (unused; accepted for the set_defaults(func=...) dispatch shape).	required

main

main() -> None

Entry point for the pn console script.

Wires up the init, run, and clean subcommands and dispatches to the corresponding handler.

Next steps

• See the Getting started walkthrough.
• Read about Hot reload when you turn on --hot-reload.