# About Lila

Lila is a Python framework based on Starlette and Pydantic. Designed for developers seeking simplicity, flexibility, and robustness, it enables efficient and customizable Web or API application development. Its modular structure and support for advanced configurations make it suitable for both beginners and experienced developers.

# Acerca de Lila (Español)

Lila es un framework de Python basado en Starlette y Pydantic. Diseñado para desarrolladores que buscan simplicidad, flexibilidad y robustez, permite crear aplicaciones Web o APIs de manera eficiente y personalizable. Su estructura modular y soporte para configuraciones avanzadas lo hacen ideal tanto para principiantes como para desarrolladores experimentados.

# Learning Lila

https://seip25.github.io/Lila

# Documentación de Lila

https://seip25.github.io/Lila

https://pypi.org/project/lila-framework/

## Key Features

- **Simplicity**: Intuitive and minimalist design.
- **Flexibility**: Support for multiple databases (MySQL, SQLite) and adaptation to various environments.
- **Speed**: Built on Starlette, known for its high performance in asynchronous applications.
- **Robust Validation**: Uses Pydantic to ensure consistent data.
- **Editable and Configurable**: Ready to use but fully customizable.
- **Multi-language Support**: Integrated support for multilingual applications.
- **Compatibility**: Can be used with frameworks like Next.js, Remix, and others.
- **Easy Migrations**: Quick and straightforward database configuration.
- **Jinja2 and HTML Sessions**: Ready-to-use with dynamic templates and session handling, while remaining compatible with React, Angular, Vue, and other frontend frameworks.
- **SQLAlchemy** :For the ORM or you can also use the connectors directly (mysql.connector, sqlite3, etc...)
- **JWT** :It comes integrated with helpers to generate tokens and the middleware already has a function that validates it.
- **Admin Panel**: Includes a built-in admin panel for easy management of your application's data and settings.
- **Robust Security**: Features IP blocking, URL filtering, and request sanitization to prevent malicious attacks and suspicious requests.
- **REST CRUD Generator**: Generate REST APIs with just a few lines of code. Includes field validations and middleware support.

---

## Características principales

- **Simplicidad**: Diseño intuitivo y minimalista.
- **Flexibilidad**: Soporte para múltiples bases de datos (MySQL, SQLite) y adaptación a diversos entornos.
- **Rapidez**: Basado en Starlette, conocido por su alto rendimiento en aplicaciones asíncronas.
- **Validación robusta**: Uso de Pydantic para garantizar datos consistentes.
- **Editable y configurable**: Todo está listo para usar, pero también es completamente personalizable.
- **Multi-idioma**: Soporte integrado para aplicaciones multilingües.
- **Compatibilidad**: Puede ser utilizado con frameworks como Next.js, Remix js, entre otros.
- **Migraciones sencillas**: Configuración rápida y fácil para bases de datos.
- **Jinja2 y sesiones HTML**: Listo para usar con plantillas dinámicas y manejo de sesiones, pero compatible con React, Angular, Vue, entre otros frameworks frontend.
- **SQLAlchemy** :Para la ORM o también se puede utilizar los connectores directamente(mysql.connector,sqlite3,etc...)
- **JWT** :Viene integrado con helpers para generar token y en el middleware ya viene una función que válida el mismo.
- **Panel de Administración**: Incluye un panel de administración integrado para gestionar fácilmente los datos y configuraciones de tu aplicación.
- **Seguridad Robusta**: Cuenta con bloqueo de IPs, filtrado de URLs y sanitización de solicitudes para prevenir ataques maliciosos y solicitudes sospechosas.
- **Generador de APIs REST**: Genera APIs REST con solo unas pocas líneas de código. Incluye validaciones de campos y soporte para middlewares.

---

## Installation (Instalación)

## Installation

### English

1. Install Lila Framework using pip:

```bash
   pip install lila-framework

```

2. Initialize your Lila project:

```bash
 lila-init

```

3. Run application:

```bash
   python app.py
```

---

### Español

1. Instala Lila Framework usando pip:

```bash
   pip install lila-framework

```

2. Inicializa tu proyecto Lila:

```bash
 lila-init

```

3. Ejecutar aplicación:

```bash
   python app.py
```

---

