Metadata-Version: 2.4
Name: apkpy
Version: 0.9.1
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 Banner](https://raw.githubusercontent.com/martim43w-sudo/Tugalandbot/main/Captura%20de%20ecr%C3%A3%202026-04-23%20210450.png)



**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!
- **`font-size: 18px;`** – Set text size in pixels (automatically converted to `sp` for Android).
- **`font-weight: bold;`** – Makes your text thicker. Supports `bold` or numeric values (`700`, `800`, `900`).
- **`font-family: 'sans-serif';`** – Choose between native font styles.

### Typography Support 🔠
ApkPy ensures your text looks great and consistent across platforms by mapping CSS generic families to native system fonts:
- **`sans-serif`**: The modern look. Maps to **Roboto** (Android) and **Segoe UI** (Windows) or **Helvetica** (macOS).
- **`serif`**: The classic look. Maps to **Times New Roman**.
- **`monospace`**: Perfect for code or alignment. Maps to **Consolas** (Windows) or **Courier**.

*Note: You can also use `font-style: italic;` to add emphasis to your labels.*

## 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!

![Hot Previewer Screenshot](https://raw.githubusercontent.com/martim43w-sudo/Tugalandbot/main/Captura%20de%20ecr%C3%A3%202026-04-22%20200253.png)



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

---

## 8. Spacing & Margins (Precision Layout) 📐

Margins allow you to create "invisible space" around your components. This is essential for moving buttons down, separating inputs, or creating breathing room between elements.

### Example Code:
```css
my_button {
    /* Move the button 50 pixels down from whatever is above it */
    margin-top: 50px;
    
    /* Push the button 20 pixels away from the left edge */
    margin-left: 20px;
}

header {
    /* Put a 30 pixel gap at the bottom of the title */
    margin-bottom: 30px;
}
```

### Margin Guide (For Absolute Beginners):

| Property | What it does (in simple terms) |
| :--- | :--- |
| **`margin`** | Adds space to **all four sides** (top, bottom, left, and right) at once. It's like putting a bubble around the whole component. |
| **`margin-top`** | Pushes the component **down**. It adds space to the top edge. Use this if you want something to move lower on the screen. |
| **`margin-bottom`** | Pushes the *next* component **away**. It adds space to the bottom edge. |
| **`margin-left`** | Pushes the component to the **right**. It adds space to the left side. |
| **`margin-right`** | Pushes the component to the **left**. It adds space to the right side. |

> [!TIP]
> In ApkPy, you can use `px` (like `20px`). The compiler automatically converts this to `dp` for Android, so your app looks perfect on every phone screen size!

---

## 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;
    font-size: 24px;
    font-weight: bold;
}

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)
```

---

---

## 11. Declarative CSS Animations 🎬 (v0.9.0)

ApkPy now supports **native declarative animations** using a syntax inspired by CSS Keyframes. You can define how a component should transition from one state to another, and the framework will generate the corresponding native Android `Animation` XML and Java logic.

### How it Works: The `@keyframes` Block

An animation is defined using the `@keyframes` keyword followed by a name. Inside, you define two states:
- **`from` (or `0%`)**: The starting state of the component when it appears.
- **`to` (or `100%`)**: The final state where the component should end.

```css
@keyframes slideUp {
  from { 
      opacity: 0; 
      margin-top: 50px; 
  }
  to { 
      opacity: 1; 
      margin-top: 0px; 
  }
}
```

### Applying the Animation

To trigger an animation, use these two properties on your component ID:
- **`animation-name`**: The name of the `@keyframes` block you defined.
- **`animation-duration`**: How long the animation lasts (e.g., `1000ms` or `2s`).

```css
my_button {
    animation-name: slideUp;
    animation-duration: 1500ms;
}
```

### Supported Properties:

| Property | Description | Example |
| :--- | :--- | :--- |
| **`opacity`** | Fades the component in or out (0.0 is invisible, 1.0 is solid). | `opacity: 0;` to `opacity: 1;` |
| **`margin-top`** | Moves the component vertically (Y-axis). | `margin-top: 100px;` to `0px;` |
| **`margin-left`** | Moves the component horizontally (X-axis). | `margin-left: -50px;` to `0px;` |
| **`scale`** | Resizes the component (1.0 is normal size). | `scale: 0.5;` to `scale: 1.0;` |

### Pro Examples for your App:

#### 1. Smooth Fade-In (Entry Effect)
Makes your title or logo appear slowly from nothing.
```css
@keyframes fadeIn {
    from { opacity: 0; }
    to { opacity: 1; }
}
```

#### 2. The "Pop" Effect (Scaling)
Makes a button grow into its place.
```css
@keyframes pop {
    from { scale: 0.5; opacity: 0; }
    to { scale: 1.0; opacity: 1; }
}
```

#### 3. Side Slide (Horizontal Entry)
Slides a component from the left edge into its position.
```css
@keyframes slideFromLeft {
    from { margin-left: -200px; opacity: 0; }
    to { margin-left: 0px; opacity: 1; }
}
```

![Animation Preview](https://raw.githubusercontent.com/teu-usuario/apkpy/main/assets/preview.png)

> [!IMPORTANT]
> **Cross-Platform Support**: These animations are fully functional in the **Tkinter Previewer** (Phase 1) so you can test the "vibe" of your app, and they are compiled into **Native Android XML** (Phase 2) for maximum performance on real devices.

---

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