{"id":16671536,"url":"https://github.com/ocervell/flask-flash","last_synced_at":"2025-04-09T19:42:56.298Z","repository":{"id":57430330,"uuid":"94793149","full_name":"ocervell/flask-flash","owner":"ocervell","description":"Flask API Framework to quickly create model-driven CRUD APIs.","archived":false,"fork":false,"pushed_at":"2020-11-07T15:21:49.000Z","size":138,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-20T07:38:16.449Z","etag":null,"topics":["crud","flask-api","flask-flash"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ocervell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-19T15:38:52.000Z","updated_at":"2025-02-21T15:49:29.000Z","dependencies_parsed_at":"2022-08-26T04:43:33.683Z","dependency_job_id":null,"html_url":"https://github.com/ocervell/flask-flash","commit_stats":null,"previous_names":["ocervell/flask_flash"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocervell%2Fflask-flash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocervell%2Fflask-flash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocervell%2Fflask-flash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ocervell%2Fflask-flash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ocervell","download_url":"https://codeload.github.com/ocervell/flask-flash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248101285,"owners_count":21047948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crud","flask-api","flask-flash"],"created_at":"2024-10-12T11:44:46.904Z","updated_at":"2025-04-09T19:42:56.279Z","avatar_url":"https://github.com/ocervell.png","language":"Python","readme":"\nFlask-Flash\n-----------\n**Flask-Flash** provides simple generation of database-driven RESTful APIs.\n\nA **Flash API** can be generated with minimal configuration allowing for quick API development.\n\nResources following the **CRUD** ***(Create, Read, Update, Delete)*** model are made very easy.\n\n\nDescription\n-----------\n**Flask-Flash** makes some assumptions about what an API should have in order to be rock-solid and production-ready, but will give you the ability to customize it to your own needs.\n\nIt provides both an API and the Python client to query it:\n\n#### Flash API\n- Integrates well with an existing `flask.Flask` application object\n- Automatic registration (and routing) of resources\n- Automatic resource caching for `GET` requests (to reduce database load)\n- Provides `flask_flash.Protected` mixin with:\n\t- Basic Authentication using `Flask-HTTPAuth`\n\t- Custom authentication forwarding\n\t- Custom permission control on every method\n- Provides `flask_flash.CRUD` mixin with:\n\t- Implements HTTP methods: `HEAD`, `GET`, `PUT`, `POST`, `DELETE`\n\t- Automatic model serialization, deserialization and parameter validation using `Flask-Marshmallow`\n\t- Resource filtering and sorting, and pagination using `db.query` object\n\n\n#### Flash API Client\n- Authentication and token handling\n- Easy resource querying, filtering, sorting, controlling pagination and caching\n- Provides `flask_flash.CRUDEndpoint`  with basic CRUD methods: `count`, `create`, `get`, `update`, `delete`\n- Configurable retries on common HTTP status codes\n- Extensible\n\nQuickstart\n-----------\n\nIn the following we will create a CRUD (Create, Read, Update, Delete) API\naround our `User` model.\n\nThe following example code is accessible from the `examples/app1` folder.\n\n### Install Flask-Flash\n\n```pip install Flask-Flash```\n\n\n### Create a CRUD API\n\nCreate an `app` folder with the following structure:\n\n`app/models.py` - *Definition of SQLAlchemy models and Marshmallow schemas.*\n\n```\nfrom flask_flash import db, ma\n\nclass UserModel(db.Model):\n    id = db.Column(db.Integer, primary_key=True)\n    username = db.Column(db.String(32))\n    password = db.Column(db.String(32))\n\nclass UserSchema(ma.ModelSchema):\n    class Meta:\n        model = UserModel # link schema with model\n    username = ma.Field(required=True)\n    password = ma.Field(required=True)\n```\n\n`app/resources.py` - *Definition of API resources.*\n```\nfrom flask_flash import CRUD\nfrom models import UserModel, UserSchema\n\nclass User(CRUD):\n    model = UserModel\n    schema = UserSchema\n```\n\n`app/manage.py` - *Basic initialization of our `Flash` app*\n\n```\n#!/usr/bin/env python\nfrom flask_flash import Flash\nfrom resources import User\n\nflash = Flash([User])\n\nif __name__ == '__main__':\n    flash.manager.run()\n```\n\n### Run your API\n\n```\n./manage.py runserver --threaded -d -r\nServer running on localhost:5001\n```\n***API Check:***\n\n`curl localhost:5001/api`\n\nThe above command should return a `HTTP 200 OK` and `{}` as content.\n\n### Query your API\n\nHere are the most common URL parameters to apply on `CRUD` resources:\n - **Filter** on db columns using `\u003ckey\u003e=\u003cvalue\u003e` (*str*, *str*/*csv-list*\\*) params.\n - **Filter** on db columns using `match` (*list*)\n - **Pagination** using `paginate` (*bool*), `per_page` (*int*) and `page` (*int*).\n - **Caching** on/off using `cache` (*bool*)\n - **Sorting** results using `order_by=\u003ckey\u003e` and `sort` (*string*, 'asc' or 'desc')\n - **Limit** the number of results using `limit` (*int*)\n - **Include / Exclude** what field shows up in results by using `include` (*csv-list*) and `exclude` (*csv-list*)\n\n\\**csv-list*: Syntax for lists like `key=x1,x2,x3` are preferred over syntax `key=x1\u0026key=x2\u0026key=x3` or `key=[x1,x2,x3]` for simplicity of query.\n\n***Create users:***\n\n```\ncurl -X POST localhost:5001/api/users \\\n-H \"Content-Type:application/json\" \\\n-d [{'username': 'John', 'password': '@kj!4la'}, {'username': 'Xiang', 'password': 'lu1Z3k'}]\n```\n***Get user with*** `id == 1`:\n\n`curl localhost:5001/api/user/1`\n\n***Get users with*** `id == 1 OR id == 2 OR id == 3`:\n\n`curl localhost:5001/api/users?id=1,2,3`\n\n***Get all users with*** `password == @kj!4la`:\n  ```\n curl localhost:5001/api/users? \\\n \t\u0026password=@kj!4la \\\n    \u0026paginate=false \\    \n ```\n\n ***Get all users with*** `username \u003e= John AND 1 \u003c= id \u003c= 5`.\n ***Include only*** `id` ***and*** `username` fields in response\n ```\n curl localhost:5001/api/users?\\\n \t\u0026match=[[ username, \u003e=, John ], [ id, between, [1, 5] ]] \\\n    \u0026order_by=username \\\n    \u0026sort=asc \\\n    \u0026include=id,username,password \\\n    \u0026paginate=false   \n ```\n\n ***Disable cache to get most recent results***\n ```\n curl localhost:5001/api/users?cache=false\n ```\n\nFlask-Flash API Client (Python)\n-----------\n\nThe positive side of having a client as part of the API framework means that\nwe are done with running most common db queries from our shell and can use a high level Python client instead.\n\nHere is an example how to use the **Flask-Flash** client:\n\n```\nfrom flask_flash import BaseClient, CRUDEndpoint  \nc = BaseClient('localhost:5001')\nc.register(CRUDEndpoint, '/user', '/users')  # register endpoint\nc.users.create(username='John', password='@kj!4la') # create user\nc.users.get()  \t\t\t\t\t\t # get first 20 users\nc.users.get(1) \t\t\t\t\t\t # get user 1\nc.users.update(1, username='Johnny') # update username for user 1\n```\n\nThe `CRUDEndpoint` allows to use the following `CRUD` features:\n\n### Queries\nYou can use `match` argument (only for `CRUD` resources) to use for `CRUDEndpoint.get` and `CRUDEndpoint.count` methods to\n```\nq = [\n\t  ['name', 'startswith', 'John'],\n      ['id', 'between', [1, 5] ],\n]\nc.users.get(match=q)\n```\nNote: All the [sqlalchemy operators](https://github.com/zzzeek/sqlalchemy/blob/master/lib/sqlalchemy/sql/operators.py) are supported for `match` syntax.\n\n\n### Sorting\n\nSorting is enabled by default on the `db.Model` primary key (if defined) in ascending order.\n\nSort by any key in the model using `order_by`, and organize by ascending or descending order by setting `sort` to `'asc'` or `'desc'`.\n```\nc.users.get(order_by='username', sort='asc')\n```\n\n### Pagination\nPagination is enabled by default.\nThe default number of records per page is 20.\n\nAlthough it's generally not advised to disable pagination (requests might timeout), it can still be done in `Flask-Flash`, either for the client as a whole:\n```\nc = BaseClient('localhost:5001', paginate=False)\n```\n... or per request:\n```\nc.users.get(paginate=False)  # get all users\n```\n\nThe number of records per page and the page to query are controlled using `per_page` and `page` argument.\n```\nc.users.get(page=1, per_page=100) # get the 100 first results\n```\n\n### Extending the API Client\nInstead of adding the endpoints using `register` like above, Flask-Flash API client can be modified to add your own endpoints (and functions !).\n\nThis is done by subclassing `BaseClient`:\n```\nclass MyClient(BaseClient):\n    @property\n    def users(self):\n    \treturn CRUDEndpoint(self, '/user', '/users')\n\n    @property\n    def get_user_count(self):\n    \treturn self.users.count(paginate=False)\n\nc = MyClient('localhost:5001')\nc.users.create(username='John', password='@%$kjn')\nnusers = c.get_user_count(self)\n```\n\nOf course, every `CRUDEndpoint` can also have other methods than the default `get`, `create`, `update`, `delete`.\n\nTheir implementation is up to you, here is an example for a `delete_all` function:\n```\nclass UserEndpoint(CRUDEndpoint):\n    def delete_all():\n      \tusers = self.get(paginate=False)\n        ids = [u['id'] for u in users]\n        return self.delete(ids)\n\nclass MyClient(BaseClient):\n    @property\n    def users(self):\n    \t  return UserEndpoint(self, '/user', '/users')\n```\nAnd in a script, call:\n```\nc = MyClient('localhost:5001')\nc.users.delete_all()\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focervell%2Fflask-flash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Focervell%2Fflask-flash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Focervell%2Fflask-flash/lists"}