# Lila Framework

Lila is a high-performance Python web framework built on **Starlette** + **Pydantic** + **SQLAlchemy**.
Designed for rapid full-stack development with async support, ORM, templates, CLI scaffolding, and admin panel.

## Project Structure

```
lila/
├── main.py                  # App entry point (uvicorn, routes, middlewares)
├── core/                    # Framework core
│   ├── app.py               # App class (extends Starlette) with error handling, CORS, compression
│   ├── routing.py           # Router with HTTP decorators, WebSocket, REST CRUD generation, OpenAPI/Swagger
│   ├── database.py          # Database class (SQLAlchemy: MySQL, PostgreSQL, SQLite)
│   ├── templates.py         # Jinja2 render, React Islands (renderReact), Markdown, Vite assets
│   ├── session.py           # Signed cookie sessions via itsdangerous
│   ├── responses.py         # JSONResponse (auto-serialize), HTMLResponse, RedirectResponse, StreamingResponse
│   ├── admin.py             # Admin panel (dashboard, metrics, model CRUD, log viewer)
│   ├── logger.py            # File-based Logger (error, warning, info) + request logging
│   ├── debug.py             # Debug middleware (RAM, CPU, execution time per request)
│   ├── translate.py         # Translate class (set/get language via session)
│   ├── middleware.py         # Re-export of Starlette Middleware
│   ├── controller.py        # RequestParser (body/query validation via Pydantic)
│   ├── request.py           # Re-export of Starlette Request
│   └── background.py        # Re-export of Starlette BackgroundTask
├── app/
│   ├── config.py            # Environment config (.env): DEBUG, SECRET_KEY, paths, project meta
│   ├── connections.py       # Database connection instances
│   ├── helpers/
│   │   ├── security.py      # JWT tokens (generate, verify), password hashing (argon2)
│   │   ├── translate.py     # Translation loading from JSON, language detection
│   │   ├── files.py         # File upload utilities
│   │   ├── validate.py      # Validation helpers
│   │   └── env.py           # Environment helpers
│   ├── locales/             # JSON translation files (i18n)
│   ├── middlewares/         # Custom middleware (security, logging, rate-limit)
│   ├── models/              # SQLAlchemy models
│   └── routes/              # Route definitions (routes.py, api.py, admin.py)
├── cli/                     # CLI tools (scaffold, model gen, migrations, auth, admin, React, minify)
├── templates/               # Jinja2 HTML templates
└── public/                  # Static files (css, js, img)
```

## Core Concepts

### Routing (`core/routing.py`)

- `Router(prefix)`: Group routes under a prefix.
- Decorators: `@router.get("/")`, `@router.post("/")`, `@router.put("/")`, `@router.delete("/")`, `@router.patch("/")`, `@router.websocket("/ws")`.
- `router.route(path, methods, model)`: Generic route decorator with optional Pydantic model for OpenAPI docs.
- `router.rest_crud_generate(...)`: Auto-generates GET all, GET by id, POST, PUT, DELETE endpoints + HTML CRUD view.
- `router.swagger_ui()` / `router.openapi_json()`: Auto-generated API documentation.
- Path parameters: `/{id}` with type conversion.

### Database (`core/database.py`)

- `Database(config)`: Supports `sqlite`, `mysql`, `postgresql`/`psgr`. Auto-creates database if not exists.
- `db.connect()`: Establish connection.
- `db.query(query, params, return_rows, return_row)`: Raw SQL queries.
- `db.query_orm(model, operation, instance, session, filters, values)`: ORM operations (select, insert, update, delete).
- `db.migrate(use_base)`: Run migrations.
- `Base`: SQLAlchemy declarative base for model definitions.

### Templates (`core/templates.py`)

- `render(request, template, context, files_translate, lang_default)`: Render Jinja2 HTML.
- `renderReact(request, component, props, options)`: Render React component as island with SSR-friendly output.
- `renderMarkdown(request, file, css_files, js_files)`: Render Markdown files as HTML pages.
- `react(component, props)`: Generate React mount point div.
- `vite_assets()`: Dev (hot reload) or production (manifest) Vite asset tags.
- Templates auto-inject: `title`, `version`, `lang`, `translate`, `description`, `keywords`, `author`.

