py2apk-compiler 0.1.0__tar.gz

py2apk_compiler-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: py2apk-compiler
+Version: 0.1.0
+Summary: A CLI tool for building Android APKs from Python source trees
+Project-URL: Homepage, https://github.com/muayyad-alsadi/py2apk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.66
+
+# Py2APK - A cli tool to create Android Apps APK from python source tree
+
+I hate heavy bloated IDEs, I hate Android Studio even more.
+
+This is a cli tool that let you write your app in python-like syntax
+Then build your apk directly from that code.
+
+```sh
+pip install py2apk-compiler
+py2apk setup
+py2apk init --template weather --pkg com.example.myweather --name "My First Weather App" myweather
+cd myweather
+py2apk build
+```
+
+* `py2apk setup` - set up the stable toolchain JAR files.
+* `py2apk init` - create a new project by copying a packaged template.
+  `--icon` is optional. `__PACKAGE__` and `__NAME__` in a template are replaced
+  with `--pkg` and `--name`.
+* `py2apk build` - from the project directory, fetch jars when `jars.db` is
+  missing, compile changed sources, assemble the APK, and sign it.
+
+`fetch_jars`, `fetch_platform`, and `compile` are the same stages `build`
+runs. Use them when you want that stage by itself.
+
+* `py2apk fetch_jars` - read `-r` (default `deps.txt`) and download those Maven
+  jars plus their runtime transitives. Google Maven and Central are always
+  searched. A `deps.txt` line `--extra-index-url URL` adds another repository
+  before those two, the same way `requirements.txt` adds an index. `-R URL`
+  does that from the command line. The `chart` template uses JitPack that way
+  for MPAndroidChart. An `.aar` dependency contributes its `classes.jar`. The
+  command also downloads the SDK platform stub for `targetSdkVersion`.
+* `py2apk fetch_platform` - download only that platform stub.
+* `py2apk compile` - find missing or stale Jasmin outputs for Python-like sources.
+
+`fetch_jars` caches Maven files under `~/.cache/py2apk/maven/` and the platform
+jar under `~/.cache/py2apk/platforms/<api>/`. Each cached jar gets a sibling
+SQLite file of its public and protected members, in the same directory as the
+Maven `.pom` when the artifact has one. That scan is reused until the jar
+changes. The project `jars/` directory receives dependency symlinks only.
+The platform stub stays in the cache. One merged `jars.db` sits at the project
+root. `jars.kind` is
+`direct`, `transitive`, or `platform`. Compile reads every kind. D8 dexes
+`direct` and `transitive` jars. The platform stub is passed to D8 with
+`--lib` so type lookup succeeds, and it is not written into the dex. The
+toolchain jars from `setup` are not dexed. Downloads use `aiohttp` with five concurrent
+transfers when that package is already installed, and `urllib.request`
+otherwise. `aiohttp` is not a required dependency.
+
+`py2apk setup` caches Jasmin and R8 through the Maven cache at
+`~/.cache/py2apk/maven/`. Apktool 3.0.3 and uber-apk-signer 1.3.0 are not
+published to Maven Central, so those two are cached from their GitHub releases
+under `~/.cache/py2apk/toolchain/`. The command symlinks all four into the
+toolchain `jars/` directory. It also creates
+`~/.local/share/py2apk/default.keystore` (alias `py2apk`, RSA 2048, PKCS12,
+10000 days) and writes the password to `default.keystore.pass` beside it.
+`XDG_DATA_HOME` overrides the directory. An existing keystore is left in place.
+
+The command interface is available after installation as `py2apk`, or directly
+from the repository root as `python3 -m Py2APK.cli`. `setup` retrieves
+apktool, Jasmin, R8/D8, and uber-apk-signer. Without `--dst`, it finds a writable
+Py2APK asset directory containing `templates/` and creates the sibling `jars/`
+directory. Pass `-d JARS_DIR` or `--dst JARS_DIR` to choose it explicitly.
+`compile` performs incremental source discovery and emits Jasmin for the
+currently supported typed Python-like subset. `build [DIRECTORY]` does the
+full project build: `fetch_jars` when `jars.db` is missing, then compile,
+Jasmin, D8, and apktool, then signs that APK with
+`~/.local/share/py2apk/default.keystore`. The installable file is
+`target/dist/<name>.signed.apk`, for example `weather.signed.apk`. `init`
+requires a destination that does not exist and recursively copies the
+selected template into it. Templates are package data, so
+this also works after `pip install --user py2apk-compiler`. For templates with
+apktool build inputs, `init` also copies `target/AndroidManifest.xml` and
+`target/apktool.yml` to the project root while preserving their modes and
+modification times. Root files and `src/` are authored inputs; `target/` is
+reproducible build output and may be deleted.
+
+## How does it work
+
+`Py2APK/cli.py` owns argument parsing and dispatch. Each non-trivial command is
+implemented in `Py2APK/cli_<COMMAND>.py`, such as `cli_setup.py`,
+`cli_init.py`, `cli_fetch_jars.py`, `cli_compile.py`, and `cli_build.py`.
+
+The command `py2apk compile` scans `src/` for missing or stale Jasmin targets and
+uses Python's built-in AST to emit `.j` files under `target/j/`. Method and
+field signatures come from the project's `jars.db`. The compiler supports the
+small, fully typed language subset used by the bundled templates.
+
+`py2apk build [DIRECTORY]` fetches jars when `jars.db` is missing, runs that
+compiler, synchronizes newer authored `AndroidManifest.xml` and `apktool.yml`
+files into `target/`, assembles the Jasmin into JVM classes, converts those
+classes to `classes.dex` with D8, asks apktool for the unsigned APK, and signs
+it with uber-apk-signer. The file to install is `target/dist/<name>.signed.apk`.
+It selects the first existing JAR
+directory from `$PY2APK_JARS`, the project's `jars/`, and the `jars/` sibling of
+source or installed `templates/` assets. A selected directory is expected to
+contain the complete toolchain, including `uber-apk-signer-*.jar`. If it does
+not, the error prints the exact `py2apk setup -d JARS_DIR` recovery command. Set
+`PY2APK_JARS=/path/to/jars` when the JARs live elsewhere.
+
+See the [internal documentation](docs/interals.md) for the generated directory
+layout and individual build stages.
+
+## Signing development APKs
+
+Apktool assembles an APK but does not sign it, and Android will not install an
+unsigned APK. `py2apk build` runs [`uber-apk-signer`](https://github.com/patrickfav/uber-apk-signer)
+on that APK with `~/.local/share/py2apk/default.keystore` and writes
+`target/dist/<name>.signed.apk`. Install that file:
+
+```sh
+adb install -r target/dist/weather.signed.apk
+```
+
+The same signer invocation, if you need to run it by hand, is:
+
+```sh
+java -jar /path/to/uber-apk-signer-1.3.0.jar \
+  -a target/dist/helloworld.apk \
+  --ks ~/.local/share/py2apk/default.keystore \
+  --ksAlias py2apk \
+  --ksPass "$(cat ~/.local/share/py2apk/default.keystore.pass)" \
+  --ksKeyPass "$(cat ~/.local/share/py2apk/default.keystore.pass)"
+```
+
+This keystore is a local release-style key, not a store you should publish
+with. Do not commit the keystore or its password file.
+
+Android Studio is not required for either building or signing Py2APK projects.
+If a release process uses Google's official tools, install only the Android SDK
+command-line tools and Build Tools. `zipalign` is a platform-specific native
+executable, not a JAR; `apksigner` is Java-based but is normally distributed as
+part of the SDK Build Tools. For lightweight development without an SDK install,
+`uber-apk-signer` bundles the alignment and signing workflow behind one command.

py2apk_compiler-0.1.0/Py2APK/classfile.py

@@ -0,0 +1,191 @@
+"""Parse JVM class files into the members the Jasmin compiler needs.
+
+The reader uses only ``struct``. It walks the constant pool and member tables
+and skips attributes by length, so method bodies are never decoded.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+
+ACC_PUBLIC = 0x0001
+ACC_PRIVATE = 0x0002
+ACC_PROTECTED = 0x0004
+ACC_STATIC = 0x0008
+ACC_INTERFACE = 0x0200
+ACC_SYNTHETIC = 0x1000
+
+
+@dataclass(frozen=True)
+class ClassMember:
+    owner: str
+    name: str
+    descriptor: str
+    is_static: bool
+    opcode: str = ""
+
+
+@dataclass(frozen=True)
+class ParsedClass:
+    internal: str
+    super_internal: str | None
+    is_interface: bool
+    interfaces: tuple[str, ...]
+    methods: tuple[ClassMember, ...]
+    fields: tuple[ClassMember, ...]
+
+
+class ClassFileError(ValueError):
+    """Raised when a class file is not readable."""
+
+
+class _Reader:
+    def __init__(self, data: bytes) -> None:
+        self.data = data
+        self.offset = 0
+
+    def u1(self) -> int:
+        value = self.data[self.offset]
+        self.offset += 1
+        return value
+
+    def u2(self) -> int:
+        value = struct.unpack_from(">H", self.data, self.offset)[0]
+        self.offset += 2
+        return value
+
+    def u4(self) -> int:
+        value = struct.unpack_from(">I", self.data, self.offset)[0]
+        self.offset += 4
+        return value
+
+    def skip(self, count: int) -> None:
+        self.offset += count
+
+    def bytes(self, count: int) -> bytes:
+        chunk = self.data[self.offset : self.offset + count]
+        self.offset += count
+        return chunk
+
+
+def parameter_descriptors(params: str) -> tuple[str, ...]:
+    index = 0
+    found: list[str] = []
+    while index < len(params):
+        start = index
+        index = _skip_field(params, index)
+        found.append(params[start:index])
+    return tuple(found)
+
+
+def split_method_descriptor(descriptor: str) -> tuple[str, str]:
+    """Return the concatenated parameter descriptors and the result descriptor."""
+    if not descriptor.startswith("(") or ")" not in descriptor:
+        raise ClassFileError(f"bad method descriptor: {descriptor}")
+    index = 1
+    while descriptor[index] != ")":
+        index = _skip_field(descriptor, index)
+    return descriptor[1:index], descriptor[index + 1 :]
+
+
+def parse_class(data: bytes) -> ParsedClass:
+    reader = _Reader(data)
+    if len(data) < 8 or reader.u4() != 0xCAFEBABE:
+        raise ClassFileError("class file does not start with 0xCAFEBABE")
+    _ = reader.u2()
+    _ = reader.u2()
+    pool = _constant_pool(reader)
+    access = reader.u2()
+    internal = _class_name(pool, reader.u2())
+    super_index = reader.u2()
+    super_internal = _class_name(pool, super_index) if super_index else None
+    interfaces = tuple(_class_name(pool, reader.u2()) for _ in range(reader.u2()))
+    is_interface = bool(access & ACC_INTERFACE)
+    fields = tuple(_members(reader, pool, internal, is_interface, methods=False))
+    methods = tuple(_members(reader, pool, internal, is_interface, methods=True))
+    return ParsedClass(internal, super_internal, is_interface, interfaces, methods, fields)
+
+
+def _constant_pool(reader: _Reader) -> list[object]:
+    count = reader.u2()
+    pool: list[object] = [None] * count
+    index = 1
+    while index < count:
+        tag = reader.u1()
+        if tag == 1:
+            pool[index] = reader.bytes(reader.u2()).decode("utf-8", "surrogateescape")
+        elif tag in {7, 8, 16, 19, 20}:
+            pool[index] = ("class", reader.u2()) if tag == 7 else reader.u2()
+        elif tag in {3, 4, 9, 10, 11, 12, 17, 18}:
+            reader.skip(4)
+        elif tag in {5, 6}:
+            reader.skip(8)
+            index += 1
+        elif tag == 15:
+            reader.skip(3)
+        else:
+            raise ClassFileError(f"unknown constant-pool tag {tag}")
+        index += 1
+    return pool
+
+
+def _class_name(pool: list[object], index: int) -> str:
+    entry = pool[index]
+    if not isinstance(entry, tuple) or entry[0] != "class":
+        raise ClassFileError(f"constant pool {index} is not a class")
+    name = pool[entry[1]]
+    if not isinstance(name, str):
+        raise ClassFileError(f"class name {entry[1]} is not Utf8")
+    return name
+
+
+def _utf8(pool: list[object], index: int) -> str:
+    value = pool[index]
+    if not isinstance(value, str):
+        raise ClassFileError(f"constant pool {index} is not Utf8")
+    return value
+
+
+def _members(
+    reader: _Reader,
+    pool: list[object],
+    owner: str,
+    is_interface: bool,
+    *,
+    methods: bool,
+) -> list[ClassMember]:
+    found: list[ClassMember] = []
+    for _ in range(reader.u2()):
+        access = reader.u2()
+        name = _utf8(pool, reader.u2())
+        descriptor = _utf8(pool, reader.u2())
+        for _attribute in range(reader.u2()):
+            _ = reader.u2()
+            reader.skip(reader.u4())
+        visible = bool(access & (ACC_PUBLIC | ACC_PROTECTED))
+        if not visible or access & ACC_SYNTHETIC or access & ACC_PRIVATE:
+            continue
+        is_static = bool(access & ACC_STATIC)
+        opcode = ""
+        if methods:
+            if is_static:
+                opcode = "invokestatic"
+            elif name == "<init>":
+                opcode = "invokespecial"
+            elif is_interface:
+                opcode = "invokeinterface"
+            else:
+                opcode = "invokevirtual"
+        found.append(ClassMember(owner, name, descriptor, is_static, opcode))
+    return found
+
+
+def _skip_field(descriptor: str, index: int) -> int:
+    while descriptor[index] == "[":
+        index += 1
+    if descriptor[index] == "L":
+        end = descriptor.index(";", index)
+        return end + 1
+    return index + 1

py2apk_compiler-0.1.0/Py2APK/cli.py

@@ -0,0 +1,159 @@
+"""Command-line interface for Py2APK."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+from pathlib import Path
+from typing import cast
+
+from Py2APK.cli_build import build_project
+from Py2APK.cli_compile import compile_project
+from Py2APK.cli_fetch_jars import fetch_jars
+from Py2APK.cli_fetch_platform import main as fetch_platform_main
+from Py2APK.cli_setup import download_jars
+from Py2APK.cli_init import init_project
+
+
+def _setup(args: argparse.Namespace) -> int:
+    destination_arg = cast(str | None, args.destination)
+    destination = None if destination_arg is None else Path(destination_arg)
+    return download_jars(destination)
+
+
+def _init(args: argparse.Namespace) -> int:
+    icon = None if args.icon is None else str(args.icon)
+    return init_project(
+        template_name=str(args.template),
+        icon=icon,
+        package=str(args.package),
+        name=str(args.name),
+        destination=Path(str(args.directory)),
+    )
+
+
+def _fetch_jars(args: argparse.Namespace) -> int:
+    repositories = list(args.repositories or [])
+    dependency_file = None if args.dependencies is None else Path(args.dependencies)
+    return fetch_jars(Path(args.directory).expanduser(), dependency_file, repositories)
+
+
+def _fetch_platform(args: argparse.Namespace) -> int:
+    return fetch_platform_main(Path(args.directory).expanduser())
+
+
+def _compile(_args: argparse.Namespace) -> int:
+    return compile_project()
+
+
+def _build(args: argparse.Namespace) -> int:
+    return build_project(Path(args.directory).expanduser())
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="py2apk",
+        description="Build Android APKs from Python source trees.",
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    setup_parser = subparsers.add_parser(
+        "setup",
+        help="set up the required toolchain JAR files",
+    )
+    _ = setup_parser.add_argument(
+        "-d",
+        "--dst",
+        dest="destination",
+        help="destination jars directory (default: detected package assets)",
+    )
+    setup_parser.set_defaults(handler=_setup)
+
+    init_parser = subparsers.add_parser(
+        "init",
+        help="initialize a project from a template",
+    )
+    init_parser.add_argument(
+        "--template",
+        default="blank",
+        help="project template (default: blank)",
+    )
+    init_parser.add_argument("--icon", help="path to the app icon")
+    init_parser.add_argument(
+        "--pkg",
+        dest="package",
+        required=True,
+        help="Android package name",
+    )
+    init_parser.add_argument("--name", required=True, help="display name of the app")
+    init_parser.add_argument("directory", help="directory to create")
+    init_parser.set_defaults(handler=_init)
+
+    compile_parser = subparsers.add_parser(
+        "compile",
+        help="find Python sources that need Jasmin output",
+    )
+    compile_parser.set_defaults(handler=_compile)
+
+    build_parser = subparsers.add_parser(
+        "build",
+        help="build a project into an APK",
+    )
+    build_parser.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        help="project directory (default: current directory)",
+    )
+    build_parser.set_defaults(handler=_build)
+
+    fetch_jars_parser = subparsers.add_parser(
+        "fetch_jars",
+        help="fetch dependency jars and the Android platform jar",
+    )
+    fetch_jars_parser.add_argument(
+        "-r",
+        dest="dependencies",
+        help="dependency file (default: deps.txt)",
+    )
+    fetch_jars_parser.add_argument(
+        "-R",
+        dest="repositories",
+        action="append",
+        help="extra Maven repository URL, tried before Central (repeatable)",
+    )
+    fetch_jars_parser.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        help="project directory (default: current directory)",
+    )
+    fetch_jars_parser.set_defaults(handler=_fetch_jars)
+
+    fetch_platform_parser = subparsers.add_parser(
+        "fetch_platform",
+        help="fetch the Android platform stub jar for targetSdkVersion",
+    )
+    fetch_platform_parser.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        help="project directory (default: current directory)",
+    )
+    fetch_platform_parser.set_defaults(handler=_fetch_platform)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = create_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help()
+        return 0
+    return handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())