drfast-api 0.1.0__py3-none-any.whl

drfast/__init__.py

@@ -0,0 +1,44 @@
+"""DRF-inspired primitives for async FastAPI applications."""
+
+from drfast.filters import FilterSet
+from drfast.middleware import BaseMiddleware
+from drfast.models import Model, SoftDeleteModel, TimestampedModel
+from drfast.pagination import LimitOffsetPagination
+from drfast.permissions import AllowAny, BasePermission, IsAdminUser, IsAuthenticated
+from drfast.routers import DefaultRouter
+from drfast.serializers import (
+	BooleanField,
+	CharField,
+	EmailField,
+	IntegerField,
+	ModelSerializer,
+	Serializer,
+	UUIDField,
+)
+from drfast.settings import DRFastSettings
+from drfast.views import APIView, ModelViewSet
+
+__all__ = [
+	"APIView",
+	"AllowAny",
+	"BaseMiddleware",
+	"BasePermission",
+	"BooleanField",
+	"CharField",
+	"DRFastSettings",
+	"DefaultRouter",
+	"EmailField",
+	"FilterSet",
+	"IntegerField",
+	"IsAdminUser",
+	"IsAuthenticated",
+	"LimitOffsetPagination",
+	"Model",
+	"ModelSerializer",
+	"ModelViewSet",
+	"Serializer",
+	"SoftDeleteModel",
+	"TimestampedModel",
+	"UUIDField",
+]
+

drfast/auth.py

@@ -0,0 +1,126 @@
+"""Current FastAPI Users integration backed by Tortoise ORM.
+
+FastAPI Users no longer ships a Tortoise adapter. This module maintains the
+small persistence bridge while leaving its authentication and security flows
+to FastAPI Users.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable
+from typing import Any, Generic, Protocol, Self, TypeVar
+from uuid import UUID
+
+from fastapi import Depends, Request
+from fastapi_users import BaseUserManager, FastAPIUsers
+from fastapi_users.authentication import AuthenticationBackend, BearerTransport, JWTStrategy
+from fastapi_users.db import BaseUserDatabase
+from fastapi_users.manager import UUIDIDMixin
+from fastapi_users.models import UserProtocol
+from tortoise import fields
+
+from drfast.models import Model, TimestampedModel
+
+
+class TortoiseUserProtocol(UserProtocol[UUID], Protocol):
+	"""Structural contract required by the Tortoise FastAPI Users adapter."""
+
+	@classmethod
+	async def get_or_none(cls, **kwargs: Any) -> Self | None: ...
+
+	@classmethod
+	async def create(cls, **kwargs: Any) -> Self: ...
+
+	async def save(self, *, update_fields: list[str]) -> None: ...
+
+	async def delete(self) -> None: ...
+
+
+UserType = TypeVar("UserType", bound=TortoiseUserProtocol)
+AuthUserType = TypeVar("AuthUserType", bound=UserProtocol[UUID])
+
+
+class FastAPIUserModel(Model, TimestampedModel):
+	"""Ready-to-use Tortoise user table base with FastAPI Users fields."""
+
+	email = fields.CharField(max_length=320, unique=True, index=True)
+	hashed_password = fields.CharField(max_length=1024)
+	is_active = fields.BooleanField(default=True)
+	is_superuser = fields.BooleanField(default=False)
+	is_verified = fields.BooleanField(default=False)
+
+	class Meta:
+		abstract = True
+
+
+class TortoiseUserDatabase(BaseUserDatabase[UserType, UUID], Generic[UserType]):
+	"""FastAPI Users persistence adapter for a Tortoise UUID user model."""
+
+	def __init__(self, user_model: type[UserType]) -> None:
+		self.user_model = user_model
+
+	async def get(self, id: UUID) -> UserType | None:
+		return await self.user_model.get_or_none(id=id)
+
+	async def get_by_email(self, email: str) -> UserType | None:
+		return await self.user_model.get_or_none(email=email)
+
+	async def create(self, create_dict: dict[str, Any]) -> UserType:
+		return await self.user_model.create(**create_dict)
+
+	async def update(self, user: UserType, update_dict: dict[str, Any]) -> UserType:
+		for key, value in update_dict.items():
+			setattr(user, key, value)
+		await user.save(update_fields=list(update_dict))
+		return user
+
+	async def delete(self, user: UserType) -> None:
+		await user.delete()
+
+
+class DRFastUserManager(UUIDIDMixin, BaseUserManager[UserType, UUID], Generic[UserType]):
+	"""Base manager applications subclass to add password and event policies."""
+
+	reset_password_token_secret: str
+	verification_token_secret: str
+
+
+def jwt_authentication(
+	secret: str,
+	lifetime_seconds: int = 3600,
+) -> AuthenticationBackend[AuthUserType, UUID]:
+	"""Build FastAPI Users' bearer/JWT backend for generated projects."""
+	bearer_transport = BearerTransport(tokenUrl="auth/jwt/login")
+
+	def get_strategy() -> JWTStrategy[AuthUserType, UUID]:
+		return JWTStrategy(secret=secret, lifetime_seconds=lifetime_seconds)
+
+	return AuthenticationBackend[AuthUserType, UUID](
+		name="jwt", transport=bearer_transport, get_strategy=get_strategy
+	)
+
+
+def build_fastapi_users(
+	get_user_manager: Callable[..., AsyncGenerator[DRFastUserManager[UserType], None]],
+	backend: AuthenticationBackend[UserType, UUID],
+) -> FastAPIUsers[UserType, UUID]:
+	"""Create a FastAPI Users facade from application dependencies."""
+	return FastAPIUsers(get_user_manager, [backend])
+
+
+def current_user_middleware(
+	current_active_user: Callable[..., Any],
+) -> Callable[[Request, Any], Any]:
+	"""Adapt a FastAPI Users dependency for DRFast permission classes.
+
+	Use this with a normal FastAPI dependency on protected routes when request
+	state is desired by custom `BasePermission` implementations.
+	"""
+	async def dependency(  # noqa: B008 - FastAPI resolves dependencies from the signature.
+		request: Request, user: Any = Depends(current_active_user)  # noqa: B008
+	) -> Any:
+		request.state.user = user
+		return user
+
+	return dependency
+

