fastapi-crud-generator 0.0.1__tar.gz

fastapi_crud_generator-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "fastapi_crud_generator/**"  # docstrings in source
+
+jobs:
+  deploy:
+    name: Build & deploy
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # push to gh-pages branch
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Deploy docs
+        run: uv run --group docs mkdocs gh-deploy --force

fastapi_crud_generator-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    name: Build & publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write   # create GitHub release
+      id-token: write   # OIDC token for PyPI trusted publisher
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastapi_crud_generator-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,105 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  unit:
+    name: unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --group dev --group sqlmodel
+      - name: Run unit tests
+        run: uv run pytest tests/ --ignore=tests/integration/ -q
+
+  test:
+    name: ${{ matrix.orm }} / ${{ matrix.db }}
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: mysql
+          MYSQL_DATABASE: test
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -pmysql"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - orm: sqlmodel
+            db: sqlite
+            uv_groups: "--group sqlmodel --group sqlite"
+          - orm: sqlalchemy
+            db: sqlite
+            uv_groups: "--group sqlalchemy --group sqlite"
+          - orm: tortoise
+            db: sqlite
+            uv_groups: "--group tortoise --group sqlite"
+
+          - orm: sqlmodel
+            db: postgres
+            uv_groups: "--group sqlmodel --group postgresql"
+            postgres_url: postgresql+asyncpg://postgres:postgres@localhost/test
+          - orm: sqlalchemy
+            db: postgres
+            uv_groups: "--group sqlalchemy --group postgresql"
+            postgres_url: postgresql+asyncpg://postgres:postgres@localhost/test
+          - orm: tortoise
+            db: postgres
+            uv_groups: "--group tortoise --group postgresql"
+            postgres_url: postgresql+asyncpg://postgres:postgres@localhost/test
+
+          - orm: sqlmodel
+            db: mysql
+            uv_groups: "--group sqlmodel --group mysql"
+            mysql_url: mysql+aiomysql://root:mysql@localhost/test
+          - orm: sqlalchemy
+            db: mysql
+            uv_groups: "--group sqlalchemy --group mysql"
+            mysql_url: mysql+aiomysql://root:mysql@localhost/test
+          - orm: tortoise
+            db: mysql
+            uv_groups: "--group tortoise --group mysql"
+            mysql_url: mysql+aiomysql://root:mysql@localhost/test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --group dev ${{ matrix.uv_groups }}
+
+      - name: Run tests
+        run: uv run pytest tests/integration/ -q
+        env:
+          PYTEST_ORM: ${{ matrix.orm }}
+          PYTEST_DB: ${{ matrix.db }}
+          POSTGRES_URL: ${{ matrix.postgres_url }}
+          MYSQL_URL: ${{ matrix.mysql_url }}

fastapi_crud_generator-0.0.1/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Build / distribution
+dist/
+build/
+*.egg-info/
+*.egg
+
+# uv
+.uv/
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Jupyter
+jupyter/
+*.ipynb
+
+# MkDocs
+site/
+TEST_MATRIX.md

fastapi_crud_generator-0.0.1/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Nikolai Lukianov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

