drfast-api 0.1.0__py3-none-any.whl

drfast/pagination.py

@@ -0,0 +1,53 @@
+"""Native JSON limit/offset pagination."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException, Request, status
+
+
+class LimitOffsetPagination:
+	default_limit = 50
+	max_limit = 100
+
+	def parameters(self, request: Request) -> tuple[int, int]:
+		try:
+			limit = int(request.query_params.get("limit", self.default_limit))
+			offset = int(request.query_params.get("offset", 0))
+		except ValueError as exc:
+			raise HTTPException(
+				status_code=status.HTTP_400_BAD_REQUEST,
+				detail="Invalid pagination.",
+			) from exc
+		if limit < 1 or limit > self.max_limit or offset < 0:
+			raise HTTPException(
+				status_code=status.HTTP_400_BAD_REQUEST,
+				detail="Invalid pagination.",
+			)
+		return limit, offset
+
+	def response(
+		self,
+		request: Request,
+		*,
+		count: int,
+		offset: int,
+		limit: int,
+		results: list[Any],
+	) -> dict[str, Any]:
+		def link(next_offset: int) -> str | None:
+			if next_offset < 0 or next_offset >= count:
+				return None
+			params = dict(request.query_params)
+			params.update({"limit": str(limit), "offset": str(next_offset)})
+			query = "&".join(f"{key}={value}" for key, value in params.items())
+			return f"{request.url.path}?{query}"
+
+		return {
+			"count": count,
+			"next": link(offset + limit),
+			"previous": link(max(offset - limit, -1)),
+			"results": results,
+		}
+

drfast/permissions.py

@@ -0,0 +1,54 @@
+"""Async DRF-style permission primitives."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException, Request, status
+
+
+class BasePermission:
+	"""Base for request-level and object-level access rules."""
+
+	message = "You do not have permission to perform this action."
+
+	async def has_permission(self, request: Request, view: Any) -> bool:
+		return True
+
+	async def has_object_permission(self, request: Request, view: Any, obj: Any) -> bool:
+		return await self.has_permission(request, view)
+
+
+class AllowAny(BasePermission):
+	pass
+
+
+class IsAuthenticated(BasePermission):
+	message = "Authentication credentials were not provided."
+
+	async def has_permission(self, request: Request, view: Any) -> bool:
+		user = getattr(request.state, "user", None)
+		return user is not None and bool(getattr(user, "is_active", True))
+
+
+class IsAdminUser(IsAuthenticated):
+	message = "Administrator access is required."
+
+	async def has_permission(self, request: Request, view: Any) -> bool:
+		return await super().has_permission(request, view) and bool(
+			getattr(request.state.user, "is_superuser", False)
+		)
+
+
+async def enforce_permissions(request: Request, view: Any, obj: Any | None = None) -> None:
+	"""Raise a uniform HTTP error for failed configured permissions."""
+	for permission_type in getattr(view, "permission_classes", (AllowAny,)):
+		permission = permission_type()
+		allowed = (
+			await permission.has_object_permission(request, view, obj)
+			if obj is not None
+			else await permission.has_permission(request, view)
+		)
+		if not allowed:
+			raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=permission.message)
+

drfast/routers.py

