Metadata-Version: 2.4
Name: evlet
Version: 0.4.4
Summary: A small Python application framework with SQLite and a neutral UI schema
License-Expression: MIT
Project-URL: Homepage, https://github.com/evlet-io/evlet
Project-URL: Repository, https://github.com/evlet-io/evlet
Project-URL: Issues, https://github.com/evlet-io/evlet/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography<52,>=44.0.1
Requires-Dist: packaging<27,>=24
Requires-Dist: uvicorn<1,>=0.34
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.3.6; extra == "postgres"
Requires-Dist: psycopg-pool<4,>=3.3.3; extra == "postgres"
Provides-Extra: s3
Requires-Dist: boto3<2,>=1.43.119; extra == "s3"
Provides-Extra: print
Requires-Dist: weasyprint<71,>=70; extra == "print"
Requires-Dist: jinja2<4,>=3.1; extra == "print"
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: uvicorn<1,>=0.34; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: setuptools>=77.0.3; extra == "dev"
Dynamic: license-file

# Evlet

Evlet is a Python application framework. Define your models in Python and get
forms, lists, permissions and APIs in the browser. SQLite is the default;
PostgreSQL is optional.

## Install, create a site, open it

Use Python 3.12 or newer in a virtual environment:

```sh
python -m pip install --upgrade evlet
evlet setup myproject --app notes --instance acme --dev
```

That one command creates the project, a Notes app and a site called acme,
installs the app and starts `evlet dev` on 127.0.0.1. Read the trust prompt
first. The server prints a one-time sign-in link for a new administrator. Your
site keeps its data when you stop and restart it; run the same command again to
pick up where it stopped.

The same steps one at a time:

```sh
evlet setup myproject
cd myproject
evlet app notes
evlet instance acme
evlet install notes --instance acme
evlet serve acme
```

Every instance has a built-in **System Administrator** (username `admin`) with no
password. `evlet serve` tells you to set one with `evlet users set-password acme admin`;
then open **http://127.0.0.1:8000** and sign in. There is no default password. To serve a site on your own domain behind Caddy, see
[Serve a site on a domain in one go](docs/cli.md#serve-a-site-on-a-domain-in-one-go).

An **app** contains reusable Python code. An **instance** is a site with its own
database, accounts and files. You can install the same app on several instances.
The package includes the browser UI, Playground and offline guides. Node is not
needed to create or serve Python-only apps. App-owned native TS/JS extensions
need Node 24 when building their assets.

The [declarative app guide](docs/amendment-v2.md) covers flat app packages,
owned child tables, reactive fields, dialogs, reports, services and native additions.
[Finite calculations](docs/finite-calculations.md) describe the finite-v1 formula
language, nested owned tables and the shared Python/browser calculation engine.
[States, moves and model actions](docs/states-actions.md) describe document states,
locks and actions with validated inputs. [Document numbers](docs/sequences.md) describe
`Sequence` fields and naming series. [Measures](docs/measures.md) describe exact aggregates, declared model
measures and their HTTP routes.
[Model meaning](docs/meaning.md) describes key fields, related records and
attachment limits.
[Effects](docs/effects.md) describe the rows a
document posts to other models when it enters a state.
[The Journal](docs/journal.md) describes each record's append-only
history, notes and follow ups, and its tamper-evident hash chain.

For virtual environment setup and each step explained, read
[Your first site](docs/getting-started.md).

## Build your app

- [What you can customize](docs/customizing.md): models, lists, pages, actions,
  permissions and migrations, with examples from the Notes starter.
- [CLI guide](docs/cli.md): projects, app sources, instances, trust and deployment
  boundaries.
- [Upgrade or retire an app](docs/app-upgrades.md): the supported workflow today,
  backups and moving a project.
- [Model engine](docs/model-engine.md) and [business capabilities](docs/business-capabilities.md):
  database queries, accounts, child rows, actions and private attachments.
- [UI guide](docs/ui.md): the browser interface and its routes.
- [Reports](docs/reports.md): filters, typed rows, totals, a chart, CSV export and print, in the browser and for Eva.
- [Slips](docs/slips.md): forms presented from code that save nothing until handed in.
- [Routing](docs/routing.md): frontends, reserved paths, `routes.py` and `evlet routes`.
- [API stability](docs/api-stability.md): the names apps can rely on, deprecations and what is internal.
- [UI framework](docs/ui-framework.md): Evlet's own browser framework and components.

`evlet dev --instance acme` reloads Python changes while you work. At startup it
prints a one-time sign-in link, so you can skip the sign-in form. Stop the server
and run `evlet migrate acme` when a model change needs a migration.

## Explore without a project

```sh
evlet playground
evlet docs
```

The Playground uses temporary demo data. Use an instance for records you want to keep. Offline documentation
opens at **http://127.0.0.1:8001**.

`evlet playground` and `evlet dev` print a sign-in link for the built-in Administrator when they start:

```text
The admin account has no password yet. Open this link to sign in and choose one (works once, for 10 minutes):
  http://127.0.0.1:8000/_dev/signin?token=...
```

Open it, choose a password on the "Set your password" screen and, when admins need two-step
sign-in, set up your authenticator app. Once the Administrator has a password the link just
signs you in. Run `evlet dev-link` in another terminal for a fresh link once the first one is
used or expired. Use `--user NAME` to sign in as someone else, or `--no-link` to skip the
link. Links exist only under `evlet playground` and `evlet dev`, never under `evlet serve`;
see [development sign-in links](docs/cli.md#development-sign-in-links).

The sign-in rules live in the instance's `config.py`: `Security(password_min=..., admin_two_step=...,
two_step=..., admin_sign_in=...)`. `password_min=1` allows any password, which is handy on a
development instance. Admins always follow config.py; Controls can change the rules for everyone
else ([controls.md](docs/controls.md#security-rules)).

## Optional capabilities

PostgreSQL, S3 and PDF printing are available as `evlet[postgres]`, `evlet[s3]` and
`evlet[print]` ([print designs](docs/printing.md)). The existing
[tenant deployment](docs/tenancy-deployment.md), [jobs and live updates](docs/jobs-realtime.md),
[connector](docs/connector.md), [Tool Engine](docs/tools.md), [Eva](docs/eva.md), [PostgreSQL](docs/postgresql.md) and
[operations](docs/production-operations.md) guides describe their limits.
No database server, Redis, Docker or worker is required for a local SQLite app.

## Work on Evlet itself

See [the contributor guide](CONTRIBUTING.md) for a source checkout, frontend
builds and package checks. [Milestone notes](docs/internal/milestones.md) record the
completed backend work. Development builds use a `.dev0` version so they can be
distinguished from published packages. This branch contains unreleased fixes.

## License

Evlet uses the [MIT License](LICENSE).
