fsrest 0.1.0__tar.gz

fsrest-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+/.venv/
+/dist/
+/build/
+/.pytest_cache/
+/.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+

fsrest-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 huoyinghui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

fsrest-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: fsrest
+Version: 0.1.0
+Summary: Reusable, framework-agnostic REST CRUD logic for Pydantic applications
+Project-URL: Homepage, https://github.com/pydtools/fsrest
+Project-URL: Repository, https://github.com/pydtools/fsrest
+Project-URL: Issues, https://github.com/pydtools/fsrest/issues
+Author-email: huoyinghui <hyhlinux@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 huoyinghui
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+License-File: LICENSE
+Keywords: crud,dao,fastapi,pydantic,rest
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic<3,>=1.10
+Description-Content-Type: text/markdown
+
+# 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.
+
+## Install
+
+```bash
+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.
+
+```python
+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`:
+
+```python
+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:
+
+```bash
+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.
+

fsrest-0.1.0/README.md

@@ -0,0 +1,88 @@
+# 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.
+
+## Install
+
+```bash
+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.
+
+```python
+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`:
+
+```python
+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:
+
+```bash
+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.
+

fsrest-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fsrest"
+version = "0.1.0"
+description = "Reusable, framework-agnostic REST CRUD logic for Pydantic applications"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "huoyinghui", email = "hyhlinux@gmail.com" },
+]
+requires-python = ">=3.9"
+dependencies = [
+    "pydantic>=1.10,<3",
+]
+keywords = ["rest", "crud", "pydantic", "fastapi", "dao"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/pydtools/fsrest"
+Repository = "https://github.com/pydtools/fsrest"
+Issues = "https://github.com/pydtools/fsrest/issues"
+
+[dependency-groups]
+dev = [
+    "build>=1.2",
+    "pytest>=7",
+    "ruff>=0.9",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fsrest"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

fsrest-0.1.0/src/fsrest/__init__.py

@@ -0,0 +1,28 @@
+"""Public API for fsrest."""
+
+from .base import (
+    RestCreateReqProtocol,
+    RestCrudDaoProtocol,
+    RestCrudLogicBase,
+    RestIdReqProtocol,
+    RestListReqProtocol,
+    RestUpdateReqProtocol,
+)
+from .exceptions import APIError, RestApiError
+from .schemas import RestCrudSchemaMapSchema, RestDeleteRespSchema, RestPageReqSchema, RestPageRespSchema
+
+__all__ = [
+    "APIError",
+    "RestApiError",
+    "RestCreateReqProtocol",
+    "RestCrudDaoProtocol",
+    "RestCrudLogicBase",
+    "RestCrudSchemaMapSchema",
+    "RestDeleteRespSchema",
+    "RestIdReqProtocol",
+    "RestListReqProtocol",
+    "RestPageReqSchema",
+    "RestPageRespSchema",
+    "RestUpdateReqProtocol",
+]
+

fsrest-0.1.0/src/fsrest/base.py

@@ -0,0 +1,163 @@
+"""Reusable single-resource REST CRUD logic."""
+
+from __future__ import annotations
+
+from typing import Generic, Protocol, TypeVar, cast
+
+from pydantic import BaseModel
+
+from .exceptions import RestApiError
+from .schemas import RestCrudSchemaMapSchema, RestDeleteRespSchema
+
+RestItemSchemaT = TypeVar("RestItemSchemaT", bound=BaseModel)
+RestListReqSchemaT = TypeVar("RestListReqSchemaT", bound=BaseModel)
+RestListRespSchemaT = TypeVar("RestListRespSchemaT", bound=BaseModel)
+RestListFilterSchemaT = TypeVar("RestListFilterSchemaT", bound=BaseModel)
+RestOrderingSchemaT = TypeVar("RestOrderingSchemaT", bound=BaseModel)
+RestPageDataSchemaT = TypeVar("RestPageDataSchemaT", bound=BaseModel)
+RestGetReqSchemaT = TypeVar("RestGetReqSchemaT", bound=BaseModel)
+RestCreateReqSchemaT = TypeVar("RestCreateReqSchemaT", bound=BaseModel)
+RestCreateFieldsSchemaT = TypeVar("RestCreateFieldsSchemaT", bound=BaseModel)
+RestUpdateReqSchemaT = TypeVar("RestUpdateReqSchemaT", bound=BaseModel)
+RestUpdateFieldsSchemaT = TypeVar("RestUpdateFieldsSchemaT", bound=BaseModel)
+RestDeleteReqSchemaT = TypeVar("RestDeleteReqSchemaT", bound=BaseModel)
+
+ItemT_co = TypeVar("ItemT_co", bound=BaseModel, covariant=True)
+FilterT_co = TypeVar("FilterT_co", bound=BaseModel, covariant=True)
+FilterT_contra = TypeVar("FilterT_contra", bound=BaseModel, contravariant=True)
+OrderingT_co = TypeVar("OrderingT_co", bound=BaseModel, covariant=True)
+OrderingT_contra = TypeVar("OrderingT_contra", bound=BaseModel, contravariant=True)
+PageDataT_co = TypeVar("PageDataT_co", bound=BaseModel, covariant=True)
+PageDataT_contra = TypeVar("PageDataT_contra", bound=BaseModel, contravariant=True)
+ListRespT_co = TypeVar("ListRespT_co", bound=BaseModel, covariant=True)
+CreateFieldsT_co = TypeVar("CreateFieldsT_co", bound=BaseModel, covariant=True)
+CreateFieldsT_contra = TypeVar("CreateFieldsT_contra", bound=BaseModel, contravariant=True)
+UpdateFieldsT_co = TypeVar("UpdateFieldsT_co", bound=BaseModel, covariant=True)
+UpdateFieldsT_contra = TypeVar("UpdateFieldsT_contra", bound=BaseModel, contravariant=True)
+
+
+class RestListReqProtocol(Protocol[FilterT_co, OrderingT_co, PageDataT_contra, ListRespT_co]):
+    page: int
+    page_size: int
+
+    def build_filters(self) -> FilterT_co: ...
+
+    def build_ordering(self) -> OrderingT_co: ...
+
+    def build_response(self, *, page_data: PageDataT_contra) -> ListRespT_co: ...
+
+
+class RestIdReqProtocol(Protocol):
+    id: str
+
+
+class RestCreateReqProtocol(Protocol[CreateFieldsT_co]):
+    def build_create_fields(self) -> CreateFieldsT_co: ...
+
+
+class RestUpdateReqProtocol(Protocol[UpdateFieldsT_co]):
+    id: str
+
+    def build_update_fields(self) -> UpdateFieldsT_co: ...
+
+
+class RestCrudDaoProtocol(
+    Protocol[ItemT_co, FilterT_contra, OrderingT_contra, PageDataT_co, CreateFieldsT_contra, UpdateFieldsT_contra]
+):
+    @classmethod
+    def list_schema_page(
+        cls, *, filters: FilterT_contra, ordering: OrderingT_contra, page: int, page_size: int
+    ) -> PageDataT_co: ...
+
+    @classmethod
+    def get_schema_by_id(cls, item_id: str) -> ItemT_co | None: ...
+
+    @classmethod
+    def create_schema(cls, *, fields: CreateFieldsT_contra) -> ItemT_co: ...
+
+    @classmethod
+    def update_schema_by_id(cls, *, item_id: str, fields: UpdateFieldsT_contra) -> ItemT_co | None: ...
+
+    @classmethod
+    def delete_by_id(cls, item_id: str) -> bool: ...
+
+
+class RestCrudLogicBase(
+    Generic[
+        RestItemSchemaT,
+        RestListReqSchemaT,
+        RestListRespSchemaT,
+        RestListFilterSchemaT,
+        RestOrderingSchemaT,
+        RestPageDataSchemaT,
+        RestGetReqSchemaT,
+        RestCreateReqSchemaT,
+        RestCreateFieldsSchemaT,
+        RestUpdateReqSchemaT,
+        RestUpdateFieldsSchemaT,
+        RestDeleteReqSchemaT,
+    ]
+):
+    """Base logic for a single-resource REST CRUD API.
+
+    Subclasses bind ``dao_rest_crud``. ``schema_map`` remains available for
+    endpoint generators and introspection, but the CRUD methods do not require it.
+    """
+
+    dao_rest_crud: type[
+        RestCrudDaoProtocol[
+            RestItemSchemaT,
+            RestListFilterSchemaT,
+            RestOrderingSchemaT,
+            RestPageDataSchemaT,
+            RestCreateFieldsSchemaT,
+            RestUpdateFieldsSchemaT,
+        ]
+    ]
+    schema_map: RestCrudSchemaMapSchema
+    error_class: type[RestApiError] = RestApiError
+
+    @classmethod
+    def list_items(cls, *, query: RestListReqSchemaT) -> RestListRespSchemaT:
+        contract = cast(
+            RestListReqProtocol[RestListFilterSchemaT, RestOrderingSchemaT, RestPageDataSchemaT, RestListRespSchemaT],
+            query,
+        )
+        page_data = cls.dao_rest_crud.list_schema_page(
+            filters=contract.build_filters(),
+            ordering=contract.build_ordering(),
+            page=contract.page,
+            page_size=contract.page_size,
+        )
+        return contract.build_response(page_data=page_data)
+
+    @classmethod
+    def get_item(cls, *, query: RestGetReqSchemaT) -> RestItemSchemaT:
+        contract = cast(RestIdReqProtocol, query)
+        item = cls.dao_rest_crud.get_schema_by_id(contract.id)
+        if item is None:
+            raise cls.error_class(f"Record not found: {contract.id}")
+        return item
+
+    @classmethod
+    def create_item(cls, *, payload: RestCreateReqSchemaT) -> RestItemSchemaT:
+        contract = cast(RestCreateReqProtocol[RestCreateFieldsSchemaT], payload)
+        return cls.dao_rest_crud.create_schema(fields=contract.build_create_fields())
+
+    @classmethod
+    def update_item(cls, *, payload: RestUpdateReqSchemaT) -> RestItemSchemaT:
+        contract = cast(RestUpdateReqProtocol[RestUpdateFieldsSchemaT], payload)
+        item = cls.dao_rest_crud.update_schema_by_id(item_id=contract.id, fields=contract.build_update_fields())
+        if item is None:
+            raise cls.error_class(f"Record not found: {contract.id}")
+        return item
+
+    @classmethod
+    def delete_item(cls, *, payload: RestDeleteReqSchemaT) -> RestDeleteRespSchema:
+        contract = cast(RestIdReqProtocol, payload)
+        if cls.dao_rest_crud.get_schema_by_id(contract.id) is None:
+            raise cls.error_class(f"Record not found: {contract.id}")
+        if not cls.dao_rest_crud.delete_by_id(contract.id):
+            raise cls.error_class(f"Failed to delete record: {contract.id}")
+        return RestDeleteRespSchema(id=contract.id, deleted=True)
+

fsrest-0.1.0/src/fsrest/exceptions.py

@@ -0,0 +1,46 @@
+"""Exceptions raised by :mod:`fsrest`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class RestApiError(Exception):
+    """A framework-independent REST business error.
+
+    ``code`` and ``error_code`` are intentionally plain integers so an
+    application can translate the exception into its own HTTP response type.
+    """
+
+    code = 400
+    error_code = 400455
+    message = "REST operation failed"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        code: int | None = None,
+        error_code: int | None = None,
+        data: Any = None,
+    ) -> None:
+        self.message = message if message is not None else type(self).message
+        self.code = code if code is not None else type(self).code
+        self.error_code = error_code if error_code is not None else type(self).error_code
+        self.data = data
+        super().__init__(self.message)
+
+    @property
+    def msg(self) -> str:
+        """Compatibility alias used by applications that call the field ``msg``."""
+
+        return self.message
+
+    @msg.setter
+    def msg(self, value: str) -> None:
+        self.message = value
+        self.args = (value,)
+
+
+# Compatibility with the original internal package.
+APIError = RestApiError

fsrest-0.1.0/src/fsrest/py.typed

@@ -0,0 +1 @@
+

fsrest-0.1.0/src/fsrest/schemas.py

@@ -0,0 +1,49 @@
+"""Common Pydantic schemas used by REST CRUD logic."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+RestItemSchemaT = TypeVar("RestItemSchemaT", bound=BaseModel)
+
+
+class RestPageReqSchema(BaseModel):
+    """Page-number pagination input."""
+
+    page: int = Field(default=1, ge=1, le=100000, description="Page number, starting at 1")
+    page_size: int = Field(default=20, ge=1, le=200, description="Number of records per page")
+
+
+class RestPageRespSchema(BaseModel, Generic[RestItemSchemaT]):
+    """Page-number pagination response."""
+
+    items: list[RestItemSchemaT] = Field(default_factory=list, description="Records on the current page")
+    total: int = Field(default=0, ge=0, description="Total number of records")
+    page: int = Field(default=1, ge=1, description="Current page number")
+    page_size: int = Field(default=20, ge=1, description="Number of records per page")
+
+
+class RestDeleteRespSchema(BaseModel):
+    """Deletion response."""
+
+    id: str = Field(..., description="ID of the deleted record")
+    deleted: bool = Field(default=True, description="Whether the record was deleted")
+
+
+class RestCrudSchemaMapSchema(BaseModel):
+    """Concrete schema types bound to a :class:`RestCrudLogicBase` subclass."""
+
+    item_schema: type[BaseModel]
+    list_req_schema: type[BaseModel]
+    list_resp_schema: type[BaseModel]
+    list_filter_schema: type[BaseModel]
+    ordering_schema: type[BaseModel]
+    page_data_schema: type[BaseModel]
+    get_req_schema: type[BaseModel]
+    create_req_schema: type[BaseModel]
+    create_fields_schema: type[BaseModel]
+    update_req_schema: type[BaseModel]
+    update_fields_schema: type[BaseModel]
+    delete_req_schema: type[BaseModel]