Metadata-Version: 2.4
Name: py-auth-fastapi
Version: 0.0.1
Summary: FastAPI integration for py-auth-core.
Author-email: Olatunji Jamaldeen Omotoyosi <jamaldeen.o@yahoo.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jamaldeen09/py-auth
Project-URL: Repository, https://github.com/jamaldeen09/py-auth
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi[standard]>=0.100.0
Requires-Dist: py-auth-core>=0.0.1
Dynamic: license-file

# py-auth-fastapi

**FastAPI integration for [py-auth-core](https://pypi.org/project/py-auth-core/).**

Removes the boilerplate of wiring `py-auth-core` authentication into a FastAPI application down to a single line.

[![PyPI version](https://img.shields.io/pypi/v/py-auth-fastapi.svg)](https://pypi.org/project/py-auth-fastapi/)
[![Python versions](https://img.shields.io/pypi/pyversions/py-auth-fastapi.svg)](https://pypi.org/project/py-auth-fastapi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Features

- ✅ **One-liner setup** — Mounts as a standard FastAPI `APIRouter` with `app.include_router()`
- ✅ **Automatic cookie handling** — Sets and clears session and CSRF cookies automatically
- ✅ **Dependency injection** — Includes `get_current_session()` dependency factory for protecting endpoints
- ✅ **Built-in error handling** — Converts `py-auth-core` errors into standard FastAPI `HTTPException` responses

---

## Installation

```bash
pip install py-auth-fastapi
```

---

## Quick Start

```python
from fastapi import FastAPI, Depends
from py_auth import PyAuth
from py_auth_fastapi import PyAuthFastAPI

# Initialize your PyAuth instance
auth = PyAuth(...)

app = FastAPI()

# Mount auth router (prefix="/auth" and tags=["Authentication"] by default)
auth_router = PyAuthFastAPI(auth)
app.include_router(auth_router)

# Protect routes using the session dependency
@app.get("/protected")
async def protected_route(session=Depends(auth_router.get_current_session())):
    return {"message": f"Hello user {session['user_id']}"}
```

### Endpoints Registered

- `POST /auth/signin` — Authenticates credentials and sets session & CSRF cookies
- `POST /auth/signout` — Revokes session and deletes cookies
- `GET  /auth/session` — Fetches current session and rotates CSRF token

---

## License

[MIT](LICENSE)