@@ -0,0 +1,42 @@
+"""Router registry for model viewsets."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+
+from drfast.views import ModelViewSet
+
+
+class DefaultRouter:
+	"""Register viewsets then mount their FastAPI routes explicitly."""
+
+	def __init__(self) -> None:
+		self._registry: list[tuple[str, type[ModelViewSet], str | None]] = []
+
+	def register(
+		self,
+		prefix: str,
+		viewset: type[ModelViewSet],
+		*,
+		basename: str | None = None,
+	) -> None:
+		self._registry.append((prefix.rstrip("/"), viewset, basename))
+
+	def urls(self) -> list[APIRouter]:
+		return [
+			viewset().as_router(prefix=prefix, tags=[basename or prefix])
+			for prefix, viewset, basename in self._registry
+		]
+
+	def include_in(self, app: FastAPI, *, prefix: str = "") -> None:
+		for router in self.urls():
+			app.include_router(router, prefix=prefix)
+
+	def routes(self) -> list[dict[str, Any]]:
+		return [
+			{"prefix": prefix, "viewset": viewset.__name__, "basename": basename}
+			for prefix, viewset, basename in self._registry
+		]
+

drfast/serializers.py

@@ -0,0 +1,214 @@
+"""DRF-shaped serializers backed by Pydantic v2 validation."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, ClassVar, Generic, TypeVar, cast
+
+from pydantic import (
+	BaseModel,
+	ConfigDict,
+	EmailStr,
+	ValidationError,
+	create_model,
+)
+from pydantic import (
+	Field as PydanticField,
+)
+from tortoise.models import Model as TortoiseModel
+
+ModelType = TypeVar("ModelType", bound=TortoiseModel)
+
+
+class SerializerValidationError(ValueError):
+	"""Validation failure with a JSON-ready error detail."""
+
+	def __init__(self, detail: Any) -> None:
+		super().__init__("Serializer validation failed")
+		self.detail = detail
+
+
+class Field:
+	"""A declarative serializer field.
+
+	The field's concrete Python type is passed to Pydantic, so FastAPI retains
+	native request validation and OpenAPI schemas.
+	"""
+
+	python_type: Any = Any
+
+	def __init__(
+		self,
+		*,
+		required: bool = True,
+		default: Any = ...,
+		read_only: bool = False,
+		write_only: bool = False,
+		alias: str | None = None,
+	) -> None:
+		self.required = required
+		self.default = default
+		self.read_only = read_only
+		self.write_only = write_only
+		self.alias = alias
+
+	def pydantic_field(self, *, for_input: bool) -> tuple[Any, Any]:
+		if (for_input and self.read_only) or (not for_input and self.write_only):
+			return Any, PydanticField(exclude=True)
+		default = self.default
+		if not self.required and default is ...:
+			default = None
+		return self.python_type, PydanticField(default=default, alias=self.alias)
+
+
+class CharField(Field):
+	python_type = str
+
+
+class EmailField(Field):
+	python_type = EmailStr
+
+
+class IntegerField(Field):
+	python_type = int
+
+
+class BooleanField(Field):
+	python_type = bool
+
+
+class UUIDField(Field):
+	from uuid import UUID
+
+	python_type = UUID
+
+
+class SerializerMeta(type):
+	def __new__(
+		mcls: type[SerializerMeta],
+		name: str,
+		bases: tuple[type[Any], ...],
+		namespace: dict[str, Any],
+	) -> type[Serializer[Any]]:
+		declared: dict[str, Field] = {}
+		for base in bases:
+			declared.update(getattr(base, "_declared_fields", {}))
+		for key, value in list(namespace.items()):
+			if isinstance(value, Field):
+				declared[key] = value
+				namespace.pop(key)
+		namespace["_declared_fields"] = declared
+		return cast("type[Serializer[Any]]", super().__new__(mcls, name, bases, namespace))
+
+
+class Serializer(Generic[ModelType], metaclass=SerializerMeta):
+	"""Serializer with explicit fields and async validation hooks."""
+
+	_declared_fields: ClassVar[dict[str, Field]]
+
+	def __init__(self, instance: ModelType | None = None, *, partial: bool = False) -> None:
+		self.instance = instance
+		self.partial = partial
+		self.validated_data: dict[str, Any] = {}
+
+	@classmethod
+	def _schema(cls, *, for_input: bool, partial: bool = False) -> type[BaseModel]:
+		fields: dict[str, tuple[Any, Any]] = {}
+		for name, field in cls._declared_fields.items():
+			if (for_input and field.read_only) or (not for_input and field.write_only):
+				continue
+			annotation, default = field.pydantic_field(for_input=for_input)
+			if partial and for_input and default is ...:
+				default = None
+			fields[name] = (annotation, default)
+		model = create_model(
+			f"{cls.__name__}{'Input' if for_input else 'Output'}",
+			__config__=ConfigDict(from_attributes=True, populate_by_name=True),
+			**cast(Any, fields),
+		)
+		return cast(type[BaseModel], model)
+
+	@classmethod
+	def input_schema(cls) -> type[BaseModel]:
+		return cls._schema(for_input=True)
+
+	@classmethod
+	def output_schema(cls) -> type[BaseModel]:
+		return cls._schema(for_input=False)
+
+	async def is_valid(self, data: Mapping[str, Any]) -> bool:
+		try:
+			parsed = self._schema(for_input=True, partial=self.partial).model_validate(data)
+		except ValidationError as exc:
+			raise SerializerValidationError(exc.errors(include_url=False)) from exc
+		values = parsed.model_dump(exclude_unset=self.partial, by_alias=False)
+		for name, value in list(values.items()):
+			validator = getattr(self, f"validate_{name}", None)
+			if validator is not None:
+				result = validator(value)
+				values[name] = await result if hasattr(result, "__await__") else result
+		validated = self.validate(values)
+		self.validated_data = await validated if hasattr(validated, "__await__") else validated
+		return True
+
+	def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
+		return attrs
+
+	async def create(self, validated_data: dict[str, Any]) -> ModelType:
+		raise NotImplementedError("Serializer.create() must be implemented")
+
+	async def update(self, instance: ModelType, validated_data: dict[str, Any]) -> ModelType:
+		raise NotImplementedError("Serializer.update() must be implemented")
+
+	async def save(self) -> ModelType:
+		if self.instance is None:
+			self.instance = await self.create(self.validated_data)
+		else:
+			self.instance = await self.update(self.instance, self.validated_data)
+		return self.instance
+
+	def representation(self, instance: ModelType | Mapping[str, Any]) -> dict[str, Any]:
+		data = self.output_schema().model_validate(instance).model_dump(mode="json", by_alias=True)
+		return {name: value for name, value in data.items() if value is not None}
+
+
+class ModelSerializer(Serializer[ModelType]):
+	"""Serializer with model-backed create and update behavior."""
+
+	model: ClassVar[type[ModelType]]
+	fields: ClassVar[tuple[str, ...] | str] = "__all__"
+	read_only_fields: ClassVar[tuple[str, ...]] = ()
+
+	@classmethod
+	def _model_fields(cls) -> dict[str, Field]:
+		if cls._declared_fields:
+			return cls._declared_fields
+		result: dict[str, Field] = {}
+		selected = None if cls.fields == "__all__" else set(cls.fields)
+		for name, db_field in cls.model._meta.fields_map.items():
+			if selected is not None and name not in selected:
+				continue
+			is_automatic = name in {"id", "created_at", "updated_at", "deleted_at"}
+			python_type = getattr(db_field, "field_type", Any)
+			result[name] = Field(
+				required=not getattr(db_field, "null", False),
+				read_only=is_automatic or name in cls.read_only_fields,
+			)
+			result[name].python_type = python_type
+		return result
+
+	@classmethod
+	def _schema(cls, *, for_input: bool, partial: bool = False) -> type[BaseModel]:
+		if not cls._declared_fields:
+			cls._declared_fields = cls._model_fields()
+		return super()._schema(for_input=for_input, partial=partial)
+
+	async def create(self, validated_data: dict[str, Any]) -> ModelType:
+		return await self.model.create(**validated_data)
+
+	async def update(self, instance: ModelType, validated_data: dict[str, Any]) -> ModelType:
+		for name, value in validated_data.items():
+			setattr(instance, name, value)
+		await instance.save(update_fields=list(validated_data))
+		return instance
+