drfast/cli.py

@@ -0,0 +1,358 @@
+"""Django-inspired management CLI for DRFast projects."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import runpy
+import sys
+from getpass import getpass
+from pathlib import Path
+from textwrap import dedent
+
+
+def _write(path: Path, content: str) -> None:
+	path.parent.mkdir(parents=True, exist_ok=True)
+	path.write_text(dedent(content).lstrip(), encoding="utf-8")
+
+
+def startproject(name: str, destination: str) -> None:
+	"""Generate a runnable application with local SQLite configuration."""
+	if not name.isidentifier():
+		raise SystemExit("Project name must be a valid Python identifier.")
+	root = Path(destination).resolve() / name
+	if root.exists() and any(root.iterdir()):
+		raise SystemExit(f"Refusing to overwrite non-empty directory: {root}")
+	package = name
+	_write(
+		root / "pyproject.toml",
+		f'''
+		[project]
+		name = "{name}"
+		version = "0.1.0"
+		requires-python = ">=3.11"
+		dependencies = ["drfast-api[postgres]"]
+
+		[tool.tortoise]
+		tortoise_orm = "{package}.settings.TORTOISE_ORM"
+		''',
+	)
+	_write(root / ".env.example", """DEBUG=true
+DATABASE_URL=sqlite://db.sqlite3
+SECRET_KEY=replace-before-production
+""")
+	_write(root / package / "__init__.py", "")
+	_write(
+		root / package / "settings.py",
+		f'''
+		from drfast import DRFastSettings
+
+
+		class Settings(DRFastSettings):
+			app_name: str = "{name}"
+			debug: bool = True
+			installed_apps: list[str] = [
+				"{package}.users.models",
+				"{package}.apps.todo.models",
+			]
+
+
+		settings = Settings()
+		TORTOISE_ORM = settings.tortoise_config()
+		''',
+	)
+	_write(root / package / "users" / "__init__.py", "")
+	_write(
+		root / package / "users" / "models.py",
+		"""
+		from drfast.auth import FastAPIUserModel
+
+
+		class User(FastAPIUserModel):
+			pass
+		""",
+	)
+	_write(
+		root / package / "users" / "auth.py",
+		f'''
+		from collections.abc import AsyncGenerator
+		from uuid import UUID
+
+		from fastapi import Depends
+		from fastapi_users import schemas
+		from drfast.auth import (
+			DRFastUserManager,
+			TortoiseUserDatabase,
+			build_fastapi_users,
+			jwt_authentication,
+		)
+
+		from {package}.settings import settings
+		from {package}.users.models import User
+
+
+		class UserRead(schemas.BaseUser[UUID]):
+			pass
+
+
+		class UserCreate(schemas.BaseUserCreate):
+			pass
+
+
+		class UserUpdate(schemas.BaseUserUpdate):
+			pass
+
+
+		async def get_user_db() -> AsyncGenerator[TortoiseUserDatabase[User], None]:
+			yield TortoiseUserDatabase(User)
+
+
+		class UserManager(DRFastUserManager[User]):
+			reset_password_token_secret = settings.secret_key.get_secret_value()
+			verification_token_secret = settings.secret_key.get_secret_value()
+
+
+		async def get_user_manager(
+			user_db: TortoiseUserDatabase[User] = Depends(get_user_db),
+		) -> AsyncGenerator[UserManager, None]:
+			yield UserManager(user_db)
+
+
+		auth_backend = jwt_authentication(
+			settings.secret_key.get_secret_value(), settings.jwt_lifetime_seconds
+		)
+		fastapi_users = build_fastapi_users(get_user_manager, auth_backend)
+		''',
+	)
+	_write(root / package / "apps" / "__init__.py", "")
+	_write(root / package / "apps" / "todo" / "__init__.py", "")
+	_write(
+		root / package / "apps" / "todo" / "models.py",
+		"""
+		from tortoise import fields
+		from drfast import Model, TimestampedModel
+
+
+		class Todo(Model, TimestampedModel):
+			title = fields.CharField(max_length=200)
+			completed = fields.BooleanField(default=False)
+		""",
+	)
+	_write(
+		root / package / "apps" / "todo" / "serializers.py",
+		f'''
+		from drfast import BooleanField, CharField, ModelSerializer, UUIDField
+		from {package}.apps.todo.models import Todo
+
+
+		class TodoSerializer(ModelSerializer[Todo]):
+			model = Todo
+			id = UUIDField(read_only=True)
+			title = CharField()
+			completed = BooleanField(required=False, default=False)
+		''',
+	)
+	_write(
+		root / package / "apps" / "todo" / "views.py",
+		f'''
+		from drfast import FilterSet, ModelViewSet
+		from {package}.apps.todo.models import Todo
+		from {package}.apps.todo.serializers import TodoSerializer
+
+
+		class TodoFilters(FilterSet):
+			fields = {{"completed": ("exact",)}}
+
+
+		class TodoViewSet(ModelViewSet):
+			model = Todo
+			serializer_class = TodoSerializer
+			filterset_class = TodoFilters
+			ordering_fields = ("created_at", "title")
+		''',
+	)
+	_write(
+		root / package / "urls.py",
+		f'''
+		from drfast import DefaultRouter
+		from {package}.apps.todo.views import TodoViewSet
+
+		router = DefaultRouter()
+		router.register("/todos", TodoViewSet, basename="todos")
+		''',
+	)
+	_write(
+		root / package / "main.py",
+		f'''
+		from drfast.orm import create_app
+		from {package}.settings import settings
+		from {package}.urls import router
+		from {package}.users.auth import (
+			UserCreate,
+			UserRead,
+			UserUpdate,
+			auth_backend,
+			fastapi_users,
+		)
+
+		app = create_app(settings)
+		router.include_in(app, prefix="/api")
+		app.include_router(
+			fastapi_users.get_auth_router(auth_backend), prefix="/auth/jwt", tags=["auth"]
+		)
+		app.include_router(
+			fastapi_users.get_register_router(UserRead, UserCreate), prefix="/auth", tags=["auth"]
+		)
+		app.include_router(
+			fastapi_users.get_users_router(UserRead, UserUpdate), prefix="/users", tags=["users"]
+		)
+		''',
+	)
+	_write(
+		root / "README.md",
+		f"# {name}\n\nRun `drfast init`, `drfast migrate`, then `drfast runserver`.\n",
+	)
+	print(f"Created {root}")
+
+
+def startapp(name: str, project: str = ".") -> None:
+	"""Generate a conventional models/serializers/views app package."""
+	if not name.isidentifier():
+		raise SystemExit("App name must be a valid Python identifier.")
+	project_root = Path(project).resolve()
+	root = project_root / "apps" / name
+	if root.exists():
+		raise SystemExit(f"App already exists: {root}")
+	for filename in ("__init__.py", "models.py", "serializers.py", "views.py", "tests.py"):
+		_write(root / filename, "")
+	package = project_root.name.replace("-", "_")
+	settings_path = project_root / package / "settings.py"
+	if settings_path.exists():
+		settings = settings_path.read_text(encoding="utf-8")
+		marker = "\t]\n\n\nsettings = Settings()"
+		entry = f'\t\t"{package}.apps.{name}.models",\n'
+		if marker not in settings:
+			raise SystemExit(f"Could not update installed_apps in {settings_path}")
+		settings_path.write_text(settings.replace(marker, f"{entry}{marker}", 1), encoding="utf-8")
+	print(f"Created {root}")
+
+
+def _run_tortoise(arguments: list[str]) -> int:
+	"""Run Tortoise's supported module CLI without relying on ``PATH``."""
+	original_argv = sys.argv
+	try:
+		sys.argv = ["tortoise", *arguments]
+		runpy.run_module("tortoise", run_name="__main__")
+	except SystemExit as exc:
+		return exc.code if isinstance(exc.code, int) else 1
+	finally:
+		sys.argv = original_argv
+	return 0
+
+
+async def _create_superuser(project: str, email: str) -> None:
+	settings_module = importlib.import_module(f"{project}.settings")
+	user_module = importlib.import_module(f"{project}.users.models")
+	from fastapi_users.password import PasswordHelper
+	from tortoise import Tortoise
+
+	password = getpass("Password: ")
+	confirm = getpass("Password (again): ")
+	if password != confirm:
+		raise SystemExit("Passwords do not match.")
+	await Tortoise.init(config=settings_module.TORTOISE_ORM)
+	try:
+		await user_module.User.create(
+			email=email,
+			hashed_password=PasswordHelper().hash(password),
+			is_active=True,
+			is_superuser=True,
+			is_verified=True,
+		)
+	finally:
+		await Tortoise.close_connections()
+
+
+def _project_name() -> str:
+	return Path.cwd().name.replace("-", "_")
+
+
+def _validate_project_name(project: str) -> str:
+	if not project or not all(part.isidentifier() for part in project.split(".")):
+		raise SystemExit("Project must be a dotted Python module name.")
+	return project
+
+
+def main(argv: list[str] | None = None) -> None:
+	parser = argparse.ArgumentParser(prog="drfast")
+	subparsers = parser.add_subparsers(dest="command", required=True)
+	project_parser = subparsers.add_parser("startproject")
+	project_parser.add_argument("name")
+	project_parser.add_argument("destination", nargs="?", default=".")
+	app_parser = subparsers.add_parser("startapp")
+	app_parser.add_argument("name")
+	app_parser.add_argument("--project", default=".")
+	run_parser = subparsers.add_parser("runserver")
+	run_parser.add_argument("--host", default="127.0.0.1")
+	run_parser.add_argument("--port", type=int, default=8000)
+	run_parser.add_argument("--project", default=None)
+	subparsers.add_parser("check")
+	subparsers.add_parser("routes")
+	user_parser = subparsers.add_parser("createsuperuser")
+	user_parser.add_argument("--email", required=True)
+	user_parser.add_argument("--project", default=None)
+	for command in (
+		"init",
+		"makemigrations",
+		"migrate",
+		"downgrade",
+		"history",
+		"heads",
+		"sqlmigrate",
+	):
+		migration_parser = subparsers.add_parser(command)
+		migration_parser.add_argument("args", nargs=argparse.REMAINDER)
+
+	args = parser.parse_args(argv)
+	if args.command == "startproject":
+		startproject(args.name, args.destination)
+		return
+	if args.command == "startapp":
+		startapp(args.name, args.project)
+		return
+	if args.command == "runserver":
+		project = _validate_project_name(args.project or _project_name())
+		import uvicorn
+
+		uvicorn.run(f"{project}.main:app", host=args.host, port=args.port, reload=True)
+		return
+	if args.command in {
+		"init",
+		"makemigrations",
+		"migrate",
+		"downgrade",
+		"history",
+		"heads",
+		"sqlmigrate",
+	}:
+		raise SystemExit(_run_tortoise([args.command, *args.args]))
+	if args.command == "createsuperuser":
+		project = _validate_project_name(args.project or _project_name())
+		asyncio.run(_create_superuser(project, args.email))
+		return
+	project = _validate_project_name(_project_name())
+	if args.command == "check":
+		importlib.import_module(f"{project}.main")
+		print("System check identified no issues.")
+		return
+	if args.command == "routes":
+		app = importlib.import_module(f"{project}.main").app
+		for route in app.routes:
+			methods = ",".join(sorted(getattr(route, "methods", [])))
+			print(f"{getattr(route, 'path', ''):30} {methods}")
+
+
+if __name__ == "__main__":
+	main()
+

