apkpy 0.4.0

A simple framework to build Android apps using Python and CSS-like styling

🚀 ApkPy — Build Android Apps in Pure Python

ApkPy is a revolutionary transpiler framework that empowers you to build native Android applications using only Python and CSS-style definitions. We don't use WebViews or heavy runtime rendering engines. ApkPy parses your Python logic and directly generates pure Android Java and XML components, ready to be compiled into a lightning-fast .apk.

---

1. The Vision 🌟

Forget the steep learning curves of Java, Kotlin, or the massive footprint of cross-platform engines. Why choose ApkPy over interpreted frameworks like Kivy or Flet?

• Smaller APK Sizes: Since we transpile to pure Android projects, you avoid bundling heavy Python interpreters or WebView packages into your deployment.
• Flawless Performance: By generating true native Activity, Button, and EditText elements under the hood, your app runs at the maximum possible speed the OS allows.
• 100% Native Look & Feel: Because your components interact directly with the Android SDK, OS-level features like haptics, text-selection, and system animations are preserved automatically.

2. How it Works (The Technical Secret) 🛠️

How it works: ApkPy parses your Python code into an Abstract Syntax Tree (AST) and maps UI calls to their corresponding Android XML Layouts and Java Activity classes. It's not a simulation; it's code generation.

3. Full Installation & Setup 📥

Getting started is instantly accessible. You do not need any prior knowledge of Android Studio to start designing.

pip install apkpy

(Need the new features? Run pip install --upgrade apkpy)

4. Complete Syntax Guide (v0.4.0 Standard) 🎨

ApkPy v0.4.0 introduces the easiest way to organize and style your multi-screen applications.

The Screen

Everything belongs to a Screen. Screens translate directly to native Android Activities.

login_screen = Screen(id="login_container")

The CSS Engine

Say goodbye to complex dictionary configurations. ApkPy uses a multi-line string approach with standard CSS syntax. No quotes are needed around values!

style = """
login_container {
    gap: 15px;
    flex-direction: column;
}
"""

New Layout Features (v0.4.0)

Our Android-generation engine has been upgraded to support massive productivity boosters:

• gap: 20px; – Automatically places calculated dp margins between elements in your layout container.
• flex-direction: row; / column; – Orients your components mapped directly to android:orientation="horizontal" or "vertical".
• padding: 10px 20px; – Pushes text content away from your component edges, built cleanly into native Android XML <padding>.
• focus-border-color: #2196F3; – When a user taps your inputs, ApkPy dynamically swaps the border colors via native <selector> XML states! No manual event bindings required!

5. Component & Logic Workflow ⚙️

Adding elements and routing interactions is declarative and incredibly clean.

Adding Components: Simply call the component and attach it to your screen. Give it an id to map it to your CSS string.

btn = button("Login", id="primary_btn", screen=login_screen)
inputs("Your email", type="text", id="email_input", screen=login_screen)

Linking Logic & Navigation: Instead of fighting with Android Intent classes, handle navigation with a single method.

login_screen.on_click_navigate(button=btn, to=dashboard_screen)

The Application Lifecycle: Your file must end by invoking the execution layer with run().

run(start_screen=login_screen)

6. The Two-Step Execution Flow 🔄

ApkPy makes the development lifecycle effortless via two distinct phases:

Phase 1: Development (Hot Previewer)

Simply run your Python file normally:

python main.py

This instantly boots up our Tkinter-based Hot Previewer on your computer. You get immediate visual feedback for your screens, interactive inputs, focus colors, buttons, and navigation without needing an emulator!

Phase 2: Production (Native Compilation)

When you're ready to deploy, run the CLI tool in your project folder:

apkpy build

This triggers the transpiler! ApkPy generates all Java classes, Manifests, Layouts, and Drawables completely from scratch. Open the resulting bundled .zip project and generate your production .apk!

---

7. FAQ (Quick Answers) ❓

"Does it support Android APIs?" Yes! We are currently expanding support for native permissions, GPS, Camera, and more in upcoming versions.

"Do I need the Android SDK installed?" To write and preview your app using python main.py, no SDK is required. However, apkpy build generates a native Android Studio project. To compile that project into a final .apk, you will need the Android SDK/Java installed on your machine (or just upload the generated folder to a CI/CD service like GitHub Actions).

---

8. Master Example: Modern Styled Login

Here is a fully functional v0.4.0 standard application showing off the power of spacing, inputs, and interactive styling. Just copy, paste, and run!

from apkpy_lib.ui import Screen, button, label, inputs, run

# 1. Initialize Screen
login_screen = Screen(id="login_container")

# 2. Add Native Components
label("Welcome to ApkPy v0.4.0", id="title", screen=login_screen)
inputs("Enter Username", type="text", id="fields", screen=login_screen)
inputs("Enter Password", type="password", id="fields", screen=login_screen)

btn_login = button("Sign In", id="btn_primary", screen=login_screen)
btn_register = button("Create Account", id="btn_secondary", screen=login_screen)

# 3. CSS Engine (No quotes needed!)
style = """
login_container {
    flex-direction: column;
    gap: 15px;
    background-color: #f7f9fc;
}

title {
    color: #333333;
}

fields {
    background-color: white;
    border-color: #d1d5db;
    border-radius: 8px;
    padding: 12px;
    focus-border-color: #3b82f6; 
}

btn_primary {
    background-color: #3b82f6;
    color: white;
    border-radius: 12px;
    pressed-color: #2563eb;
}

btn_secondary {
    background-color: none;
    color: #3b82f6;
    border-color: #3b82f6;
    border-radius: 12px;
    border-width: 2px;
    pressed-color: #e5e7eb;
}
"""

# 4. Launch Desktop Preview
run(start_screen=login_screen)

---

🤝 Community & Support

Found a bug? Open an issue on Reddit!

Want to contribute? We are looking for contributors to expand our Native Component library! Join us in making Python a first-class citizen for Android development.