drfast/settings.py

@@ -0,0 +1,45 @@
+"""Typed application settings and Tortoise configuration generation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class DRFastSettings(BaseSettings):
+	"""Settings consumed by project wiring, never by views directly."""
+
+	model_config = SettingsConfigDict(env_file=".env", env_prefix="", extra="ignore")
+
+	app_name: str = "DRFast API"
+	debug: bool = False
+	database_url: str = "sqlite://db.sqlite3"
+	installed_apps: list[str] = Field(default_factory=list)
+	secret_key: SecretStr = SecretStr("change-me-in-production")
+	jwt_lifetime_seconds: int = 3600
+	cors_origins: list[str] = Field(default_factory=list)
+
+	def tortoise_config(self) -> dict[str, Any]:
+		"""Return the configuration shared by runtime and migration commands."""
+		apps: dict[str, dict[str, Any]] = {}
+		for module in self.installed_apps:
+			package, _, _ = module.rpartition(".")
+			label = package.rsplit(".", maxsplit=1)[-1]
+			if label in apps:
+				raise ValueError(f"Duplicate Tortoise app label '{label}' in installed_apps")
+			apps[label] = {
+				"models": [module],
+				"default_connection": "default",
+				"migrations": f"{package}.migrations",
+			}
+		return {
+			"connections": {"default": self.database_url},
+			"apps": apps,
+		}
+
+	def validate_production(self) -> None:
+		if not self.debug and self.secret_key.get_secret_value() == "change-me-in-production":
+			raise ValueError("SECRET_KEY must be set when DEBUG is false")
+

drfast/views.py

@@ -0,0 +1,230 @@
+"""Class-based FastAPI views and Tortoise model viewsets."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Sequence
+from typing import Any, ClassVar, cast
+from uuid import UUID
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Request, status
+from tortoise.exceptions import DoesNotExist
+from tortoise.models import Model as TortoiseModel
+
+from drfast.filters import FilterSet
+from drfast.pagination import LimitOffsetPagination
+from drfast.permissions import AllowAny, BasePermission, enforce_permissions
+from drfast.serializers import ModelSerializer, SerializerValidationError
+
+
+class APIView:
+	"""Base class for a FastAPI route group with DRF-style permissions."""
+
+	permission_classes: ClassVar[tuple[type[BasePermission], ...]] = (AllowAny,)
+	authentication_dependencies: ClassVar[tuple[Callable[..., Any], ...]] = ()
+
+	async def check_permissions(self, request: Request, obj: Any | None = None) -> None:
+		await enforce_permissions(request, self, obj)
+
+
+class ModelViewSet(APIView):
+	"""Async CRUD viewset for a Tortoise model."""
+
+	model: ClassVar[type[TortoiseModel]]
+	serializer_class: ClassVar[type[ModelSerializer[Any]]]
+	filterset_class: ClassVar[type[FilterSet] | None] = None
+	pagination_class: ClassVar[type[LimitOffsetPagination] | None] = LimitOffsetPagination
+	ordering_fields: ClassVar[tuple[str, ...]] = ()
+
+	def serializer(
+		self,
+		instance: Any | None = None,
+		*,
+		partial: bool = False,
+	) -> ModelSerializer[Any]:
+		return self.serializer_class(instance, partial=partial)
+
+	async def get_object(self, request: Request, pk: UUID) -> TortoiseModel:
+		try:
+			obj = await self.model.get(id=pk)
+		except DoesNotExist as exc:
+			raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found.") from exc
+		await self.check_permissions(request, obj)
+		return obj
+
+	def _queryset(self, request: Request) -> Any:
+		queryset = self.model.all()
+		if self.filterset_class is not None:
+			queryset = queryset.filter(**self.filterset_class.filters_from_request(request))
+		ordering = request.query_params.get("ordering")
+		if ordering:
+			fields = tuple(field.strip() for field in ordering.split(",") if field.strip())
+			if not fields or any(
+				field.removeprefix("-") not in self.ordering_fields for field in fields
+			):
+				raise HTTPException(
+					status_code=status.HTTP_400_BAD_REQUEST,
+					detail="Invalid ordering.",
+				)
+			queryset = queryset.order_by(*fields)
+		return queryset
+
+	async def list(self, request: Request) -> dict[str, Any] | list[dict[str, Any]]:
+		await self.check_permissions(request)
+		queryset = self._queryset(request)
+		if self.pagination_class is None:
+			instances = await queryset
+			return [self.serializer(instance).representation(instance) for instance in instances]
+		paginator = self.pagination_class()
+		limit, offset = paginator.parameters(request)
+		count = await queryset.count()
+		instances = await queryset.offset(offset).limit(limit)
+		return paginator.response(
+			request,
+			count=count,
+			offset=offset,
+			limit=limit,
+			results=[
+				self.serializer(instance).representation(instance) for instance in instances
+			],
+		)
+
+	async def retrieve(self, request: Request, pk: UUID) -> dict[str, Any]:
+		instance = await self.get_object(request, pk)
+		return self.serializer(instance).representation(instance)
+
+	async def create(self, request: Request, payload: dict[str, Any]) -> dict[str, Any]:
+		await self.check_permissions(request)
+		serializer = self.serializer()
+		try:
+			await serializer.is_valid(payload)
+		except SerializerValidationError as exc:
+			raise HTTPException(
+				status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+				detail=exc.detail,
+			) from exc
+		instance = await serializer.save()
+		return serializer.representation(instance)
+
+	async def update(
+		self,
+		request: Request,
+		pk: UUID,
+		payload: dict[str, Any],
+		*,
+		partial: bool,
+	) -> dict[str, Any]:
+		instance = await self.get_object(request, pk)
+		serializer = self.serializer(instance, partial=partial)
+		try:
+			await serializer.is_valid(payload)
+		except SerializerValidationError as exc:
+			raise HTTPException(
+				status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+				detail=exc.detail,
+			) from exc
+		instance = await serializer.save()
+		return serializer.representation(instance)
+
+	async def destroy(self, request: Request, pk: UUID) -> None:
+		instance = await self.get_object(request, pk)
+		await instance.delete()
+
+	def as_router(self, *, prefix: str, tags: Sequence[str] | None = None) -> APIRouter:
+		"""Build conventional collection/detail routes for this viewset."""
+		router = APIRouter(prefix=prefix, tags=[*tags] if tags else [])
+		input_schema = self.serializer_class.input_schema()
+		partial_input_schema = self.serializer_class._schema(for_input=True, partial=True)
+		output_schema = self.serializer_class.output_schema()
+		dependencies = [Depends(dependency) for dependency in self.authentication_dependencies]
+
+		@router.get("/", response_model=None, dependencies=dependencies)
+		async def list_view(request: Request) -> Any:
+			return await self.list(request)
+
+		@router.get("/{pk}", response_model=output_schema, dependencies=dependencies)
+		async def retrieve_view(request: Request, pk: UUID) -> Any:
+			return await self.retrieve(request, pk)
+
+		async def create_view(request: Request, payload: Any) -> Any:
+			return await self.create(request, payload.model_dump(exclude_unset=True))
+
+		async def update_view(request: Request, pk: UUID, payload: Any) -> Any:
+			return await self.update(
+				request, pk, payload.model_dump(exclude_unset=True), partial=False
+			)
+
+		async def partial_update_view(request: Request, pk: UUID, payload: Any) -> Any:
+			return await self.update(
+				request, pk, payload.model_dump(exclude_unset=True), partial=True
+			)
+
+		def signature(*parameters: inspect.Parameter) -> inspect.Signature:
+			return inspect.Signature(parameters)
+
+		request_parameter = inspect.Parameter(
+			"request", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=Request
+		)
+		pk_parameter = inspect.Parameter(
+			"pk", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=UUID
+		)
+		cast(Any, create_view).__signature__ = signature(
+			request_parameter,
+			inspect.Parameter(
+				"payload",
+				inspect.Parameter.POSITIONAL_OR_KEYWORD,
+				default=Body(...),
+				annotation=input_schema,
+			),
+		)
+		cast(Any, update_view).__signature__ = signature(
+			request_parameter,
+			pk_parameter,
+			inspect.Parameter(
+				"payload",
+				inspect.Parameter.POSITIONAL_OR_KEYWORD,
+				default=Body(...),
+				annotation=input_schema,
+			),
+		)
+		cast(Any, partial_update_view).__signature__ = signature(
+			request_parameter,
+			pk_parameter,
+			inspect.Parameter(
+				"payload",
+				inspect.Parameter.POSITIONAL_OR_KEYWORD,
+				default=Body(...),
+				annotation=partial_input_schema,
+			),
+		)
+		router.add_api_route(
+			"/",
+			create_view,
+			methods=["POST"],
+			response_model=output_schema,
+			status_code=status.HTTP_201_CREATED,
+			dependencies=dependencies,
+		)
+		router.add_api_route(
+			"/{pk}",
+			update_view,
+			methods=["PUT"],
+			response_model=output_schema,
+			dependencies=dependencies,
+		)
+		router.add_api_route(
+			"/{pk}",
+			partial_update_view,
+			methods=["PATCH"],
+			response_model=output_schema,
+			dependencies=dependencies,
+		)
+
+		@router.delete(
+			"/{pk}", status_code=status.HTTP_204_NO_CONTENT, dependencies=dependencies
+		)
+		async def destroy_view(request: Request, pk: UUID) -> None:
+			await self.destroy(request, pk)
+
+		return router
+