muffin-rest 11.0.1__tar.gz → 12.0.1__tar.gz

muffin_rest-12.0.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.3
+Name: muffin-rest
+Version: 12.0.1
+Summary: The package provides enhanced support for writing REST APIs with Muffin framework
+License: MIT
+Keywords: rest,api,muffin,asgi,asyncio,trio
+Author: Kirill Klenov
+Author-email: horneds@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Trio
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Internet :: WWW/HTTP
+Provides-Extra: peewee
+Provides-Extra: sqlalchemy
+Provides-Extra: yaml
+Requires-Dist: apispec (>=6,<7)
+Requires-Dist: marshmallow (>=3,<4)
+Requires-Dist: marshmallow-peewee ; extra == "peewee"
+Requires-Dist: marshmallow-sqlalchemy ; extra == "sqlalchemy"
+Requires-Dist: muffin
+Requires-Dist: muffin-databases ; extra == "sqlalchemy"
+Requires-Dist: muffin-peewee-aio ; extra == "peewee"
+Requires-Dist: pyyaml ; extra == "yaml"
+Requires-Dist: sqlalchemy ; extra == "sqlalchemy"
+Project-URL: Homepage, https://github.com/klen/muffin-rest
+Project-URL: Repository, https://github.com/klen/muffin-rest
+Description-Content-Type: text/markdown
+
+# Muffin‑REST
+
+**Muffin‑REST** simplifies building RESTful APIs with [Muffin](https://github.com/klen/muffin) by offering:
+
+- Declarative `API` class with resource registration
+- Built-in filtering, sorting, pagination, and search
+- Support for:
+  - [Peewee ORM](http://docs.peewee-orm.com/en/latest/) via `PeeweeEndpoint`
+  - [SQLAlchemy Core](https://docs.sqlalchemy.org/en/14/core/) via `SAEndpoint`
+  - [MongoDB](https://www.mongodb.com/) via `MongoEndpoint`
+- [Swagger/OpenAPI](https://swagger.io/) autodocumentation
+- Works with asyncio, Trio, and Curio
+
+[![Tests Status](https://github.com/klen/muffin-rest/workflows/tests/badge.svg)](https://github.com/klen/muffin-rest/actions)
+[![PyPI Version](https://img.shields.io/pypi/v/muffin-rest)](https://pypi.org/project/muffin-rest/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/muffin-rest)](https://pypi.org/project/muffin-rest/)
+
+## Requirements
+
+- Python >= 3.10
+- Trio requires Peewee backend
+
+## Installation
+
+Install core package:
+
+```bash
+pip install muffin-rest
+```
+
+Add optional backend support:
+
+- SQLAlchemy Core: `pip install muffin-rest[sqlalchemy]`
+- Peewee ORM: `pip install muffin-rest[peewee]`
+- YAML support for Swagger: `pip install muffin-rest[yaml]`
+
+## Quickstart (Peewee example)
+
+```python
+from muffin import Application
+from muffin_rest import API
+from muffin_rest.peewee import PeeweeEndpoint
+from models import User  # your Peewee model
+
+app = Application("myapp")
+api = API(title="User Service", version="1.0")
+
+@api.route
+class UsersEndpoint(PeeweeEndpoint):
+    class Meta:
+        model = User
+        lookup_field = "id"
+        filters = ["name", "email"]
+        ordering = ["-created_at"]
+
+api.setup(app, prefix="/api", swagger=True)
+```
+
+Endpoints available:
+
+- `GET    /api/users/` — list with pagination, search, filtering
+- `POST   /api/users/` — create
+- `GET    /api/users/{id}/` — retrieve
+- `PUT    /api/users/{id}/` — replace
+- `PATCH  /api/users/{id}/` — update
+- `DELETE /api/users/{id}/` — remove
+- Docs: `/api/docs/`, OpenAPI spec: `/api/openapi.json`
+
+## Usage with SQLAlchemy
+
+```python
+from muffin_rest import API
+from muffin_rest.sqlalchemy import SAEndpoint
+from models import my_table, db_engine
+
+api = API()
+@api.route
+class MySAEndpoint(SAEndpoint):
+    class Meta:
+        table = my_table
+        database = db_engine
+
+api.setup(app)
+```
+
+## Usage with MongoDB
+
+```python
+from muffin_rest import API
+from muffin_rest.mongo import MongoEndpoint
+from models import mongo_collection
+
+api = API()
+@api.route
+class MyMongoEndpoint(MongoEndpoint):
+    class Meta:
+        collection = mongo_collection
+
+api.setup(app)
+```
+
+## Advanced Configuration
+
+Customize Swagger and routes via constructor:
+
+```python
+api = API(
+    title="Service API",
+    version="2.1",
+    swagger_ui=True,
+    openapi_path="/api/openapi.json",
+    docs_path="/api/docs/"
+)
+```
+
+## Contributing & Examples
+
+- See `examples/` for live application demos
+- Tests in `tests/` focus on filtering, pagination, status codes
+- Check `CHANGELOG.md` for latest changes
+
+## Bug Tracker
+
+Report bugs or request features:
+https://github.com/klen/muffin-rest/issues
+
+## Contributing
+
+Repo: https://github.com/klen/muffin-rest
+Pull requests, example additions, docs improvements welcome!
+
+## Contributors
+
+- [klen](https://github.com/klen) (Kirill Klenov)
+
+## License
+
+Licensed under the [MIT license](http://opensource.org/licenses/MIT).
+

muffin_rest-12.0.1/README.md

@@ -0,0 +1,138 @@
+# Muffin‑REST
+
+**Muffin‑REST** simplifies building RESTful APIs with [Muffin](https://github.com/klen/muffin) by offering:
+
+- Declarative `API` class with resource registration
+- Built-in filtering, sorting, pagination, and search
+- Support for:
+  - [Peewee ORM](http://docs.peewee-orm.com/en/latest/) via `PeeweeEndpoint`
+  - [SQLAlchemy Core](https://docs.sqlalchemy.org/en/14/core/) via `SAEndpoint`
+  - [MongoDB](https://www.mongodb.com/) via `MongoEndpoint`
+- [Swagger/OpenAPI](https://swagger.io/) autodocumentation
+- Works with asyncio, Trio, and Curio
+
+[![Tests Status](https://github.com/klen/muffin-rest/workflows/tests/badge.svg)](https://github.com/klen/muffin-rest/actions)
+[![PyPI Version](https://img.shields.io/pypi/v/muffin-rest)](https://pypi.org/project/muffin-rest/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/muffin-rest)](https://pypi.org/project/muffin-rest/)
+
+## Requirements
+
+- Python >= 3.10
+- Trio requires Peewee backend
+
+## Installation
+
+Install core package:
+
+```bash
+pip install muffin-rest
+```
+
+Add optional backend support:
+
+- SQLAlchemy Core: `pip install muffin-rest[sqlalchemy]`
+- Peewee ORM: `pip install muffin-rest[peewee]`
+- YAML support for Swagger: `pip install muffin-rest[yaml]`
+
+## Quickstart (Peewee example)
+
+```python
+from muffin import Application
+from muffin_rest import API
+from muffin_rest.peewee import PeeweeEndpoint
+from models import User  # your Peewee model
+
+app = Application("myapp")
+api = API(title="User Service", version="1.0")
+
+@api.route
+class UsersEndpoint(PeeweeEndpoint):
+    class Meta:
+        model = User
+        lookup_field = "id"
+        filters = ["name", "email"]
+        ordering = ["-created_at"]
+
+api.setup(app, prefix="/api", swagger=True)
+```
+
+Endpoints available:
+
+- `GET    /api/users/` — list with pagination, search, filtering
+- `POST   /api/users/` — create
+- `GET    /api/users/{id}/` — retrieve
+- `PUT    /api/users/{id}/` — replace
+- `PATCH  /api/users/{id}/` — update
+- `DELETE /api/users/{id}/` — remove
+- Docs: `/api/docs/`, OpenAPI spec: `/api/openapi.json`
+
+## Usage with SQLAlchemy
+
+```python
+from muffin_rest import API
+from muffin_rest.sqlalchemy import SAEndpoint
+from models import my_table, db_engine
+
+api = API()
+@api.route
+class MySAEndpoint(SAEndpoint):
+    class Meta:
+        table = my_table
+        database = db_engine
+
+api.setup(app)
+```
+
+## Usage with MongoDB
+
+```python
+from muffin_rest import API
+from muffin_rest.mongo import MongoEndpoint
+from models import mongo_collection
+
+api = API()
+@api.route
+class MyMongoEndpoint(MongoEndpoint):
+    class Meta:
+        collection = mongo_collection
+
+api.setup(app)
+```
+
+## Advanced Configuration
+
+Customize Swagger and routes via constructor:
+
+```python
+api = API(
+    title="Service API",
+    version="2.1",
+    swagger_ui=True,
+    openapi_path="/api/openapi.json",
+    docs_path="/api/docs/"
+)
+```
+
+## Contributing & Examples
+
+- See `examples/` for live application demos
+- Tests in `tests/` focus on filtering, pagination, status codes
+- Check `CHANGELOG.md` for latest changes
+
+## Bug Tracker
+
+Report bugs or request features:
+https://github.com/klen/muffin-rest/issues
+
+## Contributing
+
+Repo: https://github.com/klen/muffin-rest
+Pull requests, example additions, docs improvements welcome!
+
+## Contributors
+
+- [klen](https://github.com/klen) (Kirill Klenov)
+
+## License
+
+Licensed under the [MIT license](http://opensource.org/licenses/MIT).

{muffin_rest-11.0.1 → muffin_rest-12.0.1}/muffin_rest/api.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import dataclasses as dc
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, Optional, Union, overload
+from typing import TYPE_CHECKING, Any, Callable, overload
 
 from http_router import Router
 from muffin.utils import TV, to_awaitable
@@ -27,11 +27,11 @@ class API:
 
     def __init__(
         self,
-        app: Optional[muffin.Application] = None,
+        app: muffin.Application | None = None,
         prefix: str = "",
         *,
         openapi: bool = True,
-        servers: Optional[list] = None,
+        servers: list | None = None,
         **openapi_info,
     ):
         """Post initialize the API if we have an application already."""
@@ -66,8 +66,8 @@ class API:
         app: muffin.Application,
         *,
         prefix: str = "",
-        openapi: Optional[bool] = None,
-        servers: Optional[list] = None,
+        openapi: bool | None = None,
+        servers: list | None = None,
         **openapi_info,
     ):
         """Initialize the API."""
@@ -100,16 +100,12 @@ class API:
         self.router.route("/openapi.json")(openapi_json)
 
     @overload
-    def route(self, obj: str, *paths: str, **params) -> Callable[[TV], TV]:
-        ...
+    def route(self, obj: str, *paths: str, **params) -> Callable[[TV], TV]: ...
 
     @overload
-    def route(self, obj: TVHandler, *paths: str, **params) -> TVHandler:
-        ...
+    def route(self, obj: TVHandler, *paths: str, **params) -> TVHandler: ...
 
-    def route(
-        self, obj: Union[str, TVHandler], *paths: str, **params
-    ) -> Union[Callable[[TV], TV], TVHandler]:
+    def route(self, obj: str | TVHandler, *paths: str, **params) -> Callable[[TV], TV] | TVHandler:
         """Route an endpoint by the API."""
         from .handler import RESTBase
 

{muffin_rest-11.0.1 → muffin_rest-12.0.1}/muffin_rest/errors.py

@@ -1,9 +1,10 @@
 """Helpers to raise API errors as JSON responses."""
+
 from __future__ import annotations
 
 import json
 from http import HTTPStatus
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING
 
 from muffin import ResponseError
 
@@ -16,7 +17,7 @@ class APIError(ResponseError):
 
     def __init__(
         self,
-        content: Optional[TJSON] = None,
+        content: TJSON | None = None,
         *,
         status_code: int = HTTPStatus.BAD_REQUEST.value,
         **json_data,

{muffin_rest-11.0.1 → muffin_rest-12.0.1}/muffin_rest/filters.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import operator
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Iterable, Mapping, Optional  # py39
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Iterable, Mapping
 
 import marshmallow as ma
 from asgi_tools._compat import json_loads
@@ -59,8 +59,8 @@ class Filter(Mutate):
         name: str,
         *,
         field: Any = None,
-        schema_field: Optional[ma.fields.Field] = None,
-        operator: Optional[str] = None,
+        schema_field: ma.fields.Field | None = None,
+        operator: str | None = None,
         **meta,
     ):
         """Initialize filter.
@@ -75,7 +75,7 @@ class Filter(Mutate):
         self.schema_field = schema_field or self.schema_field
         self.default_operator = operator or self.default_operator
 
-    async def apply(self, collection: Any, data: Optional[Mapping] = None):
+    async def apply(self, collection: Any, data: Mapping | None = None):
         """Filter given collection."""
         if not data:
             return None, collection

{muffin_rest-11.0.1 → muffin_rest-12.0.1}/muffin_rest/handler.py

@@ -9,9 +9,7 @@ from typing import (
     Iterable,
     Literal,
     Mapping,
-    Optional,
     Sequence,
-    Union,
     cast,
     overload,
 )
@@ -31,7 +29,7 @@ from muffin_rest.types import TSchemaRes
 
 from .errors import HandlerNotBindedError
 from .options import RESTOptions
-from .types import TVCollection, TVData, TVResource
+from .types import TVCollection, TVResource
 
 
 class RESTHandlerMeta(HandlerMeta):
@@ -39,7 +37,7 @@ class RESTHandlerMeta(HandlerMeta):
 
     def __new__(mcs, name, bases, params):
         """Prepare options for the handler."""
-        kls = cast(type["RESTBase"], super().__new__(mcs, name, bases, params))
+        kls = cast("type[RESTBase]", super().__new__(mcs, name, bases, params))
         kls.meta = kls.meta_class(kls)
 
         if getattr(kls.meta, kls.meta_class.base_property, None) is not None:
@@ -58,22 +56,22 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
 
     meta: RESTOptions
     meta_class: type[RESTOptions] = RESTOptions
-    _api: Optional[API] = None
+    _api: API | None = None
 
-    filters: Optional[dict[str, Any]] = None
-    sorting: Optional[dict[str, Any]] = None
+    filters: dict[str, Any] | None = None
+    sorting: dict[str, Any] | None = None
 
     class Meta:
         """Tune the handler."""
 
         # Resource filters
-        filters: Sequence[Union[str, tuple[str, str], Filter]] = ()
+        filters: Sequence[str | tuple[str, str] | Filter] = ()
 
         # Define allowed resource sorting params
-        sorting: Sequence[Union[str, tuple[str, dict], Sort]] = ()
+        sorting: Sequence[str | tuple[str, dict] | Sort] = ()
 
         # Serialize/Deserialize Schema class
-        Schema: Optional[type[ma.Schema]] = None
+        Schema: type[ma.Schema] | None = None
 
     @classmethod
     def __route__(cls, router, *paths, **params):
@@ -84,9 +82,7 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
 
         else:
             router.bind(cls, f"/{ cls.meta.name }", methods=methods, **params)
-            router.bind(
-                cls, f"/{ cls.meta.name }/{{{ cls.meta.name_id }}}", methods=methods, **params
-            )
+            router.bind(cls, f"/{ cls.meta.name }/{{pk}}", methods=methods, **params)
 
         for _, method in inspect.getmembers(cls, lambda m: hasattr(m, "__route__")):
             paths, methods = method.__route__
@@ -94,7 +90,7 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
 
         return cls
 
-    async def __call__(self, request: Request, *, method_name: Optional[str] = None, **_) -> Any:
+    async def __call__(self, request: Request, *, method_name: str | None = None, **_) -> Any:
         """Dispatch the given request by HTTP method."""
         self.auth = await self.authorize(request)
 
@@ -151,7 +147,7 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
 
     async def prepare_resource(self, request: Request) -> Any:
         """Load a resource."""
-        return request["path_params"].get(self.meta.name_id)
+        return request["path_params"].get("pk")
 
     async def filter(self, request: Request, collection: TVCollection) -> tuple[TVCollection, Any]:
         """Filter the collection."""
@@ -190,7 +186,7 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
     @abc.abstractmethod
     async def paginate(
         self, request: Request, *, limit: int = 0, offset: int = 0
-    ) -> tuple[Any, Optional[int]]:
+    ) -> tuple[Any, int | None]:
         """Paginate the results."""
         raise NotImplementedError
 
@@ -215,7 +211,7 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
     # Parse data
     # -----------
     def get_schema(
-        self, request: Request, *, resource: Optional[TVResource] = None, **schema_options
+        self, request: Request, *, resource: TVResource | None = None, **schema_options
     ) -> ma.Schema:
         """Initialize marshmallow schema for serialization/deserialization."""
         query = request.url.query
@@ -232,34 +228,37 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
 
         return data
 
-    async def load(
-        self, request: Request, resource: Optional[TVResource] = None, **schema_options
-    ) -> TVData[TVResource]:
+    async def load(self, request: Request, resource: TVResource | None = None, **schema_options):
         """Load data from request and create/update a resource."""
         schema = self.get_schema(request, resource=resource, **schema_options)
-        data = cast(Union[Mapping, list], await self.load_data(request))
-        return cast(TVData[TVResource], await load_data(data, schema, partial=resource is not None))
+        data = cast("Mapping | list", await self.load_data(request))
+        return cast(
+            "TVResource | list[TVResource]",
+            await load_data(data, schema, partial=resource is not None),
+        )
 
     @overload
     async def dump(  # type: ignore[misc]
-        self, request, data: TVData, *, many: Literal[True]
+        self, request, data: TVResource | Iterable[TVResource], *, many: Literal[True]
     ) -> list[TSchemaRes]: ...
 
     @overload
-    async def dump(self, request, data: TVData, *, many: bool = False) -> TSchemaRes: ...
+    async def dump(
+        self, request, data: TVResource | Iterable[TVResource], *, many: bool = False
+    ) -> TSchemaRes: ...
 
     async def dump(
         self,
         request: Request,
-        data: Union[TVResource, Iterable[TVResource]],
+        data: TVResource | Iterable[TVResource],
         *,
         many: bool = False,
-    ) -> Union[TSchemaRes, list[TSchemaRes]]:
+    ) -> TSchemaRes | list[TSchemaRes]:
         """Serialize the given response."""
         schema = self.get_schema(request)
         return schema.dump(data, many=many)
 
-    async def get(self, request: Request, *, resource: Optional[TVResource] = None) -> ResponseJSON:
+    async def get(self, request: Request, *, resource: TVResource | None = None) -> ResponseJSON:
         """Get a resource or a collection of resources.
 
         Specify a path param to load a resource.
@@ -269,11 +268,9 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
             if resource
             else self.dump(request, data=self.collection, many=True)
         )
-        return ResponseJSON(res)
+        return ResponseJSON(res)  # type: ignore[type-var]
 
-    async def post(
-        self, request: Request, *, resource: Optional[TVResource] = None
-    ) -> ResponseJSON:
+    async def post(self, request: Request, *, resource: TVResource | None = None) -> ResponseJSON:
         """Create a resource.
 
         The method accepts a single resource's data or a list of resources to create.
@@ -283,19 +280,19 @@ class RESTBase(Generic[TVResource], Handler, metaclass=RESTHandlerMeta):
         if many:
             data = await self.save_many(request, data, update=resource is not None)
         else:
-            data = await self.save(request, cast(TVResource, data), update=resource is not None)
+            data = await self.save(request, cast("TVResource", data), update=resource is not None)
 
         res = await self.dump(request, data, many=many)
         return ResponseJSON(res)
 
-    async def put(self, request: Request, *, resource: Optional[TVResource] = None) -> ResponseJSON:
+    async def put(self, request: Request, *, resource: TVResource | None = None) -> ResponseJSON:
         """Update a resource."""
         if resource is None:
             raise APIError.NOT_FOUND()
 
         return await self.post(request, resource=resource)
 
-    async def delete(self, request: Request, resource: Optional[TVResource] = None):
+    async def delete(self, request: Request, resource: TVResource | None = None):
         """Delete a resource."""
         if resource is None:
             raise APIError.NOT_FOUND()

{muffin_rest-11.0.1 → muffin_rest-12.0.1}/muffin_rest/marshmallow.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING
 
 from marshmallow import Schema, ValidationError
 
@@ -10,7 +10,7 @@ if TYPE_CHECKING:
     from collections.abc import Mapping
 
 
-async def load_data(data: Union[Mapping, list], schema: Optional[Schema] = None, **params):
+async def load_data(data: Mapping | list, schema: Schema | None = None, **params):
     if schema is None:
         return data