# Py2Native — Full Documentation

> `llms-full.txt` — the complete, self-contained documentation of Py2Native's
> published interfaces. A short summary with links lives in `llms.txt`.
> Product website: <https://py2native.dev> · Repository:
> <https://github.com/py2native/py2native>

## Overview

Py2Native is a Python-to-native compiler. It compiles your proprietary Python
source files to C via Cython, compiles the C to native object code, and links
everything into a single native executable (or a shared library). All
 libraries stay as they are (eg plain Python) inside a managed `uv` environment —
only your code is compiled. Built executables ship with an embedded CPython
runtime and can import both the compiled modules and plain-Python libraries.

## Product tiers

- **Community** — package `py2native` (MIT). Full compilation, `uv` embedding,
  cross-platform. Published on PyPI.
- **Pro** — package `py2nativepro` (proprietary). Adds JWT-based license
  management (`keygen`/`sign`/`show` CLI commands, `--license` build flag,
  runtime JWT verification via `--public`) and string compression. Requires a
  paid-for license at build time; more information at <https://py2native.dev>.

Current versions: `py2native` 0.1.9, `py2nativepro` plugin 0.1.9.

## Installation

```
uv add --dev py2native
```

## CLI reference

Console script: `py2native` (entry point `py2native.cli:main`).

```
py2native [--verbose] <command> [options]

Commands:
  build   Build the executable
  keygen  Generate a new keypair (Pro)
  sign    Sign a JWT (Pro)
  show    Show information about a JWT (Pro)
```

Global options:

- `--verbose` — enable debug logging output.

### `py2native build`

Compiles the given modules and links them into a single native executable (or,
with `--library`, a shared library).

```
py2native build [options] <mainModule> <sources>...
```

Arguments:

- `<mainModule>` — dotted module path of the entry module, e.g. `mypkg.main`.
- `<sources>...` — one or more source glob patterns resolved against `--base`
  (e.g. `*.py`, `sub/*.py`, `**.py`). In bash, quote globs: `'*.py'`.

Options:

- `--embed <dir>` — create a deployment directory: copies a pristine CPython
  runtime, installs the project's dependencies (`uv export --no-dev` followed
  by `uv pip install --break-system-packages`), and places the executable into
  it (in library mode the built wheel is installed instead).
- `--wheel <dir>` — additionally create a PEP 427 wheel in `<dir>`.
- `--library` — build a shared library (`.pyd`/`.so`/`.dylib`) instead of an
  executable. `__main__.py` is excluded from sources and generated into the
  wheel instead.
- `--base <dir>` — base directory for source globs (default `.`).
- `--no-console` — disable the console (Windows GUI subsystem).
- `--exe <name>` — output executable name; defaults to the first dotted
  segment of `<mainModule>` with the platform suffix appended (e.g. `.exe`).
- `--version <version>` — version used for wheel naming and metadata; defaults
  to `project.version` from `pyproject.toml`.
- `--policy <policy>` — Linux wheel platform policy: `manylinux_2_28` or
  `musllinux_1_2`; ignored on other platforms.
- `--license <file>` (Pro) — Pro build license file (see License interface).
- `--public <file>` (Pro) — PEM P-256 public key embedded in the binary for
  runtime JWT verification; requires a Pro license with `withRuntimeJwt`.

### `py2native keygen` (Pro)

```
py2native keygen --private <private.pem> --public <public.pem>
```

Generates an ES256 (EC P-256) keypair and writes both keys as PEM files.

### `py2native sign` (Pro)

```
py2native sign --private <private.pem> [--expires <seconds>] <payload> <jwt>
```

- `<payload>` — a JSON object string, or a path to a JSON file.
- `<jwt>` — output path for the signed JWT (written as a text file).
- `--expires <seconds>` — sets the `iat`, `nbf`, and `exp` claims relative to
  now.

### `py2native show` (Pro)

```
py2native show [--public <public.pem>] <jwt>
```

Decodes and prints the JWT payload as JSON. With `--public`, verifies the
ES256 signature first and prints the verified claims.

## Runtime API

Every compiled executable registers a `py2native_runtime` module (also exposed
as `<package>.py2native_runtime` inside compiled packages):

