https://github.com/bubaley/fastapi-mason

FastAPI Mason is a library for building applications with a Django REST Framework-inspired architecture.
https://github.com/bubaley/fastapi-mason

django django-rest-framework drf fastapi fastapi-crud fastapi-router tortoise viewsets

Last synced: 3 months ago
JSON representation

FastAPI Mason is a library for building applications with a Django REST Framework-inspired architecture.

Host: GitHub
URL: https://github.com/bubaley/fastapi-mason
Owner: bubaley
License: mit
Created: 2025-07-09T10:34:05.000Z (3 months ago)
Default Branch: main
Last Pushed: 2025-07-11T02:17:59.000Z (3 months ago)
Last Synced: 2025-07-11T06:30:11.719Z (3 months ago)
Topics: django, django-rest-framework, drf, fastapi, fastapi-crud, fastapi-router, tortoise, viewsets
Language: Python
Homepage:
Size: 73.2 KB
Stars: 3
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

          # FastAPI Mason



  

  
FastAPI Mason




  Django REST Framework-inspired ViewSets and utilities for FastAPI applications with Tortoise ORM







  





  





  







**Django REST Framework-inspired ViewSets and utilities for FastAPI applications with Tortoise ORM.**

FastAPI Mason brings the beloved patterns and conventions from Django REST Framework to FastAPI, providing a structured and efficient way to build REST APIs. With familiar concepts like ViewSets, permissions, pagination, and serialization, you can rapidly develop robust API applications.

Just like skilled masons who craft solid foundations with precision and expertise, FastAPI Mason helps you build reliable, well-structured APIs with time-tested patterns and best practices.



Documentation: bubaley.github.io/fastapi-mason





  

    Get Started

  



## 📦 Installation

Install FastAPI Mason using UV:

```bash

uv add fastapi-mason

```

## 🚀 Quick Example

Here's a complete example showing how to build a REST API with FastAPI Mason:

```python

# main.py - Complete FastAPI Mason application

from fastapi import APIRouter, FastAPI

from tortoise import fields

from tortoise.contrib.fastapi import register_tortoise

from tortoise.models import Model

from fastapi_mason.decorators import action, viewset

from fastapi_mason.pagination import PageNumberPagination

from fastapi_mason.schemas import SchemaMeta, generate_schema, rebuild_schema

from fastapi_mason.viewsets import ModelViewSet

from fastapi_mason.wrappers import PaginatedResponseDataWrapper, ResponseDataWrapper

# Database setup

def register_database(app: FastAPI):

    register_tortoise(

        app,

        db_url='sqlite://db.sqlite3',

        modules={'models': ['main']},

        generate_schemas=True,

        add_exception_handlers=True,

    )

# Models

class Company(Model):

    id = fields.IntField(primary_key=True)

    name = fields.CharField(max_length=255)

    full_name = fields.TextField(null=True)

    created_at = fields.DatetimeField(auto_now_add=True)

    updated_at = fields.DatetimeField(auto_now=True)

# Schema meta

class CompanyMeta(SchemaMeta):

    include = ('id', 'name', 'full_name', 'created_at', 'updated_at')

# Schemas

CompanySchema = generate_schema(Company, meta=CompanyMeta)

CompanyCreateSchema = rebuild_schema(CompanySchema, exclude_readonly=True)

# Views

router = APIRouter(prefix='/companies', tags=['companies'])

@viewset(router)

class CompanyViewSet(ModelViewSet[Company]):

    model = Company

    read_schema = CompanySchema

    create_schema = CompanyCreateSchema

    pagination = PageNumberPagination

    list_wrapper = PaginatedResponseDataWrapper

    single_wrapper = ResponseDataWrapper

    # permission_classes = [IsAuthenticatedOrReadOnly]

    @action(methods=['GET'], detail=False, response_model=dict[str, int])

    async def stats(self):

        return {'total': await Company.all().count()}

# Application

app = FastAPI(title='My API')

register_database(app)

app.include_router(router)

```

Start server:

```bash

uvicorn main:app --reload

```

 Try API Endpoints:

```python

"""

This creates the following endpoints:

- GET /companies/ - List companies with pagination

- POST /companies/ - Create new company

- GET /companies/{item_id}/ - Get specific company

- PUT /companies/{item_id}/ - Update company

- DELETE /companies/{item_id}/ - Delete company

- GET /companies/stats/ - Custom stats endpoint

Example API Responses:

GET /companies/ (with pagination wrapper):

{

  "data": [

    {

      "id": 1,

      "name": "Acme Corp",

      "full_name": "Acme Corporation Ltd.",

      "created_at": "2023-01-01T10:00:00Z",

      "updated_at": "2023-01-01T10:00:00Z"

    }

  ],

  "pagination": {

    "page": 1,

    "page_size": 10,

    "total_pages": 5,

    "total_items": 47

  }

}

GET /companies/1/ (with single wrapper):

{

  "data": {

    "id": 1,

    "name": "Acme Corp",

    "full_name": "Acme Corporation Ltd.",

    "created_at": "2023-01-01T10:00:00Z",

    "updated_at": "2023-01-01T10:00:00Z"

  }

}

GET /companies/stats/ (custom action):

{

  "total": 123

}

"""

```

## ✨ Key Features



  🎯 ViewSets

Django-like ViewSets with automatic CRUD operations and custom actions. Build complete REST APIs with minimal boilerplate code.





🔒 Permissions

Built-in permission system with customizable access control. Protect your endpoints with authentication and authorization rules.





📄 Pagination

Multiple pagination strategies out of the box: Limit/Offset and Page Number. You can easily customize or override pagination classes to suit your needs.





📋 Schema Generation

Intelligent schema generation with meta classes for fine-grained control over API serialization.





🔄 Response Wrappers

Consistent API response formatting with customizable wrapper classes.





⚡ State Management

Request-scoped state management for sharing data across middleware and view components.



## 🎯 Philosophy

FastAPI Mason is designed with these principles in mind:

- **Familiar**: If you know Django REST Framework, you already know FastAPI Mason

- **Flexible**: Customize every aspect while maintaining sensible defaults

- **Fast**: Built on FastAPI's high-performance foundation

- **Modular**: Use only what you need, when you need it

## 📚 Getting Started

Ready to build amazing APIs? Start with our [Quick Start guide](https://bubaley.github.io/fastapi-mason/quick-start/) to get up and running in minutes.

Want to dive deeper? Explore our comprehensive guides:

- [ViewSets](https://bubaley.github.io/fastapi-mason/viewsets/) - Learn about the core ViewSet concepts

- [Schemas](https://bubaley.github.io/fastapi-mason/schemas/) - Master schema generation and meta classes

- [Permissions](https://bubaley.github.io/fastapi-mason/permissions/) - Secure your APIs with permission classes

- [Pagination](https://bubaley.github.io/fastapi-mason/pagination/) - Implement efficient data pagination

- [State Management](https://bubaley.github.io/fastapi-mason/state/) - Manage request-scoped state

- [Response Wrappers](https://bubaley.github.io/fastapi-mason/wrappers/) - Format consistent API responses

## 🤝 Community

FastAPI Mason is open source and welcomes contributions! Whether you're reporting bugs, suggesting features, or submitting pull requests, your involvement helps make the library better for everyone.

- **GitHub**: [github.com/bubaley/fastapi-mason](https://github.com/bubaley/fastapi-mason)

- **Issues**: Report bugs and request features

- **Discussions**: Get help and share ideas

## 📄 License

FastAPI Mason is released under the [MIT License](https://github.com/bubaley/fastapi-mason/blob/main/LICENSE).