CRUDFastAPI


NameCRUDFastAPI JSON
Version 0.1.2 PyPI version JSON
download
home_pagehttps://github.com/mithun2003/CRUDFastAPI
SummaryCRUDFastAPI is a Python package for FastAPI, offering robust async CRUD operations and flexible endpoint creation utilities.
upload_time2024-06-29 19:58:36
maintainerNone
docs_urlNone
authorMithun Thomas
requires_python<4.0,>=3.9
licenseMIT
keywords fastapi crud async sqlalchemy pydantic fastcrud crudfastapi
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <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/1e/63/e1312b107c2b0392484224e8316de1e7860f8653582ea6108377bd75bcce/crudfastapi-0.1.2.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.2",
    "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": "8e64c7795e34f97d50f7bad1f687b00f4a1a17097a588fecaa9e620c21d61fe3",
                "md5": "1b65856ba697a485e3c73d2a6463a849",
                "sha256": "f49bbfe965edefa6d236b0e95ca76129df2b8e4bcc52041b2074b75e1260e9ec"
            },
            "downloads": -1,
            "filename": "crudfastapi-0.1.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "1b65856ba697a485e3c73d2a6463a849",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.9",
            "size": 37373,
            "upload_time": "2024-06-29T19:58:34",
            "upload_time_iso_8601": "2024-06-29T19:58:34.573770Z",
            "url": "https://files.pythonhosted.org/packages/8e/64/c7795e34f97d50f7bad1f687b00f4a1a17097a588fecaa9e620c21d61fe3/crudfastapi-0.1.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1e63e1312b107c2b0392484224e8316de1e7860f8653582ea6108377bd75bcce",
                "md5": "d298e7cf4b77205404e2db657775494a",
                "sha256": "df637ea34558aa7b2dd62748645e31bcaeed3888eb33ece160a593c97db1ec97"
            },
            "downloads": -1,
            "filename": "crudfastapi-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "d298e7cf4b77205404e2db657775494a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.9",
            "size": 31845,
            "upload_time": "2024-06-29T19:58:36",
            "upload_time_iso_8601": "2024-06-29T19:58:36.369699Z",
            "url": "https://files.pythonhosted.org/packages/1e/63/e1312b107c2b0392484224e8316de1e7860f8653582ea6108377bd75bcce/crudfastapi-0.1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-06-29 19:58:36",
    "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"
}
        
Elapsed time: 0.28044s