android-widgets 0.1.6__tar.gz → 0.1.8__tar.gz

android_widgets-0.1.8/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: android-widgets
+Version: 0.1.8
+Summary: This would be used to auto gen XMLs for Android Home Screen widgets.
+Author-email: Fabian <fector101@yahoo.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Fector101/kivy-androidwidgets
+Project-URL: Documentation, https://github.com/Fector101/kivy-androidwidgets
+Project-URL: Source, https://github.com/Fector101/kivy-androidwidgets
+Project-URL: Tracker, https://github.com/Fector101/kivy-androidwidgets/issues
+Keywords: kivy,android,widgets,hello-world,python-package
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Android
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: kivy>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+Kivy-androidwidgets
+---
+Generate Android home-screen widgets for Kivy / Buildozer apps from a pure-Python DSL — **no XML, no Java**. Widget definitions are compiled by a CLI pre-build step into `res/`, `src/` and a p4a hook that Buildozer compiles straight into the APK.
+
+Complete sample: [working app](https://github.com/Fector101/wallpaper-carousel)
+
+Quickstart
+---
+### 1. Install
+```bash
+pip install kivy-androidwidgets
+```
+
+### 2. Describe your widget in Python
+
+`widgets.py` (in your project root):
+
+```python
+from android_widgets import HomeWidget, AWColumn, AWRow, AWText, AWImage, AWButton, AWProgressBar, Color
+
+clock = HomeWidget(
+    name="Clock",
+    description="Shows the current time",
+    layout=AWColumn(
+        spacing=6,
+        children=[
+            AWText("12:00", id="time", size=28, bold=True),
+            AWText("Mon 4 Aug", id="date", size=12, color=Color("#888888")),
+        ],
+    ),
+    min_width_dp=110,          # 2 cells
+    min_height_dp=110,
+    resize_mode="horizontal|vertical",
+    update_period_ms=1800000,  # Android minimum: 30 minutes
+    tap_to_open=True,          # whole widget opens the app on tap
+    background=Color("#FFFFFF"),
+    radius=12,
+)
+```
+
+### 3. Generate the Android artifacts
+
+```bash
+python -m android_widgets init     # creates p4a/hook.py (one-time)
+python -m android_widgets generate --spec buildozer.spec --module widgets.py
+```
+
+This writes (gitignore them):
+- `res/layout/<name>.xml`, `res/layout/<name>_preview.xml`
+- `res/xml/<name>_provider.xml` — the `appwidget-provider` metadata
+- `res/drawable/widget_bg_<name>.xml` — rounded background shapes
+- `src/<package>/<ClassName>.java` — one `AppWidgetProvider` per widget
+- `res/values/widgets.xml`, `p4a/widget_receivers.json`
+
+`generate` reads `package.domain` + `package.name` from `buildozer.spec`. Use `--dry-run` to preview without writing.
+
+### 4. Wire it into `buildozer.spec`
+
+```ini
+android.add_resources = res
+android.add_src = src
+p4a.hook = p4a/hook.py
+```
+
+### 5. Build
+```bash
+buildozer android debug
+```
+
+The generated `p4a/hook.py` (`after_apk_build`) injects the `<receiver>` entries into the dist's `AndroidManifest.xml` before aapt compiles it, so no manual manifest editing.
+
+DSL Reference
+---
+- `HomeWidget` — `name`, `description`, `layout`, `min_width_dp`, `min_height_dp`, `target_cells`, `max_cells`, `resize_mode`, `widget_category`, `update_period_ms`, `preview_image`, `preview_layout`, `tap_to_open`, `background` (`Color`), `radius`, `padding`
+- `AWColumn`, `AWRow` — `spacing`, `children`
+- `AWFrame` — single child, ideal for cards
+- `AWText` — `text`, `size`, `color`, `bold`, `italic`, `align`, `max_lines`, `id`
+- `AWImage` — `resource`, `path`, `scale_type`, `content_description`, `id`
+- `AWButton` — `text`, `id`
+- `AWProgressBar` — `style`, `max`, `id`
+
+Layout children with an `id` become runtime handles: the generated Java loads images from `context.getFilesDir()/app/assets/...` for `AWImage(path=...)` at add-time. `tap_to_open=True` wires `@+id/widget_root` to a `PendingIntent` opening the app (with the API-23 `FLAG_IMMUTABLE` guard).
+
+Runtime updates
+---
+Add widgets to the home screen from Python at runtime (see `using-python-to-update-widget.md` for the manual version). `update_period_ms` cannot go below 1 800 000 ms on Android.
+
+Widget & feature recipes: [examples.md](examples.md) (clock, battery meter, photo, button, card layouts, multiple widgets per app, and the runtime update API).
+
+Tests
+---
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Manual fallback
+---
+Prefer the DSL above. If you need full control, the original manual method still works: hand-write the layout/provider XML, the Java `AppWidgetProvider` and the manifest hook (see below).
+
+### Step 1: Design the layout
+Store in `res/layout/simple_widget.xml`:
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:orientation="vertical"
+    android:padding="10dp"
+    android:background="#FFFFFF"
+    android:gravity="center"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content">
+
+    <TextView
+        android:id="@+id/widget_text"
+        android:text="Loading..."
+        android:textSize="18sp"
+        android:textColor="#000"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"/>
+
+</LinearLayout>
+```
+### Step 2: Create the widget info XML
+Path: `res/xml/widgetproviderinfo.xml`
+```xml
+<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
+    android:minWidth="120dp"
+    android:minHeight="60dp"
+    android:updatePeriodMillis="1800000"
+    android:initialLayout="@layout/simple_widget"
+    android:previewImage="@drawable/ic_launcher_foreground"
+    android:resizeMode="horizontal|vertical"
+    android:widgetCategory="home_screen">
+</appwidget-provider>
+```
+Create the preview image at `res/drawable/ic_launcher_foreground.png`.
+
+### Step 3: Create an `AppWidgetProvider`
+Path: `src/SimpleWidget.java`
+```java
+package org.wally.waller; // Change here from buildozer.spec package.domain+package.name
+
+import android.appwidget.AppWidgetManager;
+import android.appwidget.AppWidgetProvider;
+import android.content.Context;
+import android.widget.RemoteViews;
+
+import org.wally.waller.R; // Change here from buildozer.spec package.domain+package.name
+import android.app.PendingIntent;
+import android.content.Intent;
+
+public class SimpleWidget extends AppWidgetProvider {
+
+    @Override
+    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
+        for (int appWidgetId : appWidgetIds) {
+
+            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.simple_widget);
+
+            // Example: Set text
+            views.setTextViewText(R.id.widget_text, "Hello Widget!");
+
+            // Update widget
+            appWidgetManager.updateAppWidget(appWidgetId, views);
+        }
+    }
+}
+```
+
+### Step 4: Inject the receiver with a p4a hook
+Path: `p4a/hook.py`
+```py
+from pathlib import Path
+from pythonforandroid.toolchain import ToolchainCL
+
+
+def after_apk_build(toolchain: ToolchainCL):
+    manifest_file = Path(toolchain._dist.dist_dir) / "src" / "main" / "AndroidManifest.xml"
+    text = manifest_file.read_text(encoding="utf-8")
+
+    package = "org.wally.waller"
+    receiver_xml = f'''
+    <receiver android:name="{package}.SimpleWidget"
+              android:enabled="true"
+              android:exported="false">
+        <intent-filter>
+            <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
+        </intent-filter>
+        <meta-data android:name="android.appwidget.provider"
+               android:resource="@xml/widgetproviderinfo" />
+    </receiver>
+    '''
+
+    if receiver_xml.strip() not in text:
+        if "</application>" in text:
+            text = text.replace("</application>", f"{receiver_xml}\n</application>")
+            print("Receiver added")
+        else: 
+            print("Could not find </application> to insert receiver")
+    else: 
+        print("Receiver already exists in manifest")
+
+    manifest_file.write_text(text, encoding="utf-8")
+    print("Successfully_101: Manifest update completed successfully!")
+```
+
+### Step 5: Wire into `buildozer.spec`
+```ini
+android.add_resources = res
+android.add_src = src
+p4a.hook = p4a/hook.py
+```
+
+Sample Image:
+
+![Rounded corners widget](https://raw.githubusercontent.com/Fector101/kivy-androidwidgets/main/imgs/not-rounded.jpg)
+
+### For more widget customisation check: [How to Customise.md](how-to-customise.md)

android_widgets-0.1.8/README.md

@@ -0,0 +1,217 @@
+Kivy-androidwidgets
+---
+Generate Android home-screen widgets for Kivy / Buildozer apps from a pure-Python DSL — **no XML, no Java**. Widget definitions are compiled by a CLI pre-build step into `res/`, `src/` and a p4a hook that Buildozer compiles straight into the APK.
+
+Complete sample: [working app](https://github.com/Fector101/wallpaper-carousel)
+
+Quickstart
+---
+### 1. Install
+```bash
+pip install kivy-androidwidgets
+```
+
+### 2. Describe your widget in Python
+
+`widgets.py` (in your project root):
+
+```python
+from android_widgets import HomeWidget, AWColumn, AWRow, AWText, AWImage, AWButton, AWProgressBar, Color
+
+clock = HomeWidget(
+    name="Clock",
+    description="Shows the current time",
+    layout=AWColumn(
+        spacing=6,
+        children=[
+            AWText("12:00", id="time", size=28, bold=True),
+            AWText("Mon 4 Aug", id="date", size=12, color=Color("#888888")),
+        ],
+    ),
+    min_width_dp=110,          # 2 cells
+    min_height_dp=110,
+    resize_mode="horizontal|vertical",
+    update_period_ms=1800000,  # Android minimum: 30 minutes
+    tap_to_open=True,          # whole widget opens the app on tap
+    background=Color("#FFFFFF"),
+    radius=12,
+)
+```
+
+### 3. Generate the Android artifacts
+
+```bash
+python -m android_widgets init     # creates p4a/hook.py (one-time)
+python -m android_widgets generate --spec buildozer.spec --module widgets.py
+```
+
+This writes (gitignore them):
+- `res/layout/<name>.xml`, `res/layout/<name>_preview.xml`
+- `res/xml/<name>_provider.xml` — the `appwidget-provider` metadata
+- `res/drawable/widget_bg_<name>.xml` — rounded background shapes
+- `src/<package>/<ClassName>.java` — one `AppWidgetProvider` per widget
+- `res/values/widgets.xml`, `p4a/widget_receivers.json`
+
+`generate` reads `package.domain` + `package.name` from `buildozer.spec`. Use `--dry-run` to preview without writing.
+
+### 4. Wire it into `buildozer.spec`
+
+```ini
+android.add_resources = res
+android.add_src = src
+p4a.hook = p4a/hook.py
+```
+
+### 5. Build
+```bash
+buildozer android debug
+```
+
+The generated `p4a/hook.py` (`after_apk_build`) injects the `<receiver>` entries into the dist's `AndroidManifest.xml` before aapt compiles it, so no manual manifest editing.
+
+DSL Reference
+---
+- `HomeWidget` — `name`, `description`, `layout`, `min_width_dp`, `min_height_dp`, `target_cells`, `max_cells`, `resize_mode`, `widget_category`, `update_period_ms`, `preview_image`, `preview_layout`, `tap_to_open`, `background` (`Color`), `radius`, `padding`
+- `AWColumn`, `AWRow` — `spacing`, `children`
+- `AWFrame` — single child, ideal for cards
+- `AWText` — `text`, `size`, `color`, `bold`, `italic`, `align`, `max_lines`, `id`
+- `AWImage` — `resource`, `path`, `scale_type`, `content_description`, `id`
+- `AWButton` — `text`, `id`
+- `AWProgressBar` — `style`, `max`, `id`
+
+Layout children with an `id` become runtime handles: the generated Java loads images from `context.getFilesDir()/app/assets/...` for `AWImage(path=...)` at add-time. `tap_to_open=True` wires `@+id/widget_root` to a `PendingIntent` opening the app (with the API-23 `FLAG_IMMUTABLE` guard).
+
+Runtime updates
+---
+Add widgets to the home screen from Python at runtime (see `using-python-to-update-widget.md` for the manual version). `update_period_ms` cannot go below 1 800 000 ms on Android.
+
+Widget & feature recipes: [examples.md](examples.md) (clock, battery meter, photo, button, card layouts, multiple widgets per app, and the runtime update API).
+
+Tests
+---
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Manual fallback
+---
+Prefer the DSL above. If you need full control, the original manual method still works: hand-write the layout/provider XML, the Java `AppWidgetProvider` and the manifest hook (see below).
+
+### Step 1: Design the layout
+Store in `res/layout/simple_widget.xml`:
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:orientation="vertical"
+    android:padding="10dp"
+    android:background="#FFFFFF"
+    android:gravity="center"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content">
+
+    <TextView
+        android:id="@+id/widget_text"
+        android:text="Loading..."
+        android:textSize="18sp"
+        android:textColor="#000"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"/>
+
+</LinearLayout>
+```
+### Step 2: Create the widget info XML
+Path: `res/xml/widgetproviderinfo.xml`
+```xml
+<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
+    android:minWidth="120dp"
+    android:minHeight="60dp"
+    android:updatePeriodMillis="1800000"
+    android:initialLayout="@layout/simple_widget"
+    android:previewImage="@drawable/ic_launcher_foreground"
+    android:resizeMode="horizontal|vertical"
+    android:widgetCategory="home_screen">
+</appwidget-provider>
+```
+Create the preview image at `res/drawable/ic_launcher_foreground.png`.
+
+### Step 3: Create an `AppWidgetProvider`
+Path: `src/SimpleWidget.java`
+```java
+package org.wally.waller; // Change here from buildozer.spec package.domain+package.name
+
+import android.appwidget.AppWidgetManager;
+import android.appwidget.AppWidgetProvider;
+import android.content.Context;
+import android.widget.RemoteViews;
+
+import org.wally.waller.R; // Change here from buildozer.spec package.domain+package.name
+import android.app.PendingIntent;
+import android.content.Intent;
+
+public class SimpleWidget extends AppWidgetProvider {
+
+    @Override
+    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
+        for (int appWidgetId : appWidgetIds) {
+
+            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.simple_widget);
+
+            // Example: Set text
+            views.setTextViewText(R.id.widget_text, "Hello Widget!");
+
+            // Update widget
+            appWidgetManager.updateAppWidget(appWidgetId, views);
+        }
+    }
+}
+```
+
+### Step 4: Inject the receiver with a p4a hook
+Path: `p4a/hook.py`
+```py
+from pathlib import Path
+from pythonforandroid.toolchain import ToolchainCL
+
+
+def after_apk_build(toolchain: ToolchainCL):
+    manifest_file = Path(toolchain._dist.dist_dir) / "src" / "main" / "AndroidManifest.xml"
+    text = manifest_file.read_text(encoding="utf-8")
+
+    package = "org.wally.waller"
+    receiver_xml = f'''
+    <receiver android:name="{package}.SimpleWidget"
+              android:enabled="true"
+              android:exported="false">
+        <intent-filter>
+            <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
+        </intent-filter>
+        <meta-data android:name="android.appwidget.provider"
+               android:resource="@xml/widgetproviderinfo" />
+    </receiver>
+    '''
+
+    if receiver_xml.strip() not in text:
+        if "</application>" in text:
+            text = text.replace("</application>", f"{receiver_xml}\n</application>")
+            print("Receiver added")
+        else: 
+            print("Could not find </application> to insert receiver")
+    else: 
+        print("Receiver already exists in manifest")
+
+    manifest_file.write_text(text, encoding="utf-8")
+    print("Successfully_101: Manifest update completed successfully!")
+```
+
+### Step 5: Wire into `buildozer.spec`
+```ini
+android.add_resources = res
+android.add_src = src
+p4a.hook = p4a/hook.py
+```
+
+Sample Image:
+
+![Rounded corners widget](https://raw.githubusercontent.com/Fector101/kivy-androidwidgets/main/imgs/not-rounded.jpg)
+
+### For more widget customisation check: [How to Customise.md](how-to-customise.md)

{android_widgets-0.1.6 → android_widgets-0.1.8}/android_widgets/__init__.py

@@ -12,7 +12,7 @@ from .config import get_python_activity_context
 try:
     from .java_classes import *
 except Exception as e:
-    print("[android_widgets] Import Java classes Error:", e)
+    logger.debug(f"Import Java classes Error: {e}")
     from .facade import *
 
     RemoteViews_ = RemoteViews
@@ -20,6 +20,20 @@ except Exception as e:
 
 from .tools import SpecFile
 
+from .generate.nodes import (
+    Color,
+    HomeWidget,
+    AWButton,
+    AWColumn,
+    AWFrame,
+    AWImage,
+    AWProgressBar,
+    AWRow,
+    AWText,
+)
+
+from .runtime import get_widget_data, save_widget_data, update_widget
+
 if is_platform_android():
     enable_logging()
 

android_widgets-0.1.8/android_widgets/__main__.py

@@ -0,0 +1,4 @@
+from .generate.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

android_widgets-0.1.8/android_widgets/generate/__init__.py

@@ -0,0 +1,32 @@
+"""Build-time generators: turn the Python DSL into Android res/src artifacts."""
+
+from .nodes import (
+    Color,
+    HomeWidget,
+    AWButton,
+    AWColumn,
+    AWFrame,
+    AWImage,
+    AWProgressBar,
+    AWRow,
+    AWText,
+)
+from .generator import collect_widgets, generate
+from .manifest import inject_receivers, inject_widget_receivers, receivers_from_widgets
+
+__all__ = [
+    "Color",
+    "HomeWidget",
+    "AWButton",
+    "AWColumn",
+    "AWFrame",
+    "AWImage",
+    "AWProgressBar",
+    "AWRow",
+    "AWText",
+    "collect_widgets",
+    "generate",
+    "inject_receivers",
+    "inject_widget_receivers",
+    "receivers_from_widgets",
+]

android_widgets-0.1.8/android_widgets/generate/bindings.py

@@ -0,0 +1,58 @@
+"""Describe which layout nodes are runtime-updatable and their data keys.
+
+Both the generated Java (reads the keys in onUpdate) and the Python runtime
+(writes the keys before broadcasting an update) must agree on the key format,
+so this module is shared and kept free of Android dependencies.
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from . import nodes
+from .xml import to_snake
+
+PREFERENCES_NAME = "android_widgets"
+
+TEXT = "text"
+BUTTON = "button"
+IMAGE = "image"
+PROGRESS = "progress"
+
+
+@dataclass
+class DataBinding:
+    view_id: str
+    kind: str
+    default: str
+    max: Optional[int] = None
+
+    @property
+    def java_setter(self) -> str:
+        return {
+            TEXT: "setTextViewText",
+            BUTTON: "setTextViewText",
+            IMAGE: "setImageViewBitmap",
+            PROGRESS: "setProgressBar",
+        }[self.kind]
+
+
+def data_bindings(home_widget: nodes.HomeWidget) -> List[DataBinding]:
+    """Collect runtime-updatable nodes (those with an id) from the tree."""
+    binds: List[DataBinding] = []
+    for node in home_widget.layout.iter_nodes():
+        if not node.id:
+            continue
+        if isinstance(node, nodes.AWText):
+            binds.append(DataBinding(node.id, TEXT, node.text))
+        elif isinstance(node, nodes.AWButton):
+            binds.append(DataBinding(node.id, BUTTON, node.text))
+        elif isinstance(node, nodes.AWProgressBar):
+            binds.append(DataBinding(node.id, PROGRESS, "0", node.max))
+        elif isinstance(node, nodes.AWImage) and node.path:
+            binds.append(DataBinding(node.id, IMAGE, node.path))
+    return binds
+
+
+def data_key(widget_name: str, view_id: str) -> str:
+    """SharedPreferences key for a runtime-updatable field."""
+    return f"{to_snake(widget_name)}.{view_id}"

android_widgets-0.1.8/android_widgets/generate/cli.py

@@ -0,0 +1,102 @@
+"""Command line interface: `python -m android_widgets generate`."""
+
+import argparse
+import os
+import sys
+
+from ..tools import SpecFile
+from .generator import collect_widgets, generate, load_widget_module
+
+
+def _package_from_spec(spec_path: str) -> str:
+    spec = SpecFile(spec_path)
+    domain = spec.get("app", "package.domain")
+    name = spec.get("app", "package.name")
+    if not domain or not name:
+        raise SystemExit(
+            f"Error: buildozer.spec at {spec_path} is missing "
+            f"package.domain or package.name"
+        )
+    return f"{domain}.{name}"
+
+
+def cmd_generate(args) -> int:
+    if not os.path.exists(args.spec):
+        raise SystemExit(f"Error: buildozer.spec not found at {args.spec}")
+    package = _package_from_spec(args.spec)
+
+    module_path = os.path.abspath(args.module)
+    if not os.path.exists(module_path):
+        raise SystemExit(f"Error: widget module not found at {module_path}")
+    module = load_widget_module(module_path, base_dir=args.out)
+    widgets = collect_widgets(module)
+    if not widgets:
+        print(f"Warning: no HomeWidget definitions found in {module_path}")
+
+    written = generate(widgets, package=package, out_dir=args.out, dry_run=args.dry_run)
+
+    mode = "Would generate" if args.dry_run else "Generated"
+    print(f"{mode} {len(written)} file(s) for {len(widgets)} widget(s):")
+    for path in written:
+        print(f"  {path}")
+    if not args.dry_run and widgets:
+        print("\nNext: add these to buildozer.spec and run 'buildozer android debug':")
+        print("  android.add_resources = res")
+        print("  android.add_src = src")
+        print("  p4a.hook = p4a/hook.py")
+    return 0
+
+
+def cmd_init(args) -> int:
+    import shutil
+
+    template = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+        "templates",
+        "p4a_hook.py",
+    )
+    out_dir = os.path.join(args.out, "p4a")
+    os.makedirs(out_dir, exist_ok=True)
+    dest = os.path.join(out_dir, "hook.py")
+    if os.path.exists(dest) and not args.force:
+        print(f"Info: {dest} already exists (use --force to overwrite)")
+        return 0
+    shutil.copy(template, dest)
+    print(f"Created {dest}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="android-widgets",
+        description="Generate Android home screen widget resources for Kivy apps.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    gen = sub.add_parser("generate", help="Generate res/ + src/ + p4a hook data")
+    gen.add_argument("--spec", default="buildozer.spec", help="path to buildozer.spec")
+    gen.add_argument(
+        "--module",
+        default="widgets.py",
+        help="Python module containing the HomeWidget definitions",
+    )
+    gen.add_argument("--out", default=".", help="project directory to write into")
+    gen.add_argument("--dry-run", action="store_true", help="print files without writing")
+    gen.set_defaults(func=cmd_generate)
+
+    init = sub.add_parser("init", help="Scaffold p4a/hook.py into the project")
+    init.add_argument("--out", default=".", help="project directory")
+    init.add_argument("--force", action="store_true", help="overwrite existing hook.py")
+    init.set_defaults(func=cmd_init)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())