fastapi_crud_generator-0.0.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: fastapi-crud-generator
+Version: 0.0.1
+Summary: CRUD route generator for FastAPI
+Project-URL: Homepage, https://github.com/mozgsml/fastapi_crud_generator
+Project-URL: Repository, https://github.com/mozgsml/fastapi_crud_generator
+Project-URL: Issues, https://github.com/mozgsml/fastapi_crud_generator/issues
+Author-email: Nikolai Lukianov <laserwargpt@gmail.com>
+License: The MIT License (MIT)
+        
+        Copyright (c) 2026 Nikolai Lukianov
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+        THE SOFTWARE.
+License-File: LICENSE.txt
+Keywords: api,crud,fastapi,rest,sqlalchemy,sqlmodel,tortoise
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi
+Requires-Dist: pydantic
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy[asyncio]; extra == 'sqlalchemy'
+Provides-Extra: sqlmodel
+Requires-Dist: sqlmodel; extra == 'sqlmodel'
+Provides-Extra: tortoise
+Requires-Dist: tortoise-orm>=1.1.7; extra == 'tortoise'
+Description-Content-Type: text/markdown
+
+# fastapi-crud-generator
+
+[![Tests](https://github.com/mozgsml/fastapi_crud_generator/actions/workflows/tests.yml/badge.svg)](https://github.com/mozgsml/fastapi_crud_generator/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/fastapi-crud-generator)](https://pypi.org/project/fastapi-crud-generator/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-crud-generator)](https://pypi.org/project/fastapi-crud-generator/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+Adds full CRUD routes to FastAPI without writing schemas, filters, or pagination by hand.
+Everything is generated automatically from your ORM model.
+
+```python
+from fastapi_crud_generator import CRUDCollection
+from fastapi_crud_generator.orm.sqlmodel import SQLModelAdapter
+
+crud = CRUDCollection(orm_adapter=SQLModelAdapter(model=Article, get_session=get_session))
+app.include_router(crud.get_router(prefix="/articles", tags=["articles"]))
+```
+
+Three lines — and five endpoints are ready with filtering, sorting, and pagination:
+
+```
+GET    /articles              ?title=…&published=true&sort=created_at:desc&page=1&per_page=20
+GET    /articles/{article_id}
+POST   /articles
+PATCH  /articles/{article_id}
+DELETE /articles/{article_id}
+```
+
+## Installation
+
+If SQLModel, SQLAlchemy, or Tortoise is already in your project:
+
+```bash
+pip install fastapi-crud-generator
+```
+
+To install an ORM together with the package:
+
+```bash
+pip install "fastapi-crud-generator[sqlmodel]"
+pip install "fastapi-crud-generator[sqlalchemy]"
+pip install "fastapi-crud-generator[tortoise]"
+```
+
+## Documentation
+
+**[mozgsml.github.io/fastapi_crud_generator](https://mozgsml.github.io/fastapi_crud_generator)**
+
+- [Getting Started](https://mozgsml.github.io/fastapi_crud_generator/guide/getting-started/) — full working example from scratch
+- [Schema Generation](https://mozgsml.github.io/fastapi_crud_generator/guide/schema-generation/) — control which fields appear in each schema
+- [Nested Resources](https://mozgsml.github.io/fastapi_crud_generator/guide/nested-resources/) — `/threads/{id}/posts/{id}`
+- [Custom Adapter](https://mozgsml.github.io/fastapi_crud_generator/custom-adapter/) — connect your own ORM
+
+## License
+
+MIT

fastapi_crud_generator-0.0.1/README.md

@@ -0,0 +1,56 @@
+# fastapi-crud-generator
+
+[![Tests](https://github.com/mozgsml/fastapi_crud_generator/actions/workflows/tests.yml/badge.svg)](https://github.com/mozgsml/fastapi_crud_generator/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/fastapi-crud-generator)](https://pypi.org/project/fastapi-crud-generator/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-crud-generator)](https://pypi.org/project/fastapi-crud-generator/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+Adds full CRUD routes to FastAPI without writing schemas, filters, or pagination by hand.
+Everything is generated automatically from your ORM model.
+
+```python
+from fastapi_crud_generator import CRUDCollection
+from fastapi_crud_generator.orm.sqlmodel import SQLModelAdapter
+
+crud = CRUDCollection(orm_adapter=SQLModelAdapter(model=Article, get_session=get_session))
+app.include_router(crud.get_router(prefix="/articles", tags=["articles"]))
+```
+
+Three lines — and five endpoints are ready with filtering, sorting, and pagination:
+
+```
+GET    /articles              ?title=…&published=true&sort=created_at:desc&page=1&per_page=20
+GET    /articles/{article_id}
+POST   /articles
+PATCH  /articles/{article_id}
+DELETE /articles/{article_id}
+```
+
+## Installation
+
+If SQLModel, SQLAlchemy, or Tortoise is already in your project:
+
+```bash
+pip install fastapi-crud-generator
+```
+
+To install an ORM together with the package:
+
+```bash
+pip install "fastapi-crud-generator[sqlmodel]"
+pip install "fastapi-crud-generator[sqlalchemy]"
+pip install "fastapi-crud-generator[tortoise]"
+```
+
+## Documentation
+
+**[mozgsml.github.io/fastapi_crud_generator](https://mozgsml.github.io/fastapi_crud_generator)**
+
+- [Getting Started](https://mozgsml.github.io/fastapi_crud_generator/guide/getting-started/) — full working example from scratch
+- [Schema Generation](https://mozgsml.github.io/fastapi_crud_generator/guide/schema-generation/) — control which fields appear in each schema
+- [Nested Resources](https://mozgsml.github.io/fastapi_crud_generator/guide/nested-resources/) — `/threads/{id}/posts/{id}`
+- [Custom Adapter](https://mozgsml.github.io/fastapi_crud_generator/custom-adapter/) — connect your own ORM
+
+## License
+
+MIT

fastapi_crud_generator-0.0.1/docs/api-reference.md

@@ -0,0 +1,37 @@
+# API Reference
+
+## CRUDCollection
+
+::: fastapi_crud_generator.crud_generator.CRUDCollection
+
+::: fastapi_crud_generator.crud_generator.CRUDCollectionBase
+
+## Adapters
+
+::: fastapi_crud_generator.orm.sqlmodel.SQLModelAdapter
+
+::: fastapi_crud_generator.orm.sqlalchemy.SQLAlchemyAdapter
+
+::: fastapi_crud_generator.orm.tortoise.TortoiseAdapter
+
+::: fastapi_crud_generator.orm.base.ORMAdapterBase
+
+## Configuration
+
+::: fastapi_crud_generator.config.CRUDConfigDict
+
+::: fastapi_crud_generator.config.NestedConfig
+
+## Pagination
+
+::: fastapi_crud_generator.paginator.PaginatorBase
+
+::: fastapi_crud_generator.schemas.PaginatorPage
+
+## Schemas & Errors
+
+::: fastapi_crud_generator.schemas.ParentRef
+
+::: fastapi_crud_generator.schemas.NotFoundError
+
+::: fastapi_crud_generator.schemas.ParentNotFoundError

fastapi_crud_generator-0.0.1/docs/custom-adapter.md

@@ -0,0 +1,120 @@
+# Custom Adapter
+
+To connect an ORM or data source that has no built-in adapter, implement `ORMAdapterBase`.
+
+## Interface
+
+```python
+from fastapi_crud_generator.orm.base import ORMAdapterBase
+from fastapi_crud_generator.schemas import PaginatorPage, ParentRef
+from pydantic import BaseModel
+
+class MyAdapter(ORMAdapterBase):
+    # Schema generation
+    def generate_public_schema(self, fields=None, base_fields=None) -> type[BaseModel]: ...
+    def generate_create_schema(self, fields=None, base_fields=None, exclude_related=None) -> type[BaseModel]: ...
+    def generate_update_schema(self, fields=None, base_fields=None) -> type[BaseModel]: ...
+    def generate_pk_schema(self) -> type[BaseModel]: ...
+    def generate_include_schema(self) -> type[BaseModel]: ...
+
+    # CRUD operations
+    async def get_one(self, pk_values, include_data, parent_refs=None): ...
+    async def get_many(self, filter_data, sort_data, include_data, paginator, parent_refs=None): ...
+    async def create_one(self, data, parent_refs=None): ...
+    async def update_one(self, pk_values, data, parent_refs=None): ...
+    async def delete_one(self, pk_values, parent_refs=None): ...
+```
+
+## Example: in-memory store
+
+```python
+from pydantic import BaseModel, create_model
+from fastapi_crud_generator.orm.base import ORMAdapterBase
+from fastapi_crud_generator.schemas import NotFoundError
+
+_store: dict[int, dict] = {}
+_next_id = 1
+
+class ItemPublic(BaseModel):
+    id: int
+    name: str
+    price: float
+
+class ItemCreate(BaseModel):
+    name: str
+    price: float
+
+class ItemUpdate(BaseModel):
+    name: str | None = None
+    price: float | None = None
+
+class ItemPK(BaseModel):
+    id: int
+
+class InMemoryAdapter(ORMAdapterBase):
+    def generate_public_schema(self, fields=None, base_fields=None):
+        return ItemPublic
+
+    def generate_create_schema(self, fields=None, base_fields=None, exclude_related=None):
+        return ItemCreate
+
+    def generate_update_schema(self, fields=None, base_fields=None):
+        return ItemUpdate
+
+    def generate_pk_schema(self):
+        return ItemPK
+
+    def generate_include_schema(self):
+        return create_model("ItemInclude")
+
+    async def get_one(self, pk_values, include_data, parent_refs=None):
+        return _store.get(pk_values.id)
+
+    async def get_many(self, filter_data, sort_data, include_data, paginator, parent_refs=None):
+        items = list(_store.values())
+        page = items[paginator.offset : paginator.offset + paginator.limit]
+        return {"page": paginator.page, "per_page": paginator.per_page, "count": len(items), "data": page}
+
+    async def create_one(self, data, parent_refs=None):
+        global _next_id
+        item = {"id": _next_id, **data.model_dump()}
+        _store[_next_id] = item
+        _next_id += 1
+        return item
+
+    async def update_one(self, pk_values, data, parent_refs=None):
+        if pk_values.id not in _store:
+            raise NotFoundError
+        for k, v in data.model_dump(exclude_none=True).items():
+            _store[pk_values.id][k] = v
+
+    async def delete_one(self, pk_values, parent_refs=None):
+        return _store.pop(pk_values.id, None)
+```
+
+Usage:
+
+```python
+crud = CRUDCollection(orm_adapter=InMemoryAdapter())
+app.include_router(crud.get_router(prefix="/items"))
+```
+
+## `parent_refs` in nested resources
+
+In nested routes, CRUD methods receive `parent_refs` — a list of `ParentRef`
+objects describing the parent items in the URL:
+
+```python
+from fastapi_crud_generator.schemas import ParentRef
+
+async def get_many(self, filter_data, sort_data, include_data, paginator, parent_refs=None):
+    query = select(Post)
+    for ref in (parent_refs or []):
+        if ref.model is Thread:
+            query = query.where(Post.thread_id == ref.pk_values.thread_id)
+    ...
+```
+
+## Full interface reference
+
+See [API Reference](api-reference.md).

fastapi_crud_generator-0.0.1/docs/guide/customization.md

@@ -0,0 +1,70 @@
+# Customization
+
+## Disabling endpoints
+
+```python
+crud = CRUDCollection(
+    orm_adapter=adapter,
+    disable_delete=True,
+    disable_create=True,
+)
+```
+
+## Overriding handlers via subclass
+
+Subclass `CRUDCollection` and override the methods you need:
+
+```python
+from fastapi_crud_generator import CRUDCollection
+from fastapi_crud_generator.orm.sqlmodel import SQLModelAdapter
+
+class ArticleCRUD(CRUDCollection):
+    orm_adapter = SQLModelAdapter(model=Article, get_session=get_session)
+
+    async def get_one_not_found(self, pk_values, include_data):
+        raise HTTPException(status_code=404, detail="Article not found")
+
+    async def create_one_handler(self, create_data, parent_refs):
+        create_data.slug = slugify(create_data.title)
+        return await super().create_one_handler(create_data, parent_refs)
+
+crud = ArticleCRUD()
+app.include_router(crud.get_router(prefix="/articles"))
+```
+
+## Class attributes instead of constructor arguments
+
+All `CRUDCollection` parameters can be set as class attributes:
+
+```python
+class ArticleCRUD(CRUDCollection):
+    orm_adapter = SQLModelAdapter(model=Article, get_session=get_session)
+    disable_delete = True
+    dependencies = [Depends(require_auth)]
+    create_dependencies = [Depends(require_admin)]
+```
+
+This is handy when several collections share common configuration:
+
+```python
+class AuthenticatedCRUD(CRUDCollection):
+    dependencies = [Depends(require_auth)]
+
+class ArticleCRUD(AuthenticatedCRUD):
+    orm_adapter = SQLModelAdapter(model=Article, get_session=get_session)
+
+class CommentCRUD(AuthenticatedCRUD):
+    orm_adapter = SQLModelAdapter(model=Comment, get_session=get_session)
+```
+
+## Custom ID path
+
+By default, `CRUDCollection` builds a path like `/{article_id}` from the model name.
+Override `apply_pk_aliases` to change this:
+
+```python
+class ArticleCRUD(CRUDCollection):
+    def apply_pk_aliases(self, pk_schema):
+        # use /{id} instead of /{article_id}
+        return pk_schema
+```

fastapi_crud_generator-0.0.1/docs/guide/dependencies.md

@@ -0,0 +1,58 @@
+# Dependencies
+
+Standard FastAPI dependencies (`Depends`) can be applied to all routes at once
+or to a specific operation type.
+
+## All routes
+
+```python
+from fastapi import Depends
+from fastapi_crud_generator import CRUDCollection
+
+crud = CRUDCollection(
+    orm_adapter=adapter,
+    dependencies=[Depends(require_auth)],
+)
+```
+
+## Per operation type
+
+```python
+crud = CRUDCollection(
+    orm_adapter=adapter,
+    get_one_dependencies=[Depends(require_auth)],
+    get_many_dependencies=[Depends(require_auth)],
+    create_dependencies=[Depends(require_admin)],
+    update_dependencies=[Depends(require_admin)],
+    delete_dependencies=[Depends(require_admin)],
+)
+```
+
+## Example: JWT authentication
+
+```python
+from fastapi import Depends, HTTPException, Security
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+security = HTTPBearer()
+
+async def require_auth(credentials: HTTPAuthorizationCredentials = Security(security)):
+    if not verify_token(credentials.credentials):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+crud = CRUDCollection(
+    orm_adapter=adapter,
+    dependencies=[Depends(require_auth)],
+)
+```
+
+## At router level
+
+Dependencies can also be added when mounting the router rather than in `CRUDCollection`:
+
+```python
+app.include_router(
+    crud.get_router(prefix="/articles"),
+    dependencies=[Depends(require_auth)],
+)
+```