feat: add Lookups documentation and implement flexible lookup system for FastAPI Mason. Rename methods in pagination and schemas

Author: bubaley

README.md

@@ -58,7 +58,7 @@ from tortoise.models import Model
 
 from fastapi_mason.decorators import action, viewset
 from fastapi_mason.pagination import PageNumberPagination
-from fastapi_mason.schemas import SchemaMeta, generate_schema, rebuild_schema
+from fastapi_mason.schemas import SchemaMeta, build_schema, rebuild_schema
 from fastapi_mason.viewsets import ModelViewSet
 from fastapi_mason.wrappers import PaginatedResponseDataWrapper, ResponseDataWrapper
 
@@ -85,7 +85,7 @@ class CompanyMeta(SchemaMeta):
     include = ('id', 'name', 'full_name', 'created_at', 'updated_at')
 
 # Schemas
-CompanySchema = generate_schema(Company, meta=CompanyMeta)
+CompanySchema = build_schema(Company, meta=CompanyMeta)
 CompanyCreateSchema = rebuild_schema(CompanySchema, exclude_readonly=True)
 
 # Views

app/domains/company/models.py

@@ -6,3 +6,6 @@
 class Company(BaseModel):
     name = fields.CharField(max_length=255)
     full_name = fields.TextField(null=True)
+
+    class Meta:
+        ordering = ['-id']

app/domains/company/schemas.py

@@ -1,6 +1,6 @@
 from app.domains.company.meta import CompanyMeta
 from app.domains.company.models import Company
-from fastapi_mason.schemas import generate_schema, rebuild_schema
+from fastapi_mason.schemas import build_schema, rebuild_schema
 
-CompanySchema = generate_schema(Company, meta=CompanyMeta)
+CompanySchema = build_schema(Company, meta=CompanyMeta)
 CompanyCreateSchema = rebuild_schema(CompanySchema, exclude_readonly=True)

app/domains/project/meta.py

@@ -1,6 +1,6 @@
 from app.core.models import BASE_FIELDS
 from app.domains.company.meta import CompanyMeta
-from fastapi_mason.schemas import SchemaMeta, generate_schema_meta
+from fastapi_mason.schemas import SchemaMeta, build_schema_meta
 
 
 class ProjectMeta(SchemaMeta):
@@ -21,12 +21,12 @@ class TaskMeta(SchemaMeta):
 
 
 def get_project_with_tasks_meta():
-    return generate_schema_meta(
+    return build_schema_meta(
         ProjectMeta,
         ('company', CompanyMeta),
         ('tasks', get_task_with_project_meta()),
     )
 
 
 def get_task_with_project_meta():
-    return generate_schema_meta(TaskMeta, ('project', ProjectMeta))
+    return build_schema_meta(TaskMeta, ('project', ProjectMeta))

app/domains/project/schemas.py

@@ -4,9 +4,9 @@
 
 from app.domains.project.meta import get_project_with_tasks_meta, get_task_with_project_meta
 from app.domains.project.models import Project, Task
-from fastapi_mason.schemas import ConfigSchemaMeta, generate_schema, rebuild_schema
+from fastapi_mason.schemas import ConfigSchemaMeta, build_schema, rebuild_schema
 
-ProjectReadSchema = generate_schema(
+ProjectReadSchema = build_schema(
     Project,
     meta=get_project_with_tasks_meta(),
     config=ConfigSchemaMeta(allow_cycles=True),
@@ -18,7 +18,7 @@
 )
 
 
-TaskReadSchema = generate_schema(Task, meta=get_task_with_project_meta())
+TaskReadSchema = build_schema(Task, meta=get_task_with_project_meta())
 TaskCreateSchema = rebuild_schema(TaskReadSchema, exclude_readonly=True)
 
 

docs/assets/metrics.js

@@ -9,4 +9,4 @@ ym(103332320, "init", {
     trackLinks:true,
     accurateTrackBounce:true,
     webvisor:true
-});
+});

docs/index.md

@@ -56,7 +56,7 @@ from tortoise.models import Model
 
 from fastapi_mason.decorators import action, viewset
 from fastapi_mason.pagination import PageNumberPagination