- `__api_version__` — the string `"1"`.
- `__features__` — dict of enabled feature flags; Pro builds with runtime JWT
  contain `jwt_verify: True`.

Pro (built with `--public`), the documented license-verification API:

```python
from py2native_runtime import verify_license

claims = verify_license(
    token,
    expected_issuer="...",
    expected_audience="...",
)
```

Returns the JWT claims as a dict on success; raises on invalid signature,
expired or not-yet-valid tokens, or issuer/audience mismatch. Verification is
implemented in compiled code (ES256 / P-256, SHA-256) with no third-party
crypto libraries, and only the public key is embedded (obfuscated).

> Implementation status: the bootstrap currently exposes `__api_version__`
> and `__features__`; the Pro verifier is compiled in, but the `verify_license`
> export wiring is not yet enabled in `py2nativepro.main.extendTemplate`.

## Build artifacts

### Executable

A single native binary containing all compiled modules. At startup it:

- sets `sys.frozen = True`,
- installs a meta-path finder that imports the compiled modules,
- adds runtime library paths (`lib/pythonXY/lib-dynload`,
  `lib/pythonXY/site-packages`, `Lib/site-packages`, `DLLs`) relative to the
  executable and its parent directory,
- imports the main module and calls `main()`.

### Wheel (`--wheel`)

Named `<product>-<version>-cpXY-cpXY[t]-<platform>.whl` (e.g.
`mypkg-1.0.0-cp311-cp311-win_amd64.whl`). For CPython >= 3.11 non-free-threaded
library builds the ABI tag is `abi3`.

Executable mode contains:

- `<product>-<version>.data/scripts/<exe>` — the native executable,
- runtime libraries next to it (Windows: `python*.dll`; Linux: `libpython*.so`),
- `<product>-<version>.dist-info/METADATA` (derived from `pyproject.toml`),
  `WHEEL`, and `RECORD`.

Library mode contains:

- `<product>/<product>.pyd|.so|.dylib` — one shared library holding all
  compiled modules,
- `<product>/__init__.py` — a meta-path finder that redirects imports of the
  compiled submodules to the shared library,
- `<product>/__main__.py` — enables `python -m <product>`; imports the main
  module and calls `main()` if present,
- `<product>-<version>.dist-info/` metadata.

On Linux, `--policy` maps the wheel tag to `manylinux2014 ... manylinux_2_28`
or `musllinux_1_2`; `auditwheel repair` is applied in library mode.

### Embed directory (`--embed`)

A self-contained deployment directory:

- full copy of a pristine CPython runtime,
- project dependencies installed from `uv export --no-dev` with
  `--break-system-packages`,
- the executable at `bin/` (Linux/macOS) or the embed root (Windows); in
  library mode the built wheel is installed into the environment instead.

Distribution recipes: an installer (Inno Setup / NSIS) on Windows; a zip or
tar.gz archive, or a Docker image (multi-stage builds recommended) on Linux.

## License interface (Pro)

Build-time license lookup order:

1. `--license <file>` CLI flag,
2. `PY2NATIVE_LICENSE` environment variable — contains the license content,
   not a path (useful for Docker and CI/CD),
3. `~/.py2native/license.dat` in the user's home directory.

The license is a JWT signed with ES256. Expected claims: `iss` =
`RSJ Software GmbH`, `aud` = `py2native`, and feature flags `withRuntimeJwt`
and `withStringCompression`. The license is needed only for the build process,
not by the built software.

## Environment variables

- `PY2NATIVE_LICENSE` — Pro build license content (not a path).
- `P2N_MINGW32` — Windows only: path to an unpacked llvm-mingw32
  (ucrt-i686) tree for 32-bit builds.

## HTTP API (website backend)

The aiohttp backend that powers <https://py2native.dev> (static files served
from `./static`, Brotli-aware). Endpoints:

- `GET /` and `GET /{path}` — landing-page SPA; returns `index.html` for
  non-file paths (path traversal prevented).
- `POST /api/login` — JSON `{"userName", "password"}`; returns
  `{"runtimeSecret"}`; HTTP 400 on bad credentials.
- `GET /api/config` — public client configuration.
- `GET /api/buy?plan=…&locale=…&continue=…&cancel=…` — redirects to a Stripe
  Checkout session for the given plan (`pro` / `enterprise` aliases supported).
