fsrest

fsrest provides reusable single-resource REST CRUD orchestration with action names familiar to Django REST Framework users. It is framework-independent: request and response objects are Pydantic models, while persistence is supplied through a small repository protocol.

Designed and developed by Codex.

Install

pip install fsrest

Python 3.9+ and Pydantic 1.10/2.x are supported.

DRF-style actions

CrudViewSet follows DRF's standard action vocabulary:

• list
• retrieve
• create
• update
• partial_update
• destroy

It is deliberately not an HTTP view and does not depend on Django. A FastAPI, Flask, Django, or other framework adapter can call these actions after request validation.

Bind a repository to CrudViewSet. Request schemas provide the conversion methods needed to turn HTTP-facing data into repository fields.

from pydantic import BaseModel
from fsrest import CrudViewSet, PageRequest, PageResponse

class Item(BaseModel):
    id: str
    name: str

class Filters(BaseModel):
    name: str | None = None

class Ordering(BaseModel):
    field: str = "id"

class PageData(BaseModel):
    items: list[Item]
    total: int

class ListQuery(PageRequest):
    name: str | None = None

    def build_filters(self) -> Filters:
        return Filters(name=self.name)

    def build_ordering(self) -> Ordering:
        return Ordering()

    def build_response(self, *, page_data: PageData) -> PageResponse[Item]:
        return PageResponse[Item](
            items=page_data.items,
            total=page_data.total,
            page=self.page,
            page_size=self.page_size,
        )

class ItemRepository:
    @classmethod
    def list_schema_page(cls, *, filters, ordering, page, page_size) -> PageData:
        ...

    # Also implement get_schema_by_id, create_schema,
    # update_schema_by_id, and delete_by_id.

class ItemViewSet(CrudViewSet):
    repository = ItemRepository

Framework code can now use familiar action names:

page = ItemViewSet.list(query=query)
item = ItemViewSet.retrieve(query=lookup)
created = ItemViewSet.create(payload=create_payload)
updated = ItemViewSet.update(payload=update_payload)
patched = ItemViewSet.partial_update(payload=patch_payload)
result = ItemViewSet.destroy(payload=delete_payload)

Override perform_create, perform_update, or perform_destroy to add audit logging, events, or transaction behavior around persistence.

The library raises RestApiError for missing records and failed deletes. To integrate with an application's existing exception middleware, subclass it and bind error_class:

class ApplicationApiError(RestApiError):
    error_code = 400455

class ItemViewSet(CrudViewSet):
    repository = ItemRepository
    error_class = ApplicationApiError

Migrating from 0.1

The 0.1 API remains available for compatibility. New code should prefer these names:

Development and publishing

From the pytools repository root, use the unified release script:

python make.py fsrest test
python make.py fsrest build
python make.py fsrest publish

publish uploads the artifacts under fsrest/dist/ using the PyPI credentials configured in ~/.pypirc. Before publishing a new release, update the version in pyproject.toml, run tests, and build fresh artifacts.