drfast/filters.py

@@ -0,0 +1,36 @@
+"""Explicit filtering configuration for list endpoints."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from fastapi import HTTPException, Request, status
+
+
+class FilterSet:
+	"""Allowlist exact filters and explicitly declared Tortoise lookups."""
+
+	fields: ClassVar[dict[str, tuple[str, ...]] | tuple[str, ...]] = ()
+
+	@classmethod
+	def allowed_lookups(cls, name: str) -> tuple[str, ...]:
+		if isinstance(cls.fields, dict):
+			return cls.fields.get(name, ())
+		return ("exact",) if name in cls.fields else ()
+
+	@classmethod
+	def filters_from_request(cls, request: Request) -> dict[str, str]:
+		filters: dict[str, str] = {}
+		for name, value in request.query_params.multi_items():
+			if name in {"limit", "offset", "ordering"}:
+				continue
+			field, separator, lookup = name.partition("__")
+			lookup = lookup if separator else "exact"
+			if lookup not in cls.allowed_lookups(field):
+				raise HTTPException(
+					status_code=status.HTTP_400_BAD_REQUEST,
+					detail=f"Filtering by '{name}' is not allowed.",
+				)
+			filters[name] = value
+		return filters
+

drfast/middleware.py

@@ -0,0 +1,48 @@
+"""Class-based application middleware with deterministic hook ordering."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Request, Response
+
+
+class BaseMiddleware:
+	"""Implement any async hook; returning a response from request short-circuits."""
+
+	async def process_request(self, request: Request) -> Response | None:
+		return None
+
+	async def process_response(self, request: Request, response: Response) -> Response:
+		return response
+
+	async def process_exception(self, request: Request, exc: Exception) -> Response | None:
+		return None
+
+
+def install_middleware(app: FastAPI, middleware_classes: list[type[BaseMiddleware]]) -> None:
+	"""Install one ASGI-compatible pipeline around FastAPI routes.
+
+	Request hooks run in declaration order; response and exception hooks run in
+	reverse order, matching stack unwinding semantics.
+	"""
+	instances = [middleware() for middleware in middleware_classes]
+
+	@app.middleware("http")
+	async def drfast_middleware(request: Request, call_next: Any) -> Response:
+		try:
+			for middleware in instances:
+				response = await middleware.process_request(request)
+				if response is not None:
+					return response
+			response = await call_next(request)
+		except Exception as exc:
+			for middleware in reversed(instances):
+				response = await middleware.process_exception(request, exc)
+				if response is not None:
+					return response
+			raise
+		for middleware in reversed(instances):
+			response = await middleware.process_response(request, response)
+		return response
+

