Metadata-Version: 2.4
Name: nexora-framework
Version: 0.1.0
Summary: Nexora modular Python web framework
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Nexora

A modular Python web framework — MVC + ORM + Middleware + Dependency Injection.

## Structure

- core/foundation      -> Front Controller, bootstrap
- core/routing         -> Router
- core/http            -> Request / Response
- core/container       -> Dependency Injection
- controllers          -> Controllers (MVC)
- views/engine         -> View Engine
- views/templates      -> Templates
- models               -> Models (ORM entities)
- database/connection  -> DB connection
- database/query_builder -> Query Builder / DQL
- database/orm         -> ORM
- database/migrations  -> Migrations
- middleware           -> Middleware pipeline
- auth                 -> Authentication
- validation           -> Validation
- session              -> Sessions / Cookies
- security/csrf        -> CSRF protection
- cli                  -> CLI tools
- tests                -> Testing
- config               -> Configuration files

## Template engine

Nexora includes its own dependency-free engine in `views/engine`:

```python
from views.engine import TemplateEngine

views = TemplateEngine()
html = views.render("pages/home.html", {"title": "Accueil", "user": user})
```

Templates escape variables by default (`{{ user.name }}`) and support `safe`,
`upper`, and `lower` filters, `{% if %}`, `{% for %}`, `{% include %}`, and
layout inheritance through `{% extends %}` / `{% block %}`. Include paths are
resolved from `views/templates`; parent-template paths are relative to the
template that declares them.

## Forms

```python
from forms import EmailField, Form, PasswordField

form = Form(action="/login", csrf_token=request.csrf_token)
form.add(EmailField("email", required=True)).add(PasswordField("password", required=True))

if request.method == "POST" and form.bind(request).is_valid():
    authenticate(**form.cleaned_data)
return form.render("Connexion")
```

Available fields: `TextField`, `EmailField`, `PasswordField`, `TextAreaField`,
`SelectField`, `CheckboxField`, and `HiddenField`.

## Environment

Copy `.env.example` into a local `.env` file, then configure the values for your
environment. The `.env` file is ignored by Git. Configuration can be read with:

```python
from config import env, load_settings

settings = load_settings()
debug = env("APP_DEBUG", cast=bool)
```

## Database

`app.bootstrap()` exposes the configured database as `app.make("database")`.
The SQLite engine provides safe parameterized queries, nested transactions,
migrations, and a fluent query builder:

```python
users = app.make("database").table("users")
users.insert({"name": "Ada", "age": 36})
active_users = users.where("age", 18, ">=").order_by("name").get()
```

## Create a project

Install Nexora in a virtual environment once, then create an application just
as you would with Symfony or Laravel:

```bash
cd ~/Bureau/Nexora
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
nexora new my-blog
cd my-blog
nexora serve
```

Do not use `--break-system-packages`: Ubuntu protects its system Python through
PEP 668. Without installation, run the local equivalent:
`python3 bin/nexora new my-blog`.

## Use as a Python framework

Nexora exposes a stable public package. Application code should import from
`nexora`, rather than the internal `core`, `database`, or `views` folders:

```python
from nexora import Application, Request, Response

app = Application().bootstrap()

@app.get("/")
def home(request: Request):
    return Response("Hello from Nexora")
```

After activating the virtual environment, `python -m pip install -e .` makes
both `import nexora` and the `nexora` command available in any project.

For a global installation with `pipx`, see [the installation guide](docs/INSTALLATION.md).
