fsrest

fsrest extracts reusable single-resource REST CRUD orchestration from application code. It is framework-independent: request/response objects are Pydantic models, while persistence is supplied through a small DAO protocol.

Designed and developed by Codex.

Install

pip install fsrest

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

Usage

Bind a DAO to RestCrudLogicBase. Request schemas provide the small conversion methods needed to turn HTTP-facing data into DAO fields.

from pydantic import BaseModel
from fsrest import RestCrudLogicBase, RestPageReqSchema, RestPageRespSchema

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(RestPageReqSchema):
    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) -> RestPageRespSchema[Item]:
        return RestPageRespSchema[Item](
            items=page_data.items,
            total=page_data.total,
            page=self.page,
            page_size=self.page_size,
        )

class ItemDao:
    @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 ItemLogic(RestCrudLogicBase):
    dao_rest_crud = ItemDao

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 ItemLogic(RestCrudLogicBase):
    dao_rest_crud = ItemDao
    error_class = ApplicationApiError

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.