drfast/models.py

@@ -0,0 +1,45 @@
+"""Tortoise model bases with explicit, composable conventions."""
+
+from __future__ import annotations
+
+from tortoise import fields
+from tortoise.models import Model as TortoiseModel
+
+
+class Model(TortoiseModel):
+	"""Abstract model with a UUID primary key."""
+
+	id = fields.UUIDField(primary_key=True)
+
+	class Meta:
+		abstract = True
+
+
+class TimestampedModel(TortoiseModel):
+	"""Opt-in UTC creation and modification timestamps."""
+
+	created_at = fields.DatetimeField(auto_now_add=True)
+	updated_at = fields.DatetimeField(auto_now=True)
+
+	class Meta:
+		abstract = True
+
+
+class SoftDeleteModel(TortoiseModel):
+	"""Opt-in soft deletion convention.
+
+	Applications choose whether ordinary queries exclude deleted rows; no manager
+	behavior is hidden by this mixin.
+	"""
+
+	deleted_at = fields.DatetimeField(null=True)
+
+	class Meta:
+		abstract = True
+
+	async def soft_delete(self) -> None:
+		from datetime import UTC, datetime
+
+		self.deleted_at = datetime.now(UTC)
+		await self.save(update_fields=["deleted_at"])
+

drfast/orm.py

@@ -0,0 +1,35 @@
+"""FastAPI lifespan wiring for Tortoise ORM."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI
+from tortoise.contrib.fastapi import RegisterTortoise
+
+from drfast.settings import DRFastSettings
+
+
+def configure_orm(app: FastAPI, settings: DRFastSettings) -> None:
+	"""Attach a Tortoise lifespan to an application.
+
+	Schema generation is deliberately never enabled here; use migrations instead.
+	"""
+	settings.validate_production()
+
+	@asynccontextmanager
+	async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+		async with RegisterTortoise(config=settings.tortoise_config()):
+			yield
+
+	app.router.lifespan_context = lifespan
+
+
+def create_app(settings: DRFastSettings, **kwargs: Any) -> FastAPI:
+	"""Create a configured FastAPI application without hiding FastAPI itself."""
+	app = FastAPI(title=settings.app_name, **kwargs)
+	configure_orm(app, settings)
+	return app
+