{"id":17880533,"url":"https://github.com/igorbenav/fastcrud","last_synced_at":"2025-04-14T23:15:42.037Z","repository":{"id":218140984,"uuid":"740300919","full_name":"igorbenav/fastcrud","owner":"igorbenav","description":"FastCRUD is a Python package for FastAPI, offering robust async CRUD operations and flexible endpoint creation utilities.","archived":false,"fork":false,"pushed_at":"2025-04-07T05:09:37.000Z","size":4022,"stargazers_count":1008,"open_issues_count":30,"forks_count":72,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-14T23:15:33.137Z","etag":null,"topics":["async","backend","crud","fastapi","pydantic","pydantic-v2","python","sqlalchemy"],"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/igorbenav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"igorbenav"}},"created_at":"2024-01-08T04:04:17.000Z","updated_at":"2025-04-14T15:48:38.000Z","dependencies_parsed_at":"2024-02-03T20:29:14.708Z","dependency_job_id":"22ff05af-f1f7-4310-b326-933c7542398d","html_url":"https://github.com/igorbenav/fastcrud","commit_stats":null,"previous_names":["igorbenav/fastcrud"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Ffastcrud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Ffastcrud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Ffastcrud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Ffastcrud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igorbenav","download_url":"https://codeload.github.com/igorbenav/fastcrud/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248975329,"owners_count":21192210,"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":["async","backend","crud","fastapi","pydantic","pydantic-v2","python","sqlalchemy"],"created_at":"2024-10-28T12:18:53.594Z","updated_at":"2025-04-14T23:15:42.018Z","avatar_url":"https://github.com/igorbenav.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://igorbenav.github.io/fastcrud/\"\u003e\n    \u003cimg src=\"https://github.com/igorbenav/fastcrud/blob/main/assets/fastcrud.png?raw=true\" alt=\"FastCRUD written in white with a drawing of a gear and inside this gear a bolt.\" width=\"45%\" height=\"auto\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\" markdown=1\u003e\n  \u003ci\u003ePowerful CRUD methods and automatic endpoint creation for FastAPI.\u003c/i\u003e\n\u003c/p\u003e\n\u003cp align=\"center\" markdown=1\u003e\n\u003ca href=\"https://github.com/igorbenav/fastcrud/actions/workflows/tests.yml\"\u003e\n  \u003cimg src=\"https://github.com/igorbenav/fastcrud/actions/workflows/tests.yml/badge.svg\" alt=\"Tests\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/fastcrud/\"\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/v/fastcrud?color=%2334D058\u0026label=pypi%20package\" alt=\"PyPi Version\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/fastcrud/\"\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/pyversions/fastcrud.svg?color=%2334D058\" alt=\"Supported Python Versions\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://codecov.io/gh/igorbenav/fastcrud\" \u003e \n  \u003cimg src=\"https://codecov.io/gh/igorbenav/fastcrud/graph/badge.svg?token=J7XUP29RKU\"/\u003e \n\u003c/a\u003e\n\u003c/p\u003e\n\u003chr\u003e\n\u003cp align=\"justify\"\u003e\n\u003cb\u003eFastCRUD\u003c/b\u003e is a Python package for \u003cb\u003eFastAPI\u003c/b\u003e, offering robust async CRUD operations and flexible endpoint creation utilities, streamlined through advanced features like \u003cb\u003eauto-detected join\u003c/b\u003e conditions, \u003cb\u003edynamic sorting\u003c/b\u003e, and offset and cursor \u003cb\u003epagination\u003c/b\u003e.\n\u003c/p\u003e\n\u003cp\u003e\u003cb\u003eDocumentation\u003c/b\u003e: \u003ca href=\"https://igorbenav.github.io/fastcrud/\"\u003eigorbenav.github.io/fastcrud\u003c/a\u003e\u003c/p\u003e\n\u003chr\u003e\n\u003ch2\u003eFeatures\u003c/h2\u003e\n\n- ⚡️ **Fully Async**: Leverages Python's async capabilities for non-blocking database operations.\n- 📚 **SQLAlchemy 2.0**: Works with the latest SQLAlchemy version for robust database interactions.\n- 🦾 **Powerful CRUD Functionality**: Full suite of efficient CRUD operations with support for joins.\n- ⚙️ **Dynamic Query Building**: Supports building complex queries dynamically, including filtering, sorting, and pagination.\n- 🤝 **Advanced Join Operations**: Facilitates performing SQL joins with other models with automatic join condition detection.\n- 📖 **Built-in Offset Pagination**: Comes with ready-to-use offset pagination.\n- ➤ **Cursor-based Pagination**: Implements efficient pagination for large datasets, ideal for infinite scrolling interfaces.\n- 🤸‍♂️ **Modular and Extensible**: Designed for easy extension and customization to fit your requirements.\n- 🛣️ **Auto-generated Endpoints**: Streamlines the process of adding CRUD endpoints with custom dependencies and configurations.\n\n\u003ch2\u003eRequirements\u003c/h2\u003e\n\u003cp\u003eBefore installing FastCRUD, ensure you have the following prerequisites:\u003c/p\u003e\n\u003cul\u003e\n  \u003cli\u003e\u003cb\u003ePython:\u003c/b\u003e Version 3.9 or newer.\u003c/li\u003e\n  \u003cli\u003e\u003cb\u003eFastAPI:\u003c/b\u003e FastCRUD is built to work with FastAPI, so having FastAPI in your project is essential.\u003c/li\u003e\n  \u003cli\u003e\u003cb\u003eSQLAlchemy:\u003c/b\u003e Version 2.0.21 or newer. FastCRUD uses SQLAlchemy for database operations.\u003c/li\u003e\n  \u003cli\u003e\u003cb\u003ePydantic:\u003c/b\u003e Version 2.4.1 or newer. FastCRUD leverages Pydantic models for data validation and serialization.\u003c/li\u003e\n  \u003cli\u003e\u003cb\u003eSQLAlchemy-Utils:\u003c/b\u003e Optional, but recommended for additional SQLAlchemy utilities.\u003c/li\u003e\n\u003c/ul\u003e\n\n\u003ch2\u003eInstalling\u003c/h2\u003e\n\nTo install, just run:\n\n```sh\npip install fastcrud\n```\n\nOr, if using poetry:\n\n```sh\npoetry add fastcrud\n```\n\n\u003ch2\u003eUsage\u003c/h2\u003e\n\nFastCRUD offers two primary ways to use its functionalities:\n\n1. By using `crud_router` for automatic endpoint creation.\n2. By integrating `FastCRUD` directly into your FastAPI endpoints for more control.\n\nBelow are examples demonstrating both approaches:\n\n\u003ch3\u003eUsing crud_router for Automatic Endpoint Creation\u003c/h3\u003e\n\nHere's a quick example to get you started:\n\n\u003ch4\u003eDefine Your Model and Schema\u003c/h4\u003e\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\u003ch4\u003eSet Up FastAPI and FastCRUD\u003c/h4\u003e\n\n**main.py**\n\n```python\nfrom typing import AsyncGenerator\n\nfrom fastapi import FastAPI\nfrom fastcrud import FastCRUD, 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() -\u003e 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\u003ch3\u003eUsing FastCRUD in User-Defined FastAPI Endpoints\u003c/h3\u003e\n\nFor more control over your endpoints, you can use FastCRUD 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 fastcrud import FastCRUD\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() -\u003e 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 FastCRUD with your model\nitem_crud = FastCRUD(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 FastCRUD directly, providing more flexibility in how the endpoints are structured and how the responses are handled.\n\nTo read more detailed descriptions, go to the \u003ca href=\"https://igorbenav.github.io/fastcrud/\"\u003edocumentation\u003c/a\u003e.\n\n\u003ch2\u003eShowcase\u003c/h2\u003e\n\nBrowse our [showcase](https://igorbenav.github.io/fastcrud/showcase/) to see projects and tutorials built with FastCRUD:\n\n- 🚀 **Applications**: Web apps and services powered by FastCRUD\n- 📖 **Open Source**: Libraries and tools built with FastCRUD\n- 📝 **Tutorials**: Learn how to build with FastCRUD\n\n\u003ch3\u003eFeatured Projects\u003c/h3\u003e\n\n- **[FastAPI Boilerplate](https://github.com/igorbenav/FastAPI-boilerplate)**: Extendable async API using FastAPI, Pydantic V2, SQLAlchemy 2.0 and PostgreSQL\n- **[Email Assistant API](https://github.com/igorbenav/email-assistant-api)**: Personalized email writing assistant using OpenAI\n- **[SQLModel Boilerplate](https://github.com/igorbenav/SQLModel-boilerplate)**: Async API boilerplate using FastAPI, SQLModel and PostgreSQL\n\n\u003ch3\u003eShare Your Project\u003c/h3\u003e\n\nBuilt something with FastCRUD? We'd love to feature it! Submit your project through our [showcase submission process](https://igorbenav.github.io/fastcrud/community/showcase_submission/).\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\nIgor Magalhaes – [@igormagalhaesr](https://twitter.com/igormagalhaesr) – igormagalhaesr@gmail.com\n[github.com/igorbenav](https://github.com/igorbenav/)\n","funding_links":["https://github.com/sponsors/igorbenav"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbenav%2Ffastcrud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorbenav%2Ffastcrud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbenav%2Ffastcrud/lists"}