Metadata-Version: 2.4
Name: apkpy
Version: 0.5.0
Summary: A simple framework to build Android apps using Python and CSS-like styling
Home-page: https://github.com/teu-usuario/apkpy
Author: Martim
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: click
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🚀 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.

```bash
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. 
```python
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!

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

### New Layout & Styling 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.
- **`border-radius: 15px;`** – Generates native XML shape drawables for smooth rounded corners.
- **`border-color: #000;`** and **`border-width: 2px;`** – Easily define component outlines.
- **`pressed-color: #cccccc;`** – Defines the feedback color when a button is clicked (native `<selector>`).
- **`focus-border-color: #2196F3;`** – When a user taps your inputs, ApkPy dynamically swaps the border colors via native XML states!

## 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.
```python
btn = button("Login", id="primary_btn", screen=login_screen)
inputs("Your email", type="text", id="email_input", screen=login_screen)
```

**Supported Input Types:**
ApkPy handles complex input mapping for you:
- `type="text"`: Standard keyboard entry.
- `type="password"`: Secure text entry with hidden characters.
- `type="search"`: Specialized search field with a clear (✕) button.
- `type="checkbox"`: Native Boolean toggle.
- `type="range"`: Interactive slider (0-100).
- `type="radio"`: Selection group (format: `inputs("Option1|Option2", type="radio")`).

**Linking Logic & Navigation:**
Instead of fighting with Android `Intent` classes, handle navigation with a single method.
```python
login_screen.on_click_navigate(button=btn, to=dashboard_screen)
```

**The Application Lifecycle:**
Your file must end by invoking the execution layer with `run()`.
```python
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:
```bash
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:
```bash
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).

---

## 9. Native Permissions & Features 📱

ApkPy allows you to interact directly with Android system features using a simple Python API.

### Declaring Manifest Permissions
Declare what your app needs so the compiler can update `AndroidManifest.xml` automatically.
```python
from apkpy_lib import declare_permissions
declare_permissions(["CAMERA", "LOCATION_FINE", "INTERNET"])
```

### Runtime Permission Requests & Toasts
Prompt users for permissions and provide instant feedback with native Toasts.
```python
from apkpy_lib import permissions, toast

def ask_camera():
    def on_result(granted):
        if granted:
            toast("Camera access granted! 📸")
        else:
            toast("We need camera permission to continue.")
            
    permissions.request("CAMERA", on_response=on_result)
```

---

## 10. Master Example: Mini Profile App 👤

This example tells a short story: It collects a user's name, requests camera permission for a "profile picture," and displays a thank-you toast. It demonstrates inputs, permissions, toasts, and advanced CSS styling.

```python
from apkpy_lib import Screen, button, label, inputs, run, toast, declare_permissions, permissions

# 1. Declare permission for the compiler
declare_permissions(["CAMERA"])

# 2. Setup the Screen
profile_screen = Screen(id="profile_container")

# 3. Logic: Handle Camera Request
def update_photo():
    def on_perm(granted):
        if granted:
            toast("Thanks! Accessing camera for your photo...")
        else:
            toast("We need camera access to take a photo!")
            
    permissions.request("CAMERA", on_response=on_perm)

# 4. Build the UI
label("Mini Profile App", id="header", screen=profile_screen)
inputs("Enter your Full Name", type="text", id="field", screen=profile_screen)
inputs("Short Bio", type="text", id="field", screen=profile_screen)

# Button that triggers permission logic
btn_photo = button("Set Profile Picture", id="btn_outline", command=update_photo, screen=profile_screen)
btn_save = button("Save Profile", id="btn_primary", screen=profile_screen)

# 5. Advanced CSS System
style = """
profile_container {
    flex-direction: column;
    gap: 20px;
    background-color: #ffffff;
}

header {
    color: #1a1a1a;
}

field {
    border-color: #e0e0e0;
    border-radius: 12px;
    padding: 14px;
    focus-border-color: #6200EE;
}

btn_outline {
    background-color: #ffffff;
    color: #6200EE;
    border-color: #6200EE;
    border-width: 2px;
    border-radius: 20px;
    pressed-color: #f3e5f5;
}

btn_primary {
    background-color: #6200EE;
    color: white;
    border-radius: 20px;
    pressed-color: #3700B3;
}
"""

run(start_screen=profile_screen)
```

---

## 🤝 Community & Support

**Found a bug?** [Open an issue on Reddit!](https://www.reddit.com/user/idkaesd/)

**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.
