Metadata-Version: 2.4
Name: muffin-rest
Version: 16.0.0
Summary: The package provides enhanced support for writing REST APIs with Muffin framework
Keywords: rest,api,muffin,asgi,asyncio,trio
Author: Kirill Klenov
Author-email: Kirill Klenov <horneds@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Framework :: AsyncIO
Classifier: Framework :: Trio
Requires-Dist: apispec>=6.8.1,<7
Requires-Dist: marshmallow>=4,<5
Requires-Dist: muffin
Requires-Dist: typing-extensions ; python_full_version < '3.13'
Requires-Dist: muffin-peewee-aio ; extra == 'peewee'
Requires-Dist: marshmallow-peewee ; extra == 'peewee'
Requires-Dist: muffin-databases ; extra == 'sqlalchemy'
Requires-Dist: marshmallow-sqlalchemy ; extra == 'sqlalchemy'
Requires-Dist: sqlalchemy ; extra == 'sqlalchemy'
Requires-Dist: pyyaml ; extra == 'yaml'
Requires-Python: >=3.11, <4
Project-URL: Homepage, https://github.com/klen/muffin-rest
Project-URL: Documentation, https://klen.github.io/muffin-rest/
Project-URL: Repository, https://github.com/klen/muffin-rest
Provides-Extra: peewee
Provides-Extra: sqlalchemy
Provides-Extra: yaml
Description-Content-Type: text/markdown

# Muffin-REST

Muffin-REST turns Muffin handlers into REST resources. Describe a model or table
in a handler's `Meta` and the handler serves list and detail endpoints with
filtering, sorting, pagination, and an OpenAPI spec generated from the code.
Peewee, SQLAlchemy Core, and MongoDB backends share the same handler API, so
changing storage does not change your routes.

[Read the documentation](https://klen.github.io/muffin-rest/) for the tutorial,
handler lifecycle, backends, querying, schemas, and OpenAPI.

[![Documentation](https://img.shields.io/badge/docs-read%20online-blue)](https://klen.github.io/muffin-rest/)
[![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/)

## Install

Python >= 3.11 and a Muffin application.

```bash
pip install muffin-rest                # core
pip install "muffin-rest[peewee]"      # Peewee ORM
pip install "muffin-rest[sqlalchemy]"  # SQLAlchemy Core
pip install "muffin-rest[yaml]"        # YAML docstrings for the OpenAPI spec
```

The Mongo backend needs `muffin-mongo`; it is not an extra of this package.

## Quickstart

```python
from muffin import Application
from muffin_rest import API
from muffin_rest.peewee import PWRESTHandler

from models import User

app = Application("myapp")
api = API(title="User Service", version="1.0")


@api.route
class Users(PWRESTHandler):
    class Meta:
        model = User
        filters = "name", "email"
        sorting = "name", ("created_at", {"default": "desc"})
        limit = 20


api.setup(app, prefix="/api")
```

`api.route` without a path derives the URLs from `Meta.name`, which defaults to
the model's table name:

| Method   | Path             | Action                                |
| -------- | ---------------- | ------------------------------------- |
| `GET`    | `/api/user`      | list, with filter/sort/pagination     |
| `POST`   | `/api/user`      | create one resource or a list of them |
| `GET`    | `/api/user/{id}` | retrieve                              |
| `PUT`    | `/api/user/{id}` | update                                |
| `DELETE` | `/api/user/{id}` | delete                                |

Create returns `200` with the serialized resource. Delete returns `200` too, with
the deleted id or ids for Peewee, and `null` for SQLAlchemy and Mongo. Handlers
answer `405` for methods outside `get`, `post`, `put`, `delete` unless you add
them to `methods`.

## Backends

```python
from muffin_rest.sqlalchemy import SARESTHandler

@api.route
class Pets(SARESTHandler):
    class Meta:
        table = pet_table
        database = db
```

```python
from muffin_rest.mongo import MongoRESTHandler

@api.route
class Pets(MongoRESTHandler):
    class Meta:
        collection = mongo_collection
        limit = 20
        aggregate = [{"$match": {"status": "available"}}]  # used with pagination
```

The Peewee handler needs a `peewee_aio` model with a manager, or an explicit
`Meta.manager`. Composite primary keys are supported; the route id joins the key
columns with `::`. The Mongo handler needs `muffin-mongo`.

## Documentation

The README covers the shape of the library. The guides explain the parts that
need more than a snippet:

| Guide | What it answers |
| ----- | --------------- |
| [Tutorial](https://klen.github.io/muffin-rest/tutorial/) | Build and run a small API from scratch |
| [Handlers and lifecycle](https://klen.github.io/muffin-rest/handlers/) | What runs on each request, and which hook to override |
| [Backends](https://klen.github.io/muffin-rest/backends/) | Peewee, SQLAlchemy, and Mongo options and differences |
| [Writing a backend](https://klen.github.io/muffin-rest/custom-backend/) | Add support for another storage system |
| [Querying](https://klen.github.io/muffin-rest/querying/) | `where`, `sort`, pagination, field selection |
| [Schemas](https://klen.github.io/muffin-rest/schemas/) | Generated schemas, validation, custom fields |
| [OpenAPI](https://klen.github.io/muffin-rest/openapi/) | Spec generation, docstrings, auth, response types |
| [Errors](https://klen.github.io/muffin-rest/errors/) | `APIError`, validation errors, status codes |
| [Cookbook](https://klen.github.io/muffin-rest/cookbook/) | Auth, scoping, soft delete, custom filters and routes |
| [API reference](https://klen.github.io/muffin-rest/reference/) | Public classes, options, and hook signatures |
| [Development](https://klen.github.io/muffin-rest/development/) | Tests, linting, examples, release |

Start with the [documentation home](https://klen.github.io/muffin-rest/)
if you are browsing the repository.

## Development

```bash
uv sync                 # install dependencies
uv run pytest           # run tests
make lint               # pyrefly + ruff
make docs               # build the documentation
make docs-serve         # preview it locally
```

Mongo tests need Docker with a container named `mongo` (`docker start mongo`).
Examples run against SQLite:

```bash
uv run uvicorn examples.peewee_orm:app --reload --port=5000
uv run uvicorn examples.sqlalchemy_core:app --reload --port=5000
```

See [Development](https://klen.github.io/muffin-rest/development/)
for the full workflow.

## Bug tracker and contributing

Issues and pull requests: https://github.com/klen/muffin-rest

## Contributors

- [klen](https://github.com/klen) (Kirill Klenov)

## License

MIT. See [LICENSE](LICENSE).
