<p align="center">
<a href="https://mithun2003.github.io/CRUDFastAPI/">
<!-- <img src="https://github.com/mithun2003/CRUDFastAPI/blob/main/assets/CRUDFastAPI.png?raw=true" alt="CRUDFastAPI written in white with a drawing of a gear and inside this gear a bolt." width="45%" height="auto"> -->
</a>
</p>
<p align="center" markdown=1>
<i>Powerful CRUD methods and automatic endpoint creation for FastAPI.</i>
</p>
<p align="center" markdown=1>
<a href="https://github.com/mithun2003/CRUDFastAPI/actions/workflows/tests.yml">
<img src="https://github.com/mithun2003/CRUDFastAPI/actions/workflows/tests.yml/badge.svg" alt="Tests"/>
</a>
<a href="https://pypi.org/project/CRUDFastAPI/">
<img src="https://img.shields.io/pypi/v/CRUDFastAPI?color=%2334D058&label=pypi%20package" alt="PyPi Version"/>
</a>
<a href="https://pypi.org/project/CRUDFastAPI/">
<img src="https://img.shields.io/pypi/pyversions/CRUDFastAPI.svg?color=%2334D058" alt="Supported Python Versions"/>
</a>
<a href="https://codecov.io/gh/mithun2003/CRUDFastAPI" >
<img src="https://codecov.io/gh/mithun2003/CRUDFastAPI/graph/badge.svg?token=J7XUP29RKU"/>
</a>
</p>
<hr>
<p align="justify">
<b>CRUDFastAPI</b> is a Python package for <b>FastAPI</b>, offering robust async CRUD operations and flexible endpoint creation utilities, streamlined through advanced features like <b>auto-detected join</b> conditions, <b>dynamic sorting</b>, and offset and cursor <b>pagination</b>.
</p>
<hr>
<h2>Features</h2>
- ⚡️ **Fully Async**: Leverages Python's async capabilities for non-blocking database operations.
- 📚 **SQLAlchemy 2.0**: Works with the latest SQLAlchemy version for robust database interactions.
- 🦾 **Powerful CRUD Functionality**: Full suite of efficient CRUD operations with support for joins.
- ⚙️ **Dynamic Query Building**: Supports building complex queries dynamically, including filtering, sorting, and pagination.
- 🤝 **Advanced Join Operations**: Facilitates performing SQL joins with other models with automatic join condition detection.
- 📖 **Built-in Offset Pagination**: Comes with ready-to-use offset pagination.
- ➤ **Cursor-based Pagination**: Implements efficient pagination for large datasets, ideal for infinite scrolling interfaces.
- 🤸♂️ **Modular and Extensible**: Designed for easy extension and customization to fit your requirements.
- 🛣️ **Auto-generated Endpoints**: Streamlines the process of adding CRUD endpoints with custom dependencies and configurations.
<h2>Requirements</h2>
<p>Before installing CRUDFastAPI, ensure you have the following prerequisites:</p>
<ul>
<li><b>Python:</b> Version 3.9 or newer.</li>
<li><b>FastAPI:</b> CRUDFastAPI is built to work with FastAPI, so having FastAPI in your project is essential.</li>
<li><b>SQLAlchemy:</b> Version 2.0.21 or newer. CRUDFastAPI uses SQLAlchemy for database operations.</li>
<li><b>Pydantic:</b> Version 2.4.1 or newer. CRUDFastAPI leverages Pydantic models for data validation and serialization.</li>
<li><b>SQLAlchemy-Utils:</b> Optional, but recommended for additional SQLAlchemy utilities.</li>
</ul>
<h2>Installing</h2>
To install, just run:
```sh
pip install CRUDFastAPI
```
Or, if using poetry:
```sh
poetry add CRUDFastAPI
```
<h2>Usage</h2>
CRUDFastAPI offers two primary ways to use its functionalities:
1. By using `crud_router` for automatic endpoint creation.
2. By integrating `CRUDFastAPI` directly into your FastAPI endpoints for more control.
Below are examples demonstrating both approaches:
<h3>Using crud_router for Automatic Endpoint Creation</h3>
Here's a quick example to get you started:
<h4>Define Your Model and Schema</h4>
**models.py**
```python
from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import DeclarativeBase
class Base(DeclarativeBase):
pass
class Item(Base):
__tablename__ = 'items'
id = Column(Integer, primary_key=True)
name = Column(String)
description = Column(String)
```
**schemas.py**
```python
from pydantic import BaseModel
class ItemCreateSchema(BaseModel):
name: str
description: str
class ItemUpdateSchema(BaseModel):
name: str
description: str
```
<h4>Set Up FastAPI and CRUDFastAPI</h4>
**main.py**
```python
from typing import AsyncGenerator
from fastapi import FastAPI
from CRUDFastAPI import CRUDFastAPI, crud_router
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import sessionmaker
from yourapp.models import Base, Item
from yourapp.schemas import ItemCreateSchema, ItemUpdateSchema
# Database setup (Async SQLAlchemy)
DATABASE_URL = "sqlite+aiosqlite:///./test.db"
engine = create_async_engine(DATABASE_URL, echo=True)
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
# Database session dependency
async def get_session() -> AsyncGenerator[AsyncSession, None]:
async with async_session() as session:
yield session
# Create tables before the app start
async def lifespan(app: FastAPI):
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield
# FastAPI app
app = FastAPI(lifespan=lifespan)
# CRUD router setup
item_router = crud_router(
session=get_session,
model=Item,
create_schema=ItemCreateSchema,
update_schema=ItemUpdateSchema,
path="/items",
tags=["Items"],
)
app.include_router(item_router)
```
<h3>Using CRUDFastAPI in User-Defined FastAPI Endpoints</h3>
For more control over your endpoints, you can use CRUDFastAPI directly within your custom FastAPI route functions. Here's an example:
**main.py**
```python
from typing import AsyncGenerator
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import sessionmaker
from CRUDFastAPI import CRUDFastAPI
from models import Base, Item
from schemas import ItemCreateSchema, ItemUpdateSchema
# Database setup (Async SQLAlchemy)
DATABASE_URL = "sqlite+aiosqlite:///./test.db"
engine = create_async_engine(DATABASE_URL, echo=True)
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
# Database session dependency
async def get_session() -> AsyncGenerator[AsyncSession, None]:
async with async_session() as session:
yield session
# Create tables before the app start
async def lifespan(app: FastAPI):
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
yield
# FastAPI app
app = FastAPI(lifespan=lifespan)
# Instantiate CRUDFastAPI with your model
item_crud = CRUDFastAPI(Item)
@app.post("/custom/items/")
async def create_item(
item_data: ItemCreateSchema, db: AsyncSession = Depends(get_session)
):
return await item_crud.create(db, item_data)
@app.get("/custom/items/{item_id}")
async def read_item(item_id: int, db: AsyncSession = Depends(get_session)):
item = await item_crud.get(db, id=item_id)
if not item:
raise HTTPException(status_code=404, detail="Item not found")
return item
# You can add more routes for update and delete operations in a similar fashion
```
In this example, we define custom endpoints for creating and reading items using CRUDFastAPI directly, providing more flexibility in how the endpoints are structured and how the responses are handled.
## References
- This project was heavily inspired by CRUDBase in [`FastAPI Microservices`](https://github.com/Kludex/fastapi-microservices) by [@kludex](https://github.com/kludex).
- Thanks [@ada0l](https://github.com/ada0l) for the PyPI package name!
## Similar Projects
- **[flask-muck](https://github.com/dtiesling/flask-muck)** - _"I'd love something like this for flask"_ There you have it
- **[FastAPI CRUD Router](https://github.com/awtkns/fastapi-crudrouter)** - Supports multiple ORMs, but currently unmantained
- **[FastAPI Quick CRUD](https://github.com/LuisLuii/FastAPIQuickCRUD)** - Same purpose, but only for SQLAlchemy 1.4
## License
[`MIT`](LICENSE.md)
## Contact
[github.com/mithun2003](https://github.com/mithun2003/)
Raw data
{
"_id": null,
"home_page": "https://github.com/mithun2003/CRUDFastAPI",
"name": "CRUDFastAPI",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "fastapi, crud, async, sqlalchemy, pydantic, fastcrud, crudfastapi",
"author": "Mithun Thomas",
"author_email": "mithunthomas003@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/84/3f/8381cb48733bdfb5abe7907d4abdcb67c77cd4e2eaeda1e6f25b76e3028f/crudfastapi-0.1.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://mithun2003.github.io/CRUDFastAPI/\">\n <!-- <img src=\"https://github.com/mithun2003/CRUDFastAPI/blob/main/assets/CRUDFastAPI.png?raw=true\" alt=\"CRUDFastAPI written in white with a drawing of a gear and inside this gear a bolt.\" width=\"45%\" height=\"auto\"> -->\n </a>\n</p>\n<p align=\"center\" markdown=1>\n <i>Powerful CRUD methods and automatic endpoint creation for FastAPI.</i>\n</p>\n<p align=\"center\" markdown=1>\n<a href=\"https://github.com/mithun2003/CRUDFastAPI/actions/workflows/tests.yml\">\n <img src=\"https://github.com/mithun2003/CRUDFastAPI/actions/workflows/tests.yml/badge.svg\" alt=\"Tests\"/>\n</a>\n<a href=\"https://pypi.org/project/CRUDFastAPI/\">\n <img src=\"https://img.shields.io/pypi/v/CRUDFastAPI?color=%2334D058&label=pypi%20package\" alt=\"PyPi Version\"/>\n</a>\n<a href=\"https://pypi.org/project/CRUDFastAPI/\">\n <img src=\"https://img.shields.io/pypi/pyversions/CRUDFastAPI.svg?color=%2334D058\" alt=\"Supported Python Versions\"/>\n</a>\n<a href=\"https://codecov.io/gh/mithun2003/CRUDFastAPI\" > \n <img src=\"https://codecov.io/gh/mithun2003/CRUDFastAPI/graph/badge.svg?token=J7XUP29RKU\"/> \n</a>\n</p>\n<hr>\n<p align=\"justify\">\n<b>CRUDFastAPI</b> is a Python package for <b>FastAPI</b>, offering robust async CRUD operations and flexible endpoint creation utilities, streamlined through advanced features like <b>auto-detected join</b> conditions, <b>dynamic sorting</b>, and offset and cursor <b>pagination</b>.\n</p>\n<hr>\n<h2>Features</h2>\n\n- \u26a1\ufe0f **Fully Async**: Leverages Python's async capabilities for non-blocking database operations.\n- \ud83d\udcda **SQLAlchemy 2.0**: Works with the latest SQLAlchemy version for robust database interactions.\n- \ud83e\uddbe **Powerful CRUD Functionality**: Full suite of efficient CRUD operations with support for joins.\n- \u2699\ufe0f **Dynamic Query Building**: Supports building complex queries dynamically, including filtering, sorting, and pagination.\n- \ud83e\udd1d **Advanced Join Operations**: Facilitates performing SQL joins with other models with automatic join condition detection.\n- \ud83d\udcd6 **Built-in Offset Pagination**: Comes with ready-to-use offset pagination.\n- \u27a4 **Cursor-based Pagination**: Implements efficient pagination for large datasets, ideal for infinite scrolling interfaces.\n- \ud83e\udd38\u200d\u2642\ufe0f **Modular and Extensible**: Designed for easy extension and customization to fit your requirements.\n- \ud83d\udee3\ufe0f **Auto-generated Endpoints**: Streamlines the process of adding CRUD endpoints with custom dependencies and configurations.\n\n<h2>Requirements</h2>\n<p>Before installing CRUDFastAPI, ensure you have the following prerequisites:</p>\n<ul>\n <li><b>Python:</b> Version 3.9 or newer.</li>\n <li><b>FastAPI:</b> CRUDFastAPI is built to work with FastAPI, so having FastAPI in your project is essential.</li>\n <li><b>SQLAlchemy:</b> Version 2.0.21 or newer. CRUDFastAPI uses SQLAlchemy for database operations.</li>\n <li><b>Pydantic:</b> Version 2.4.1 or newer. CRUDFastAPI leverages Pydantic models for data validation and serialization.</li>\n <li><b>SQLAlchemy-Utils:</b> Optional, but recommended for additional SQLAlchemy utilities.</li>\n</ul>\n\n<h2>Installing</h2>\n\nTo install, just run:\n\n```sh\npip install CRUDFastAPI\n```\n\nOr, if using poetry:\n\n```sh\npoetry add CRUDFastAPI\n```\n\n<h2>Usage</h2>\n\nCRUDFastAPI offers two primary ways to use its functionalities:\n\n1. By using `crud_router` for automatic endpoint creation.\n2. By integrating `CRUDFastAPI` directly into your FastAPI endpoints for more control.\n\nBelow are examples demonstrating both approaches:\n\n<h3>Using crud_router for Automatic Endpoint Creation</h3>\n\nHere's a quick example to get you started:\n\n<h4>Define Your Model and Schema</h4>\n\n**models.py**\n\n```python\nfrom sqlalchemy import Column, Integer, String\nfrom sqlalchemy.orm import DeclarativeBase\n\nclass Base(DeclarativeBase):\n pass\n\nclass Item(Base):\n __tablename__ = 'items'\n id = Column(Integer, primary_key=True)\n name = Column(String)\n description = Column(String)\n```\n\n**schemas.py**\n\n```python\nfrom pydantic import BaseModel\n\nclass ItemCreateSchema(BaseModel):\n name: str\n description: str\n\nclass ItemUpdateSchema(BaseModel):\n name: str\n description: str\n```\n\n<h4>Set Up FastAPI and CRUDFastAPI</h4>\n\n**main.py**\n\n```python\nfrom typing import AsyncGenerator\n\nfrom fastapi import FastAPI\nfrom CRUDFastAPI import CRUDFastAPI, crud_router\nfrom sqlalchemy.ext.asyncio import AsyncSession, create_async_engine\nfrom sqlalchemy.orm import sessionmaker\n\nfrom yourapp.models import Base, Item\nfrom yourapp.schemas import ItemCreateSchema, ItemUpdateSchema\n\n# Database setup (Async SQLAlchemy)\nDATABASE_URL = \"sqlite+aiosqlite:///./test.db\"\nengine = create_async_engine(DATABASE_URL, echo=True)\nasync_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)\n\n# Database session dependency\nasync def get_session() -> AsyncGenerator[AsyncSession, None]:\n async with async_session() as session:\n yield session\n\n# Create tables before the app start\nasync def lifespan(app: FastAPI):\n async with engine.begin() as conn:\n await conn.run_sync(Base.metadata.create_all)\n yield\n\n# FastAPI app\napp = FastAPI(lifespan=lifespan)\n\n# CRUD router setup\nitem_router = crud_router(\n session=get_session,\n model=Item,\n create_schema=ItemCreateSchema,\n update_schema=ItemUpdateSchema,\n path=\"/items\",\n tags=[\"Items\"],\n)\n\napp.include_router(item_router)\n\n```\n\n<h3>Using CRUDFastAPI in User-Defined FastAPI Endpoints</h3>\n\nFor more control over your endpoints, you can use CRUDFastAPI directly within your custom FastAPI route functions. Here's an example:\n\n**main.py**\n\n```python\nfrom typing import AsyncGenerator\n\nfrom fastapi import FastAPI, Depends, HTTPException\nfrom sqlalchemy.ext.asyncio import AsyncSession, create_async_engine\nfrom sqlalchemy.orm import sessionmaker\nfrom CRUDFastAPI import CRUDFastAPI\n\nfrom models import Base, Item\nfrom schemas import ItemCreateSchema, ItemUpdateSchema\n\n# Database setup (Async SQLAlchemy)\nDATABASE_URL = \"sqlite+aiosqlite:///./test.db\"\nengine = create_async_engine(DATABASE_URL, echo=True)\nasync_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)\n\n# Database session dependency\nasync def get_session() -> AsyncGenerator[AsyncSession, None]:\n async with async_session() as session:\n yield session\n\n# Create tables before the app start\nasync def lifespan(app: FastAPI):\n async with engine.begin() as conn:\n await conn.run_sync(Base.metadata.create_all)\n yield\n\n# FastAPI app\napp = FastAPI(lifespan=lifespan)\n\n# Instantiate CRUDFastAPI with your model\nitem_crud = CRUDFastAPI(Item)\n\n@app.post(\"/custom/items/\")\nasync def create_item(\n item_data: ItemCreateSchema, db: AsyncSession = Depends(get_session)\n):\n return await item_crud.create(db, item_data)\n\n@app.get(\"/custom/items/{item_id}\")\nasync def read_item(item_id: int, db: AsyncSession = Depends(get_session)):\n item = await item_crud.get(db, id=item_id)\n if not item:\n raise HTTPException(status_code=404, detail=\"Item not found\")\n return item\n\n# You can add more routes for update and delete operations in a similar fashion\n```\n\nIn this example, we define custom endpoints for creating and reading items using CRUDFastAPI directly, providing more flexibility in how the endpoints are structured and how the responses are handled.\n\n\n## References\n\n- This project was heavily inspired by CRUDBase in [`FastAPI Microservices`](https://github.com/Kludex/fastapi-microservices) by [@kludex](https://github.com/kludex).\n- Thanks [@ada0l](https://github.com/ada0l) for the PyPI package name!\n\n## Similar Projects\n\n- **[flask-muck](https://github.com/dtiesling/flask-muck)** - _\"I'd love something like this for flask\"_ There you have it\n- **[FastAPI CRUD Router](https://github.com/awtkns/fastapi-crudrouter)** - Supports multiple ORMs, but currently unmantained\n- **[FastAPI Quick CRUD](https://github.com/LuisLuii/FastAPIQuickCRUD)** - Same purpose, but only for SQLAlchemy 1.4\n\n## License\n\n[`MIT`](LICENSE.md)\n\n## Contact\n\n[github.com/mithun2003](https://github.com/mithun2003/)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CRUDFastAPI is a Python package for FastAPI, offering robust async CRUD operations and flexible endpoint creation utilities.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/mithun2003/CRUDFastAPI",
"Repository": "https://github.com/mithun2003/CRUDFastAPI"
},
"split_keywords": [
"fastapi",
" crud",
" async",
" sqlalchemy",
" pydantic",
" fastcrud",
" crudfastapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6d60f58b92bc7175a4ef2ab9fea4f98453e669edfe0e0cf54b32fe729b370ca2",
"md5": "4a163661b73af81131a40d13712a1b33",
"sha256": "d9b75efe58c7673696cb9fc48251efc6c0fca811b6db5ef6daa4fae7a4193ab9"
},
"downloads": -1,
"filename": "crudfastapi-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4a163661b73af81131a40d13712a1b33",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 37341,
"upload_time": "2024-06-01T04:10:08",
"upload_time_iso_8601": "2024-06-01T04:10:08.901918Z",
"url": "https://files.pythonhosted.org/packages/6d/60/f58b92bc7175a4ef2ab9fea4f98453e669edfe0e0cf54b32fe729b370ca2/crudfastapi-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "843f8381cb48733bdfb5abe7907d4abdcb67c77cd4e2eaeda1e6f25b76e3028f",
"md5": "99164480a02800034e9b164feaa40eaf",
"sha256": "a6927d984ce7c19880effcfeedb28c034dfc06e5729f9d0a55d52c6a0f43cc01"
},
"downloads": -1,
"filename": "crudfastapi-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "99164480a02800034e9b164feaa40eaf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 31896,
"upload_time": "2024-06-01T04:10:11",
"upload_time_iso_8601": "2024-06-01T04:10:11.162224Z",
"url": "https://files.pythonhosted.org/packages/84/3f/8381cb48733bdfb5abe7907d4abdcb67c77cd4e2eaeda1e6f25b76e3028f/crudfastapi-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-01 04:10:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mithun2003",
"github_project": "CRUDFastAPI",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "crudfastapi"
}
JSON