### Session (`core/session.py`)

- `Session.setSession(new_val, response, name_cookie, max_age, ...)`: Create signed cookie.
- `Session.unsign(key, request, max_age)`: Read and verify signed cookie.
- `Session.getSessionValue(request, key, max_age)`: Convenience wrapper for unsign.
- `Session.deleteSession(response, name_cookie)`: Remove session cookie.

### App (`core/app.py`)

- `App(debug, routes, cors, middleware, compress_type, trusted_hosts, public_folder, on_startup, on_shutdown)`.
- Built-in 404/500 error pages (detailed trace in DEBUG mode).
- Compression: gzip (default) or zstd.
- Debug mode: adds DebugMiddleware + debug panel at `/debug`.

### Responses (`core/responses.py`)

- `JSONResponse(data, status_code, serialize, headers)`: Auto-serializes Decimal, datetime, Pydantic models.
- `HTMLResponse`, `RedirectResponse`, `PlainTextResponse`, `StreamingResponse`.

### Security (`app/helpers/security.py`)

- `generate_token(name, value, minutes)`: JWT token generation.
- `get_token(token)`: Decode JWT from Authorization header.
- `get_user_by_token(request, key)`: Extract user ID from authorization token.
- Password hashing: argon2 via `PasswordHasher`.

### i18n (`app/helpers/translate.py`)

- Translation files: `app/locales/*.json` with `{"key": {"en": "...", "es": "..."}` format.
- `translate(file_name, request)`: Returns translated dict for current language.
- Language set via session cookie (`lang`).

### CLI Commands

- `lila-init`: Initialize project structure.
- `lila-model`: Generate SQLAlchemy model.
- `lila-scaffold_crud`: Generate full REST CRUD + HTML interface.
- `lila-auth`: Scaffold authentication system.
- `lila-admin`: Generate admin panel.
- `lila-migrations`: Run database migrations.
- `lila-minify`: Minify CSS/JS for production.
- `lila-react`: Set up React + Vite integration.

## Key Patterns

### Adding a new route

```python
from lila.core.routing import Router
from lila.core.request import Request
from lila.core.responses import JSONResponse

router = Router("api")

@router.get("/items")
async def get_items(request: Request):
    return JSONResponse({"items": []})
```

### Database query

```python
from app.connections import connection

items = connection.query("SELECT * FROM items WHERE active = 1", return_rows=True)
item = connection.query("SELECT * FROM items WHERE id = :id", params={"id": 1}, return_row=True)
```

### ORM operations

```python
session = connection.get_session()
new_id = connection.query_orm(model=Item, operation="insert", instance=Item(name="x"), session=session)
items = connection.query_orm(model=Item, operation="select", filters={"active": 1})
connection.query_orm(model=Item, operation="update", filters={"id": 1}, values={"name": "y"})
connection.query_orm(model=Item, operation="delete", filters={"id": 1})
```

### Template rendering

```python
from lila.core.templates import render
return render(request=request, template="pages/home", context={"items": items})
```

### Session usage

```python
from lila.core.session import Session
Session.setSession(new_val={"user_id": 1}, response=response, name_cookie="auth")
data = Session.unsign(key="auth", request=request, max_age=3600)
```

## Configuration (`.env`)

```
SECRET_KEY=your-secret-key
DEBUG=True
PORT=8001
HOST=127.0.0.1
TITLE_PROJECT=My App
LANG_DEFAULT=en
```

## Important Notes

- All route handlers are `async` functions receiving a Starlette `Request` object.
- Pydantic models are used for validation in `rest_crud_generate` and `RequestParser`.
- Passwords are auto-hashed with argon2 when `password` field is present in CRUD operations.
- `delete_old_logs(days=30)` runs on startup via `on_startup` lifecycle event.
- Production: set `DEBUG=False`, enable `trusted_hosts`, configure CORS properly.

## Contributions (Contribuciones)

At this stage, all official modifications to the framework will be made only by the original author. However, any feedback or suggestions to improve the project are welcome.

Actualmente, todas las modificaciones oficiales al framework serán realizadas únicamente por el autor original. Sin embargo, se agradece cualquier comentario o sugerencia que pueda mejorar el proyecto.
