Metadata-Version: 2.4
Name: laith
Version: 0.1.0
Summary: A statically compiled Python to Native Android platform
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: rich
Requires-Dist: tomli
Requires-Dist: jinja2
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"

# Laith

Python → Native Android Compiler Platform.

## Why

I have been doing React Native for half a year and i wanted to dive into Android and RN internals.
After diving i wondered why we don't have a similar project for Python.
I coded this by not following existing projects approaches. 

## What Laith means

Laith (ليث) means lion and is the name of my cat. Could not find a better name.

## Architecture

- **Frontend**: AST-based semantic analysis and type inference.
- **IR**: SSA-based Intermediate Representation.
- **Optimizer**: Multi-pass IR optimization (DCE, Constant Folding).
- **Backend**: Multi-layered emission (Kotlin/Compose + Native C++/JNI).
- **Orchestrator**: Automated Gradle/NDK build system and ADB device runner.

## Usage

```bash
# Initialize a professional project
laith init myapp

# Compile the default entry point (src/main.py)
laith build

# Build the native Android APK
laith compile

# The "Inner Loop": Build, Install, Run, and Stream Logs
laith run
```

## Project Configuration (`laith.toml`)

Laith uses a declarative, versioned manifest to manage the full Android lifecycle.

```toml
# laith.toml
version = "1.0"

[app]
name = "MyAwesomeApp"
namespace = "com.company.awesome"
identity = { id = "com.company.awesome", version_code = 42, version_name = "2.1.0" }

[sdk]
min = 26
target = 34
compile = 34

[dependencies]
implementation = [
    "com.squareup.retrofit2:retrofit:2.9.0",
    "androidx.compose.material3:material3:1.2.0"
]

[features]
compose = true
native = true
```

## Ai Contribution Policy

This project uses AI. If you use Ai and bring sensible improvement, then great. If it's mindless slop, then it wont get reviewed.

## Core Principles

1. **No embedded CPython**: No interpreter overhead; small binaries and fast startup.
2. **Compiled, not interpreted**: Statically analyzed and optimized for the Android runtime.
3. **Native Stack Alignment**: Direct mapping to Compose, Coroutines, and WorkManager.
4. **Zero-JNI Performance**: Automated C++ and JNI bridge generation for native code.

## Supported Python Subset

Laith currently supports a statically-analyzed subset of Python 3.10+:

*   **Syntax**: `def`, `async def`, `return`, assignments, and hierarchical function calls.
*   **Types**: `int`, `str`, `bool`, and `void` (explicit annotations or inferred).
*   **Async/Await**: Full mapping to Kotlin Coroutines for non-blocking I/O and UI.
*   **State Management**: `state(initial_value)` for reactive UI/background synchronization.
*   **IPC**: `Channel()` for event-based communication between layers.
*   **UI Components**: Jetpack Compose DSL (`Column`, `Row`, `Box`, `Text`, `Button`).
*   **Native**: `@native` decorator for high-performance C++ implementation.
*   **Background**: `@periodic_task` (WorkManager) and `@foreground_service` (Android Services).

## Not Supported (Yet)

To maintain high performance and static predictability, the following Python features are **not supported**:

*   **Dynamic Execution**: `eval()`, `exec()`, and dynamic `__import__()`.
*   **Runtime Metaprogramming**: Metaclasses, monkey patching, and dynamic attribute injection.
*   **Reflection**: Unrestricted `getattr`/`setattr` on arbitrary objects.
*   **Classes & Inheritance**: Custom class definitions are planned for Phase 6.
*   **Exception Handling**: `try`/`except` blocks are planned for Phase 7.

## Complete Application Demo

```python
from laith import Column, Text, Button, vibrate

def main_ui():
    Column(
        Text("Laith Vibe Lab"),
        Text("Press buttons to test haptic feedback"),
        
        Button("Quick Vibe (100ms)", on_click=lambda: vibrate(100)),
        Button("Medium Vibe (500ms)", on_click=lambda: vibrate(500)),
        Button("Long Vibe (1s)", on_click=lambda: vibrate(1000))
    )

```

## Why Laith? (Comparison)

Laith represents a fundamental shift in how Python is used for mobile development. Unlike existing tools that wrap an interpreter, Laith treats Python as a high-level frontend for a native compiler.

### vs. Kivy & BeeWare
*   **No Interpreter**: Kivy and BeeWare bundle a full CPython interpreter (libpython) inside your APK. Laith **statically compiles** Python into Kotlin/JVM and C++.
*   **Native UI**: Laith generates real **Jetpack Compose** code, using the exact same primitives as modern Android apps, rather than OpenGL custom views.

### vs. React Native
*   **No Runtime Bridge**: React Native relies on a JavaScript bridge. Laith eliminates this overhead by compiling everything to native bytecode or JNI-linked C++ before the app even runs.
*   **Type Safety**: Laith enforces a strictly typed subset, catching errors at compile-time that would be runtime crashes in JS.

### vs. Flutter
*   **Ecosystem Alignment**: Laith embraces the **Android Native Stack**, mapping Python directly to Kotlin Coroutines, WorkManager, and Jetpack Compose.
*   **Direct NDK Access**: While Flutter requires complex MethodChannels, Laith allows you to mark Python functions with `@native` to generate optimized C++ and automated JNI bridges instantly.
