Metadata-Version: 2.4
Name: authloom
Version: 0.1.0b1
Summary: Authentication building blocks for FastAPI applications
Keywords: fastapi,authentication
Author: Sreekar Nutulapati
Author-email: Sreekar Nutulapati <sreekarnv1@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: cuid2>=2.0.1
Requires-Dist: email-normalize>=3.1.0
Requires-Dist: fastapi>=0.140.0
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic[email]>=2.13.4
Requires-Dist: sqlalchemy>=2.0.51
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/sreekarnv/authloom
Project-URL: Repository, https://github.com/sreekarnv/authloom
Project-URL: Issues, https://github.com/sreekarnv/authloom/issues
Project-URL: Changelog, https://github.com/sreekarnv/authloom/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# AuthLoom

AuthLoom is a Python 3.12 or newer authentication library for FastAPI applications.

It provides email/password signup and signin, cookie-backed database sessions,
password reset, password change, email verification, and current-user
dependencies. AuthLoom is beta pre-release software; the beta series is for
validating the public API, packaging, docs, and database integration before the
first stable release.

## Installation

Using `uv`:

```bash
uv add authloom aiosqlite
```

Using `pip`:

```bash
pip install authloom aiosqlite
```

`aiosqlite` is only for the SQLite quickstart below. Install the async database
driver your application uses, such as `asyncpg` for PostgreSQL.

## Quickstart

Minimal application wiring. This is not a complete production setup.
Applications provide the async SQLAlchemy session factory and own database setup.

```python
from typing import Annotated

from fastapi import Depends, FastAPI
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine

from authloom import AuthLoom, AuthLoomConfig, create_auth_router
from authloom.db import User

engine = create_async_engine("sqlite+aiosqlite:///./app.db")
AsyncSessionLocal = async_sessionmaker(
    engine,
    class_=AsyncSession,
    expire_on_commit=False,
)

auth = AuthLoom(config=AuthLoomConfig(session_factory=AsyncSessionLocal))

app = FastAPI()
app.include_router(create_auth_router(auth))


@app.get("/protected")
async def protected_route(
    user: Annotated[User, Depends(auth.require_current_user)],
):
    return {"id": user.id, "email": user.email}
```

The router defaults to `/auth`. Use `create_auth_router(auth, prefix="/accounts")`
to choose a different route prefix.

Before using this in an application:

- Add AuthLoom metadata to your application-owned
  [Alembic migrations](https://sreekarnv.github.io/authloom/database-and-migrations/).
- Configure consumer-owned
  [CSRF protection](https://sreekarnv.github.io/authloom/consumer-integration/#mandatory-csrf-for-browser-or-deployment-use)
  before browser or deployment use.
- Use HTTPS and
  [`secure=True` cookies](https://sreekarnv.github.io/authloom/configuration/#production-cookie-settings)
  in production.

## Documentation

- Full documentation: <https://sreekarnv.github.io/authloom/>
- Consumer integration: <https://sreekarnv.github.io/authloom/consumer-integration/>
- Configuration: <https://sreekarnv.github.io/authloom/configuration/>
- Account security flows: <https://sreekarnv.github.io/authloom/account-security-flows/>
- Database and migrations: <https://sreekarnv.github.io/authloom/database-and-migrations/>
- Security model: <https://sreekarnv.github.io/authloom/security-model/>
- Changelog: <https://github.com/sreekarnv/authloom/blob/main/CHANGELOG.md>

## Example Application

See the FastAPI credentials-auth reference implementation at
<https://github.com/sreekarnv/authloom/tree/main/examples/credentials_auth>. It
runs with SQLite by default or PostgreSQL via `DATABASE_URL` and Docker Compose.

## Development

```bash
uv sync --locked --group dev --group test --group docs
uv run ruff check .
uv run pytest tests/unit tests/integration
uv run --locked --group docs mkdocs build --strict
uv build --no-sources
```

## License

AuthLoom is licensed under the Apache License 2.0. See
<https://github.com/sreekarnv/authloom/blob/main/LICENSE>.
