README.md

Flask-Muck

With Flask-Muck you don't have to worry about the CRUD.

Flask-Muck is a declarative framework for automatically generating RESTful APIs with Create, Read, Update and Delete (CRUD) endpoints in a Flask, SqlAlchemy, Marshmallow/Pydantic application stack in as little as 9 lines of code. Below is example code you might find in a Flask app. Please see the docs for full working examples

from flask import Blueprint, Flask
from flask_muck import FlaskMuckApiView, FlaskMuck
import marshmallow as ma
from marshmallow import fields as mf

from myapp import db


class MyModel(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String, nullable=False)


class MyModelSchema(ma.Schema):
    id = mf.Integer(dump_only=True)
    name = mf.String()


class MyModelApiView(FlaskMuckApiView):
    api_name = "my-model"
    session = db.session
    Model = MyModel
    ResponseSchema = MyModelSchema
    CreateSchema = MyModelSchema
    PatchSchema = MyModelSchema
    UpdateSchema = MyModelSchema
    searchable_columns = [MyModel.name]


app = Flask(__name__)

# Initialize the FlaskMuck extension if you want all batteries included. 
# Using the extension will autogenerate a Swagger UI browsable api documentation at /apidocs/
app.config['MUCK_API_URL_PREFIX'] = "/api/"
muck = FlaskMuck()
muck.init_app(app)
muck.register_muck_views([MyModelApiView])

# OR add CRUD views to an existing Flask Blueprint for greater flexibility
blueprint = Blueprint("api", __name__, url_prefix="/api/")
MyModelApiView.add_rules_to_blueprint(blueprint)


# Either option generates the following endpoints:
# CREATE             | curl -X POST "/api/v1/my-model" -H "Content-Type: application/json" \-d "{\"name\": \"Ayla\"}"
# LIST ALL           | curl -X GET "/api/v1/my-model" -d "Accept: application/json"
# LIST ALL PAGINATED | curl -X GET "/api/v1/my-model?limit=100&offset=50" -d "Accept: application/json"
# SEARCH             | curl -X GET "/api/v1/my-model?search=ayla" -d "Accept: application/json"
# FILTER             | curl -X GET "/api/v1/my-model?filter={\"name\": \"Ayla\"}" -d "Accept: application/json"
# SORT               | curl -X GET "/api/v1/my-model?sort=name" -d "Accept: application/json"
# FETCH              | curl -X GET "/api/v1/my-model/1" -d "Accept: application/json"
# UPDATE             | curl -X PUT "/api/v1/my-model" -H "Content-Type: application/json" \-d "{\"name\": \"Ayla\"}"
# PATCH              | curl -X PATCH "/api/v1/my-model" -H "Content-Type: application/json" \-d "{\"name\": \"Ayla\"}"
# DELETE             | curl -X DELETE "/api/v1/my-model/1"

Features

• Uses a declarative and modular approach to automatically generate CRUD endpoints.
• Built-in search, filter, sort and pagination when listing resources.
• Support for APIs with nested resources (i.e. /api/classrooms/12345/students).
• Fully compatible with any other Flask method-based or class-based views. Mix & match with your existing views.
• Pre and post callbacks configurable on all manipulation endpoints. Allow for adding arbitrary logic before and after Create, Update or Delete operations.
• Supports Marshmallow and Pydantic for schema definitions.
• Dynamically generates OpenAPI specification and Swagger UI.

Documentation

Please visit the docs at https://dtiesling.github.io/flask-muck/ for explanation of all features and advanced usage guides.

There are also examples of complete Flask apps using Flask-Muck in the examples directory.

Install

Flask-Muck is in Beta and does not have a standard version available for install yet. A standard release on PyPi is coming soon.

pip install flask-muck

Flask-Muck supports Python >= 3.9

Bug Reports

Submit any issues you may encounter as a GitHub issue. Please search for similar issues before submitting a new one.

Questions, Concerns, Ideas, Support, Feature Requests

All non-bug-related discussions such as support or feature requests should be submitted as a GitHub Discussion.

License

MIT licensed. See the LICENSE file for more details.

Contributing

This project follows the all-contributors specification. Contributions of any kind welcome!

Development Environment

The development environment is simple and straightforward. Dependencies are managed by Poetry and tests are run with pytest. If you would like to test any changes against a live server you can use any apps in the /examples directory.

Prerequisites:

• Python >= 3.9
• Poetry

Install dependencies.

poetry install

Run tests.

poetry run pytest

Code Style

• Code is formatted using black.
• Typing is enforced with mypy.

How should I write my commits?

This project uses release please and conventional commits for versioning releases.

Per release-please-action:

The most important prefixes you should have in mind are:

• `fix``: which represents bug fixes, and correlates to a SemVer patch.
• `feat``: which represents a new feature, and correlates to a SemVer minor.
• `feat!``:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.

Any PR with fix, feat, docs, or a conventional commit with an ! will trigger a release PR when merged.

Other conventional commits such as chore, ci, test, refactor, etc will not trigger a release but are encouraged to form a standard around conventional commits in the commit history.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

atkins 📖

Mason Cole 🚇

Support

Thanks for the stars! They mean nothing but bring me immense satisfaction. Keep 'em coming.