# FastAPI CRUDBuilder
Designed for use with FastAPI to build a router for CRUD operations on a SQLAlchemy
model. It automates the creation of API endpoints for these operations, making it
easier to set up a RESTful API.
Endpoints are created for the following operations:
- Read all items
- Read one item by primary key
- Create one item
- Update one item by primary key
- Delete all items
- Delete one item by primary key
Endpoints created by CRUDBuilder are designed to support the OpenAPI documentation that FastAPI automatically generates.
Optionally, you can add security, caching and custom postprocessors to the generated endpoints. They're designed to attach to
an existing `APIRouter` object in FastAPI, or alternatively can be used to create a new router.
---
**Documentation**: (This file) <a href="https://github.com/TetricusLabs/fastapi_crudbuilder" target="_blank">https://github.com/TetricusLabs/crudbuilder</a>
**Source Code**: <a href="https://github.com/TetricusLabs/fastapi_crudbuilder" target="_blank">https://github.com/TetricusLabs/crudbuilder</a>
---
## Pre-requisites
- Python 3.10+
- FastAPI
- SQLAlchemy
- [optional] Memcached (pymemcached client)
## Features
- Automatically generate CRUD endpoints for a given SQLAlchemy model
- Automatically generate OpenAPI documentation for the generated endpoints
- Optionally add security to the generated endpoints
- Optionally add caching to the generated endpoints
- Optionally add postprocessors to the generated endpoints
- Optionally infer the create and update models from the SQLAlchemy model, or provide custom Pydantic models
- Designed to be used with FastAPI
- Extendable to support other ORMs and caches
## Installation
```bash
poetry add fastapi_crudbuilder
```
## Usage Example
```python
from fastapi import APIRouter, Security
from fastapi_crudbuilder import CRUDBuilder
from src.postprocessors import YOUR_POSTPROCESSOR_1, YOUR_POSTPROCESSOR_2
from src.database import YOUR_DB_SESSION
from src.database.models import YOUR_MODEL
from src.security import YOUR_SECURITY_FUNCTION
example = APIRouter(prefix="/example", tags=["Example CRUD"]) # set up a FastAPI router to attach the CRUD endpoints to
@example.get("custom_non_crudbldr_route")
def custom_route():
return {"message": "Hello World"}
example = CRUDBuilder(
db_model=YOUR_MODEL,
db_func=YOUR_DB_SESSION,
infer_create=True, # Optionally infer the create model
infer_update=True, # Optionally infer the update model
read_security=Security(YOUR_SECURITY_FUNCTION.verify, scopes=["YOUR_MODEL:all:read"]),
# Optionally add custom security function and scope to the endpoint
create_security=Security(YOUR_SECURITY_FUNCTION.verify, scopes=["YOUR_MODEL:all:create"]),
update_security=Security(YOUR_SECURITY_FUNCTION.verify, scopes=["YOUR_MODEL:all:update"]),
delete_security=Security(YOUR_SECURITY_FUNCTION.verify, scopes=["YOUR_MODEL:all:delete"]),
response_postprocessors=[YOUR_POSTPROCESSOR_1(YOUR_MODEL), YOUR_POSTPROCESSOR_2(YOUR_MODEL)],
).build(example) # Attach the CRUD endpoints to the router
```
The router **must** then be added to the FastAPI app (like any other router) in order to be used.
```python
from fastapi import FastAPI
from src.routes.example import example
app = FastAPI()
app.include_router(example)
```
## Required parameters
- db_model: The SqlAlchemy model you want to create CRUD endpoints for
- db_func: The function that returns the SqlAlchemy session you'd like to use
## Optional extensions
### Infer Create/Update
This will infer the model for the create and update endpoints from the SqlAlchemy model. Otherwise, you can pass in a
custom Pydantic model for the data to be validated against. This will also be reflected in the automatically generated OpenAPI documentation.
### Security
You can pass in a FastAPI Security object to the CRUDBuilder class for each operation type (read, create, update, delete).
### Postprocessors
Post Processors are passed into the CRUDBuilder class as a list of functions that take the model as an argument and
return a function that takes the response as an argument and returns a modified version of the response.
These are processed **in order** (e.g. in the example above `YOUR_POSTPROCESSOR_1` would be applied to
the database result first, then `YOUR_POSTPROCESSOR_2` etc.)
Post Processors are expected to receive a passed-in data model and return a callable that takes the response data and modifies it.
This allows you to adjust the response of the CRUD endpoints -- for example if you store dates in your Database as UTC
but want to render them to users in their local time or a different format. See example below:
```python
def transform_response_date(db_model: BaseModel) -> Callable:
def transform_dates(data: db_model.__class__, db_model: DeclarativeMeta = db_model):
columns = inspect(db_model).columns.items()
for name, column in columns:
if column.type.python_type.__name__ in (
"datetime",
"date",
"datetime.datetime",
):
_LOGGER.info(f"Transforming {name} to ISO 8601 date format.")
if getattr(data, name):
setattr(
data, name, convert_iso_datetime_format(getattr(data, name))
)
return data
return transform_dates
```
### Caching
You can optionally pass a cache object to the CRUDBuilder class. Right now only Memcached is supported, and only the pymemcached client
has been tested. See https://pymemcache.readthedocs.io/en/latest/getting_started.html for more information on how to set up a pymemcached client.
In theory any client with the methods:
- get
- set
- delete
- delete_many
should work, but this has not been tested.
## Supported ORMS/ Caches
(Only SqlAlchemy and Memcached are supported for now)
- SqlAlchemy
- Memcached (pymemcached client)
## Calling endpoints:
GET /yourmodel
Get all items for your model
Query params:
limit: Number of items to return
skip: Number of items to skip
sort_field: Name of field to sort by, defaults to the primary key
sort_desc: True to sort descending, False for ascending
equals_field: Name of field to filter to a value, paired with equals_value
equals_value: Value of equals_field to filter by
relationships: Comma-separated names of fields that are relationships in the
SQLAlchemy model
GET /yourmodel/{item_id}
Get one item for your model by primary key (item_id)
Query params:
relationships: Comma-separated names of fields that are relationships in the
SQLAlchemy model
POST /yourmodel
Create one new item for your model
Request body:
JSON must match the given create_schema
PUT /yourmodel/{item_id}
Update fields for one item for your model by primary key (item_id)
Request body:
JSON must match the given update_schema
DELETE /yourmodel
Delete all contents in your model
DELETE /yourmodel/{item_id}
Delete one item for your model by primary key (item_id)
Notes:
* Ensure that the provided SQLAlchemy model and Pydantic schemas are compatible.
* The db_func should return a SQLAlchemy Session object. This will be injected
using FastAPI's Depends.
* The CRUD endpoints will reflect the attributes and relationships defined in
the SQLAlchemy model.
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
## Testing
We use pytest for testing. To run the tests, simply run `pytest` in the root directory of the project. Tests are stored in the `tests` directory.
## License
[MIT](https://choosealicense.com/licenses/mit/)
Raw data
{
"_id": null,
"home_page": "https://github.com/TetricusLabs/fastapi_crudbuilder",
"name": "fastapi_crudbuilder",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "FastAPI, CRUD, SQLAlchemy",
"author": "Tetricus Labs Team",
"author_email": "support@tetricuslabs.com",
"download_url": "https://files.pythonhosted.org/packages/b5/8f/e16dae5ec607914e867ce0321999fb9c75815725491db70d0ba74924796b/fastapi_crudbuilder-0.2.5.tar.gz",
"platform": null,
"description": "# FastAPI CRUDBuilder\nDesigned for use with FastAPI to build a router for CRUD operations on a SQLAlchemy\nmodel. It automates the creation of API endpoints for these operations, making it\neasier to set up a RESTful API.\n\nEndpoints are created for the following operations:\n- Read all items\n- Read one item by primary key\n- Create one item\n- Update one item by primary key\n- Delete all items\n- Delete one item by primary key\n\nEndpoints created by CRUDBuilder are designed to support the OpenAPI documentation that FastAPI automatically generates.\nOptionally, you can add security, caching and custom postprocessors to the generated endpoints. They're designed to attach to\nan existing `APIRouter` object in FastAPI, or alternatively can be used to create a new router.\n\n---\n\n**Documentation**: (This file) <a href=\"https://github.com/TetricusLabs/fastapi_crudbuilder\" target=\"_blank\">https://github.com/TetricusLabs/crudbuilder</a>\n\n**Source Code**: <a href=\"https://github.com/TetricusLabs/fastapi_crudbuilder\" target=\"_blank\">https://github.com/TetricusLabs/crudbuilder</a>\n\n---\n\n## Pre-requisites\n- Python 3.10+\n- FastAPI\n- SQLAlchemy\n- [optional] Memcached (pymemcached client)\n\n## Features\n- Automatically generate CRUD endpoints for a given SQLAlchemy model\n- Automatically generate OpenAPI documentation for the generated endpoints\n- Optionally add security to the generated endpoints\n- Optionally add caching to the generated endpoints\n- Optionally add postprocessors to the generated endpoints\n- Optionally infer the create and update models from the SQLAlchemy model, or provide custom Pydantic models\n- Designed to be used with FastAPI\n- Extendable to support other ORMs and caches\n\n\n\n## Installation\n```bash\npoetry add fastapi_crudbuilder\n```\n## Usage Example\n\n```python\nfrom fastapi import APIRouter, Security\n\nfrom fastapi_crudbuilder import CRUDBuilder\nfrom src.postprocessors import YOUR_POSTPROCESSOR_1, YOUR_POSTPROCESSOR_2\nfrom src.database import YOUR_DB_SESSION\nfrom src.database.models import YOUR_MODEL\nfrom src.security import YOUR_SECURITY_FUNCTION\n\nexample = APIRouter(prefix=\"/example\", tags=[\"Example CRUD\"]) # set up a FastAPI router to attach the CRUD endpoints to\n\n\n@example.get(\"custom_non_crudbldr_route\")\ndef custom_route():\n return {\"message\": \"Hello World\"}\n\n\nexample = CRUDBuilder(\n db_model=YOUR_MODEL,\n db_func=YOUR_DB_SESSION,\n infer_create=True, # Optionally infer the create model\n infer_update=True, # Optionally infer the update model\n read_security=Security(YOUR_SECURITY_FUNCTION.verify, scopes=[\"YOUR_MODEL:all:read\"]),\n # Optionally add custom security function and scope to the endpoint\n create_security=Security(YOUR_SECURITY_FUNCTION.verify, scopes=[\"YOUR_MODEL:all:create\"]),\n update_security=Security(YOUR_SECURITY_FUNCTION.verify, scopes=[\"YOUR_MODEL:all:update\"]),\n delete_security=Security(YOUR_SECURITY_FUNCTION.verify, scopes=[\"YOUR_MODEL:all:delete\"]),\n response_postprocessors=[YOUR_POSTPROCESSOR_1(YOUR_MODEL), YOUR_POSTPROCESSOR_2(YOUR_MODEL)],\n).build(example) # Attach the CRUD endpoints to the router\n\n```\nThe router **must** then be added to the FastAPI app (like any other router) in order to be used.\n```python\nfrom fastapi import FastAPI\nfrom src.routes.example import example\n\napp = FastAPI()\napp.include_router(example)\n\n```\n## Required parameters\n- db_model: The SqlAlchemy model you want to create CRUD endpoints for\n- db_func: The function that returns the SqlAlchemy session you'd like to use\n\n## Optional extensions\n\n### Infer Create/Update\nThis will infer the model for the create and update endpoints from the SqlAlchemy model. Otherwise, you can pass in a \ncustom Pydantic model for the data to be validated against. This will also be reflected in the automatically generated OpenAPI documentation.\n\n### Security\nYou can pass in a FastAPI Security object to the CRUDBuilder class for each operation type (read, create, update, delete).\n\n### Postprocessors\nPost Processors are passed into the CRUDBuilder class as a list of functions that take the model as an argument and\nreturn a function that takes the response as an argument and returns a modified version of the response. \n\nThese are processed **in order** (e.g. in the example above `YOUR_POSTPROCESSOR_1` would be applied to \nthe database result first, then `YOUR_POSTPROCESSOR_2` etc.) \n\nPost Processors are expected to receive a passed-in data model and return a callable that takes the response data and modifies it.\n\nThis allows you to adjust the response of the CRUD endpoints -- for example if you store dates in your Database as UTC\nbut want to render them to users in their local time or a different format. See example below:\n\n```python\ndef transform_response_date(db_model: BaseModel) -> Callable:\n def transform_dates(data: db_model.__class__, db_model: DeclarativeMeta = db_model):\n columns = inspect(db_model).columns.items()\n for name, column in columns:\n if column.type.python_type.__name__ in (\n \"datetime\",\n \"date\",\n \"datetime.datetime\",\n ):\n _LOGGER.info(f\"Transforming {name} to ISO 8601 date format.\")\n if getattr(data, name):\n setattr(\n data, name, convert_iso_datetime_format(getattr(data, name))\n )\n return data\n\n return transform_dates\n```\n\n\n### Caching\nYou can optionally pass a cache object to the CRUDBuilder class. Right now only Memcached is supported, and only the pymemcached client\nhas been tested. See https://pymemcache.readthedocs.io/en/latest/getting_started.html for more information on how to set up a pymemcached client.\n\nIn theory any client with the methods:\n- get\n- set\n- delete\n- delete_many \n\nshould work, but this has not been tested.\n\n\n## Supported ORMS/ Caches\n(Only SqlAlchemy and Memcached are supported for now)\n- SqlAlchemy\n- Memcached (pymemcached client)\n\n\n## Calling endpoints:\n GET /yourmodel\n Get all items for your model\n Query params:\n limit: Number of items to return\n skip: Number of items to skip\n sort_field: Name of field to sort by, defaults to the primary key\n sort_desc: True to sort descending, False for ascending\n equals_field: Name of field to filter to a value, paired with equals_value\n equals_value: Value of equals_field to filter by\n relationships: Comma-separated names of fields that are relationships in the\n SQLAlchemy model\n\n GET /yourmodel/{item_id}\n Get one item for your model by primary key (item_id)\n Query params:\n relationships: Comma-separated names of fields that are relationships in the\n SQLAlchemy model\n\n POST /yourmodel\n Create one new item for your model\n Request body:\n JSON must match the given create_schema\n\n PUT /yourmodel/{item_id}\n Update fields for one item for your model by primary key (item_id)\n Request body:\n JSON must match the given update_schema\n\n DELETE /yourmodel\n Delete all contents in your model\n\n DELETE /yourmodel/{item_id}\n Delete one item for your model by primary key (item_id)\n\n Notes:\n * Ensure that the provided SQLAlchemy model and Pydantic schemas are compatible.\n * The db_func should return a SQLAlchemy Session object. This will be injected\n using FastAPI's Depends.\n * The CRUD endpoints will reflect the attributes and relationships defined in\n the SQLAlchemy model.\n\n## Contributing\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## Testing\nWe use pytest for testing. To run the tests, simply run `pytest` in the root directory of the project. Tests are stored in the `tests` directory.\n\n## License\n[MIT](https://choosealicense.com/licenses/mit/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CRUDBuilder helps you to create CRUD endpoints for your FastAPI/ SqlAlchemy database models.",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/TetricusLabs/fastapi_crudbuilder",
"Repository": "https://github.com/TetricusLabs/fastapi_crudbuilder"
},
"split_keywords": [
"fastapi",
" crud",
" sqlalchemy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "88b17b44757dab5a7766e613b44c870f54a262f0f5f739c925c8b88433fe2042",
"md5": "fe8714ccccaa1902ce50c70bd30b8564",
"sha256": "9a4dbe1e3ff4470bd543826ac3e0042dc4957befa2973de4b27514be847a85de"
},
"downloads": -1,
"filename": "fastapi_crudbuilder-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe8714ccccaa1902ce50c70bd30b8564",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 11199,
"upload_time": "2024-06-28T16:35:11",
"upload_time_iso_8601": "2024-06-28T16:35:11.685905Z",
"url": "https://files.pythonhosted.org/packages/88/b1/7b44757dab5a7766e613b44c870f54a262f0f5f739c925c8b88433fe2042/fastapi_crudbuilder-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b58fe16dae5ec607914e867ce0321999fb9c75815725491db70d0ba74924796b",
"md5": "afe94bbc4a9e24ea16727a2006ec7676",
"sha256": "273fcc345ecb01a842307b16de0f84a8c4c661148f8696056e0fc32c6baaf4d1"
},
"downloads": -1,
"filename": "fastapi_crudbuilder-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "afe94bbc4a9e24ea16727a2006ec7676",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 11929,
"upload_time": "2024-06-28T16:35:12",
"upload_time_iso_8601": "2024-06-28T16:35:12.898960Z",
"url": "https://files.pythonhosted.org/packages/b5/8f/e16dae5ec607914e867ce0321999fb9c75815725491db70d0ba74924796b/fastapi_crudbuilder-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-28 16:35:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TetricusLabs",
"github_project": "fastapi_crudbuilder",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fastapi_crudbuilder"
}
JSON