- `GET /api/contact` — redirects to the configured contact URL.
- `GET /api/portal` — redirects to the Stripe billing portal.
- `GET /api/activate?license=…&email=…` — AppSumo activation: fetches the
  license from AppSumo, emails the license file to the user, marks the code
  as redeemed.
- `GET /api/appsumo/login?code=…` — AppSumo OAuth exchange; redirects to
  `/license?license=…`.
- `POST /api/stripe/webhook` — Stripe webhook; HMAC-SHA256 signature verified
  via the `Stripe-Signature` header; on `invoice.paid` emails the license.
- `POST /api/appsumo/webhook` — AppSumo webhook; HMAC-SHA256 over
  `<timestamp><body>` using the `X-Appsumo-Timestamp` and
  `X-Appsumo-Signature` headers.
- `GET /api/stripe/setup` — admin: returns the current setup state (requires
  the runtime secret from `/api/login`).
- `POST /api/stripe/setup` — admin: applies Stripe / AppSumo / SMTP / plan
  setup, registers the Stripe webhook endpoint and billing portal, persists
  the config (requires the runtime secret).
- `PUT /api/collect/{fileName}` — stores the JSON request body under
  `./data/collect/{fileName}` (telemetry collection).

Purchase flow: the site opens
`https://stagingauth.rsj.de/pricing?product=py2native` in an iframe (Stripe
pricing table) → Stripe payment → redirect to
`https://stagingauth.rsj.de/done?sessionId={session}` → subscription record
created, license emailed to the buyer → redirect to the done page on
`py2native.rsj.de/done`.

## Plugin interface

`pluginManager` (module `py2native.plugin`) loads plugins by module name:
`py2nativepro`, `.winplatform`, `.linuxplatform`, `.macplatform`. A plugin
module exports a `Plugin` class, constructed with the manager instance.
Hooks are dispatched by method name:

- CLI: `extendSubParsers(subParsers)`, `extendBuildParser(buildParser)`,
  `extendBuild(args)`.
- Compilation: `extendCompiler(compiler)`, `extendTemplate()`
  (returns `{pxd, code, exports, features}`), `getCompileArgs()`,
  `getLinkerArgs(exeName, libraryPath)`, `newCompiler(noInit)`.
- Naming and paths: `getExecutableName(mainModule)`, `getExePath(path, name)`,
  `getExecutablePath(targetPath)`, `resolveExePath(exePath)`,
  `fixPlatformName(plat_name)`, `getCompileBasics()`.
- Runtime: `getRuntimeLibPath(pristinePath, buildPath)`,
  `getRuntimeLibraries(productName, version, libraryPath)`,
  `getInstallSelector()`, `ensureDynload(targetPath)`.
- Packaging: `auditWheel(runtimePath, wheelPath, outputPath, policy)`,
  `appendExecutable(exePath, zipPath)`, `makeExecutable(exePath)`.

Manager API: `register(plugin)`; `dispatch(method, *args, **kwargs)` returns
the first non-`None` result, merges lists/dicts across plugins; any other
method name is dispatched through `__getattr__`.

## Requirements

- CPython 3.11–3.15, including free-threaded 3.14t and 3.15t
  (package `requires-python: >=3.11`).
- A platform C compiler/linker: MSVC or llvm-mingw32 on Windows, GCC on
  Linux, Clang on macOS.
- OS: Windows 8 / 10 / 11, manylinux2014- or musllinux-compatible Linux,
  or macOS.
- CPU: x86-64 or ARM64.
- Internet access during the build (downloads Python distributions and
  libraries).
- `uv` for dependency management and embedding.

## Restrictions and notes

- No two modules may share the same name.
- `__init__.py` files are namespace markers and are not compiled.
- In `--library` mode, `__main__.py` is excluded from sources.
- Third-party libraries remain as Python source: monkey-patching stays
  possible; LGPL obligations are met (libraries remain replaceable by the end
  user); copyright notices are preserved.
- Your code is compiled 100% to C and then to native code — recovering the
  source is difficult, though reverse engineering is not impossible.
- Wheel building reads `pyproject.toml` (found by walking up from `--base`);
  `project.name` and `project.version` are required.