-from fastapi_mason.schemas import SchemaMeta, generate_schema, rebuild_schema
+from fastapi_mason.schemas import SchemaMeta, build_schema, rebuild_schema
 from fastapi_mason.viewsets import ModelViewSet
 from fastapi_mason.wrappers import PaginatedResponseDataWrapper, ResponseDataWrapper
 
@@ -87,7 +87,7 @@ class CompanyMeta(SchemaMeta):
 
 
 # Schemas
-CompanySchema = generate_schema(Company, meta=CompanyMeta)
+CompanySchema = build_schema(Company, meta=CompanyMeta)
 CompanyCreateSchema = rebuild_schema(CompanySchema, exclude_readonly=True)
 
 # Views

docs/pagination.md

@@ -157,12 +157,12 @@ class CompanyViewSet(ModelViewSet[Company]):
     pagination = PageNumberPagination
 
     @action(methods=["GET"], response_model=List[ProjectReadSchema])
-    async def paginated_list(self, pagination: PageNumberPagination = Depends(PageNumberPagination.from_query)):
+    async def paginated_list(self, pagination: PageNumberPagination = Depends(PageNumberPagination.build)):
         queryset = self.get_queryset()
         return await self.get_paginated_response(queryset=queryset, pagination=pagination)
 
     @action(methods=["GET"], response_model=PaginatedResponseDataWrapper[ProjectReadSchema, PageNumberPagination[Company]])
-    async def wrapped_paginated_list(self, pagination: PageNumberPagination = Depends(PageNumberPagination.from_query)):
+    async def wrapped_paginated_list(self, pagination: PageNumberPagination = Depends(PageNumberPagination.build)):
         queryset = self.get_queryset()
         return await self.get_paginated_response(queryset=queryset, pagination=pagination, wrapper=PaginatedResponseDataWrapper)
 ```
@@ -182,7 +182,7 @@ class CustomPageNumberPagination(PageNumberPagination[ModelType]):
     """Custom pagination implementation with flexible page size and offset."""
 
     @classmethod
-    def from_query(
+    def build(
         cls,
         page: int = Query(1, ge=1, description="Page number"),
         size: int = Query(20, ge=1, le=1000, description="Number of records per page"),
@@ -210,7 +210,7 @@ class CustomPagination(Pagination[ModelType]):
     pages: int = 0
 
     @classmethod
-    def from_query(
+    def build(
         cls,
         page: int = Query(1, ge=1, description="Page number to retrieve"),
         size: int = Query(10, ge=1, le=50, description="Number of records per page"),
@@ -231,6 +231,6 @@ class CustomPagination(Pagination[ModelType]):
 
 **Explanation**
 
-- `from_query`: Defines how query parameters are parsed into the pagination instance. In this example, it uses page and size with constraints (e.g., size capped at 50).
+- `build`: Defines how query parameters are parsed into the pagination instance. In this example, it uses page and size with constraints (e.g., size capped at 50).
 - `paginate`: Applies the pagination logic to the queryset, calculating the offset based on the page and size, then limiting the results.
 - `fill_meta`: Computes metadata like the total item count and number of pages, ensuring accurate pagination information in the response.

docs/quick-start.md

@@ -111,7 +111,7 @@ Define which fields to include in your API schemas and how to handle relationshi
 
 ```python title="app/domains/project/meta.py"
 from app.core.models import BASE_FIELDS
-from fastapi_mason.schemas import SchemaMeta, generate_schema_meta
+from fastapi_mason.schemas import SchemaMeta, build_schema_meta
 
 
 class ProjectMeta(SchemaMeta):
@@ -135,15 +135,15 @@ class TaskMeta(SchemaMeta):
 # Create meta for nested schemas with relationships
 def get_project_with_tasks_meta():
     """Project schema with embedded tasks"""
