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)

Customizing behavior

Subclass a viewset and override only the smallest relevant hook. The public actions stay unchanged, so framework adapters do not need special cases.

class TenantItemViewSet(ItemViewSet):
    not_found_message = "Item {lookup_value} does not exist"

    @classmethod
    def get_repository(cls):
        # Select a repository at runtime, for example by tenant context.
        return repository_for_current_tenant()

    @classmethod
    def get_filters(cls, query):
        filters = super().get_filters(query)
        return filters.model_copy(update={"tenant_id": current_tenant_id()})

    @classmethod
    def perform_create(cls, fields):
        item = super().perform_create(fields)
        publish_item_created(item)
        return item

Available customization layers:

get_update_fields(payload, partial=...) receives whether the caller used update or partial_update, so applications can implement PUT/PATCH semantics without replacing either action.

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.