Metadata-Version: 2.5
Name: alata
Version: 0.12.0.1
Summary: A batteries-included ASGI Python framework on FastAPI and SQLAlchemy
Project-URL: Repository, https://github.com/JoBinsJP/alata-core
Project-URL: Issues, https://github.com/JoBinsJP/alata-core/issues
Author: JoBins
License: MIT License
        
        Copyright (c) 2026 JoBins
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.14.4
Requires-Dist: anyio>=4.14.2
Requires-Dist: asyncpg>=0.31.0
Requires-Dist: certifi>=2026.10.19
Requires-Dist: cleo<3.0.0,>=2.1.0
Requires-Dist: croniter>=6.2.2
Requires-Dist: dotty-dict>=1.3.1
Requires-Dist: fastapi<0.142,>=0.141.1
Requires-Dist: greenlet>=3.3.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: inflection>=0.5.1
Requires-Dist: multidict>=6.9.1
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: redis>=5.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sentry-sdk[fastapi]>=2.48.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.38
Requires-Dist: starlette<1.4,>=1.3.1
Requires-Dist: taskiq-aio-sqs<2.2,>=2.1.1
Requires-Dist: taskiq-redis<1.3,>=1.2.4
Requires-Dist: taskiq<0.14,>=0.13.0
Requires-Dist: tzdata>=2024.1
Requires-Dist: urllib3>=2.8.0
Requires-Dist: uvicorn>=0.40.0
Provides-Extra: dev
Requires-Dist: filelock>=4.2.1; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.16.0; extra == 'dev'
Requires-Dist: virtualenv>=21.14.9; extra == 'dev'
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
Requires-Dist: pymysql>=1.1.0; extra == 'mysql'
Provides-Extra: s3
Requires-Dist: boto3>=1.34.0; extra == 's3'
Provides-Extra: sqlite
Requires-Dist: aiosqlite>=0.20.0; extra == 'sqlite'
Description-Content-Type: text/markdown

# Alata

A Laravel-inspired ASGI Python Framework built on FastAPI and SQLAlchemy.

## Quick Start

```bash
uvx --from alata alata-new new my-project
cd my-project
cp .env.example .env
./alata setup
source .venv/bin/activate
./alata serve
```

The scaffolder requires a new or empty destination directory. Use
`alata-new new .` to scaffold into an empty current directory.

Without activating the environment, use `uv run ./alata <command>`, for example
`uv run ./alata serve`.

Every `./alata` command also works with `python alata`, for example
`python alata serve`, using your environment's Python from the project root.

Use `./alata test`, `./alata lint`, and `./alata format` for everyday development.
Pass pytest or Ruff arguments directly, for example `./alata test -k signup -q`
or `./alata format --check`. Run `./alata list` for all commands.

## Features

- **Service Container** — Laravel-style IoC with dependency injection
- **Eloquent-inspired ORM** — Chainable queries, relationships, eager loading, soft deletes
- **Service Providers** — Modular boot lifecycle (register → boot → boot_http)
- **Config Repository** — Centralized `config()` helper with dot-notation access
- **Queue System** — Taskiq-powered background jobs with Redis/SQS brokers
- **Schema Builder** — Laravel-style migrations with dialect-agnostic DDL
- **Event Dispatcher** — Pub/Sub event system with listeners and subscribers
- **Cache** — Redis-backed caching with `Cache.remember()` and tag support
- **Logging** — Multi-channel logging (console, file, Slack, Sentry)
- **Console Kernel** — Artisan-like CLI with scheduled tasks

## SQLAlchemy at the core

Alata's Eloquent-style layer is deliberately built **on top of SQLAlchemy
2.0** — SQLAlchemy Core handles all SQL compilation, quoting, dialects, and
pooling; the Alata layer supplies the Laravel-flavored API. Two consequences:

- **The escape hatch is first-class, not a workaround.** Every `Model` is a
  real SQLAlchemy declarative model and `alata.db.get_session()` /
  `get_async_session()` return real sessions — for anything the query
  builder doesn't cover, drop to plain SQLAlchemy 2.0
  (`session.execute(select(User).where(...))`). Caveat: global scopes and
  soft-delete filters apply only through the Alata query builder, not to raw
  SQLAlchemy queries.
- **SQLAlchemy remains available directly.** Use the fluent API for common
  queries, including JSON predicates and full-text search, and SQLAlchemy
  expressions for specialized database operations.

**PostgreSQL, MySQL, and SQLite share the database API.** Queries, models,
and migrations use SQLAlchemy and database-specific schema grammars. PostgreSQL
is the scaffold's default connection. MySQL and SQLite drivers are available
through `alata[mysql]` and `alata[sqlite]`.

Migration commands are serialized on all three databases. PostgreSQL and SQLite
apply each migration transactionally; MySQL DDL implicitly commits, so failure
recovery uses the migration's `down()` method. SQLite rebuilds tables automatically
for column and constraint changes.

## Architecture

```
app/
├── http/controllers/    # Request handlers
├── models/              # Eloquent-style ORM models
├── services/            # Business logic
├── tasks/               # Background queue jobs
├── providers/           # Application service providers
├── events/              # Event payload classes
├── exceptions/          # Exception handler
└── console/             # CLI commands & scheduler
config/                  # Declarative configuration (plain dicts)
routes/                  # API route definitions
bootstrap/               # App factory & provider registration
database/migrations/     # Schema migrations
```

Significant design decisions are recorded in
[docs/adr/](docs/adr/README.md).

## License

MIT