-    return generate_schema_meta(
+    return build_schema_meta(
         ProjectMeta,
         ("tasks", get_task_with_project_meta()),
     )
 
 
 def get_task_with_project_meta():
     """Task schema with embedded project data"""
-    return generate_schema_meta(TaskMeta, ("project", ProjectMeta))
+    return build_schema_meta(TaskMeta, ("project", ProjectMeta))
 ```
 
 ### 5. Generate Schemas
@@ -162,7 +162,7 @@ from app.domains.project.meta import (
     get_task_with_project_meta,
 )
 from app.domains.project.models import Project, Task
-from fastapi_mason.schemas import ConfigSchemaMeta, generate_schema, rebuild_schema
+from fastapi_mason.schemas import ConfigSchemaMeta, build_schema, rebuild_schema
 
 """
 https://tortoise.github.io/examples/pydantic.html?h=init_models#early-model-init
@@ -172,10 +172,10 @@ https://github.com/bubaley/fastapi-mason/blob/main/app/core/database.py
 Tortoise.init_models(["app.domains.project.models"], "models")
 
 # Simple project schema
-ProjectReadSchema = generate_schema(Project, meta=ProjectMeta)
+ProjectReadSchema = build_schema(Project, meta=ProjectMeta)
 
 # Detailed project schema with tasks (handles circular references)
-ProjectDetailSchema = generate_schema(
+ProjectDetailSchema = build_schema(
     Project,
     meta=get_project_with_tasks_meta(),
     config=ConfigSchemaMeta(allow_cycles=True),  # Handle circular references
@@ -192,7 +192,7 @@ class ProjectStatsSchema(BaseModel):
 
 
 # Task schemas
-TaskReadSchema = generate_schema(Task, meta=get_task_with_project_meta())
+TaskReadSchema = build_schema(Task, meta=get_task_with_project_meta())
 TaskCreateSchema = rebuild_schema(TaskReadSchema, exclude_readonly=True)
 
 # Type checking support
@@ -267,7 +267,7 @@ class TaskViewSet(BaseViewSet[Task]):
     @action(methods=["GET"], response_model=PaginatedResponseDataWrapper[TaskReadSchema, PageNumberPagination])
     async def list(
         self,
-        pagination: PageNumberPagination = Depends(PageNumberPagination.from_query),
+        pagination: PageNumberPagination = Depends(PageNumberPagination.build),
         project_id: bool = Query(...),
     ):
         """Override list method"""
@@ -393,14 +393,14 @@ And tasks endpoints.
 
 ### 1. **Relationship Handling**
 
-- ForeignKey and related objects are automatically included in schemas using `generate_schema_meta`.
+- ForeignKey and related objects are automatically included in schemas using `build_schema_meta`.
 - Nested object serialization (e.g., project with tasks, task with project).
 - Circular reference support with `ConfigSchemaMeta(allow_cycles=True)`.
 
 ### 2. **Flexible Schema Generation**
 
 - Different schemas for list and detail views.
-- Customizable field inclusion through meta classes (`SchemaMeta`, `generate_schema_meta`).
+- Customizable field inclusion through meta classes (`SchemaMeta`, `build_schema_meta`).
 - Generation of nested schemas for related models.
 
 ### 3. **Base and Custom ViewSets**

docs/schemas.md

@@ -11,7 +11,7 @@ The `config` parameter uses `PydanticMetaData`, allowing you to apply all standa
 The schema system consists of three main components:
 
 1. **SchemaMeta** - Defines which fields to include/exclude
-2. **generate_schema()** - Creates Pydantic models from Tortoise models
+2. **build_schema()** - Creates Pydantic models from Tortoise models
 3. **rebuild_schema()** - Modifies existing schemas for different use cases
 
 ## SchemaMeta Classes
@@ -73,12 +73,12 @@ class ProjectMeta(SchemaMeta):
 ```
 
 ```python title="app/domains/project/schemas.py"
-from fastapi_mason.schemas import generate_schema, rebuild_schema
+from fastapi_mason.schemas import build_schema, rebuild_schema
 from app.domains.project.models import Project
 from app.domains.project.meta import ProjectMeta
 
 # Generate read schema (includes all fields)
-ProjectReadSchema = generate_schema(Project, meta=ProjectMeta)
+ProjectReadSchema = build_schema(Project, meta=ProjectMeta)
 
 # Generate create schema (excludes readonly fields)
 ProjectCreateSchema = rebuild_schema(
@@ -105,7 +105,7 @@ class Task(BaseModel):
 ### Meta Classes for Relationships
 
 ```python title="app/domains/project/meta.py"
-from fastapi_mason.schemas import SchemaMeta, generate_schema_meta
+from fastapi_mason.schemas import SchemaMeta, build_schema_meta
 
 class ProjectMeta(SchemaMeta):
     include = (
@@ -125,27 +125,27 @@ class TaskMeta(SchemaMeta):
 # Create meta for nested schemas with relationships
 def get_project_with_tasks_meta():
     """Project schema with embedded tasks"""
-    return generate_schema_meta(
+    return build_schema_meta(
         ProjectMeta,
         ('tasks', get_task_with_project_meta()),
     )
 
 def get_task_with_project_meta():
     """Task schema with embedded project data"""
-    return generate_schema_meta(TaskMeta, ('project', ProjectMeta))
+    return build_schema_meta(TaskMeta, ('project', ProjectMeta))
 ```
 
 ### Schema Generation with Relationships
 
 ```python title="app/domains/project/schemas.py"
-from fastapi_mason.schemas import ConfigSchemaMeta, generate_schema, rebuild_schema
+from fastapi_mason.schemas import ConfigSchemaMeta, build_schema, rebuild_schema
 
 # Simple schemas
-ProjectReadSchema = generate_schema(Project, meta=ProjectMeta)
-TaskReadSchema = generate_schema(Task, meta=get_task_with_project_meta())
+ProjectReadSchema = build_schema(Project, meta=ProjectMeta)
+TaskReadSchema = build_schema(Task, meta=get_task_with_project_meta())
 
 # Detailed project schema with tasks (handles circular references)
-ProjectDetailSchema = generate_schema(
+ProjectDetailSchema = build_schema(
     Project,
     meta=get_project_with_tasks_meta(),
     config=ConfigSchemaMeta(allow_cycles=True),  # Handle circular references
@@ -162,7 +162,7 @@ The `rebuild_schema()` function allows you to create variations of existing sche
 
 ```python
 # Original schema includes all fields
-ProjectReadSchema = generate_schema(Project, meta=ProjectMeta)
+ProjectReadSchema = build_schema(Project, meta=ProjectMeta)
 
 # Create schema excludes readonly fields like id, created_at, updated_at
 ProjectCreateSchema = rebuild_schema(
@@ -197,7 +197,7 @@ config = ConfigSchemaMeta(
     include=('custom_field',),
 )
 
-schema = generate_schema(
+schema = build_schema(
     Project,
     meta=ProjectMeta,
     config=config
@@ -213,7 +213,7 @@ from typing import TYPE_CHECKING
 from tortoise.contrib.pydantic import PydanticModel
 
 # Runtime schema generation
-ProjectSchema = generate_schema(Project, meta=ProjectMeta)
+ProjectSchema = build_schema(Project, meta=ProjectMeta)
 
 # Type hints for IDE
 if TYPE_CHECKING:
@@ -268,8 +268,8 @@ class ProjectMetas:
         include = ('name', 'description')
 
 # Use specific meta for different contexts
-ProjectListSchema = generate_schema(Project, meta=ProjectMetas.List)
-ProjectDetailSchema = generate_schema(Project, meta=ProjectMetas.Detail)
+ProjectListSchema = build_schema(Project, meta=ProjectMetas.List)
+ProjectDetailSchema = build_schema(Project, meta=ProjectMetas.Detail)
 ```
 
 ## Common Patterns
@@ -278,16 +278,16 @@ ProjectDetailSchema = generate_schema(Project, meta=ProjectMetas.Detail)
 
 ```python
 # Different schemas for different API responses
-ProjectListSchema = generate_schema(Project, meta=ProjectListMeta)  # Minimal fields
-ProjectDetailSchema = generate_schema(Project, meta=ProjectDetailMeta)  # Full fields
+ProjectListSchema = build_schema(Project, meta=ProjectListMeta)  # Minimal fields
+ProjectDetailSchema = build_schema(Project, meta=ProjectDetailMeta)  # Full fields
 ProjectCreateSchema = rebuild_schema(ProjectDetailSchema, exclude_readonly=True)
 ```
 
 ### Schema Naming
 
 ```python
 # Explicit naming for better OpenAPI documentation
-ProjectReadSchema = generate_schema(
+ProjectReadSchema = build_schema(
     Project,
     meta=ProjectMeta,
     name="ProjectResponse"