fastapi-listing 0.2.9

Advaned Data Listing Library for FastAPI

fastapi-listing

An Advanced Data Listing Library for fastapi

A Python library for building fast, extensible, and customizable data listing APIs.

Usage

➡️ Configure fastapi-listing for db session:

from fastapi import FastAPI
from sqlalchemy.orm import Session

from fastapi_listing.middlewares import DaoSessionBinderMiddleware

def get_db() -> Session:
    """
    replicating sessionmaker for any fastapi app.
    anyone could be using a different way or opensource packages to produce sessions.
    it all comes down to a single result that is yielding a session.
    for the sake of simplicity and testing purpose I'm replicating this behaviour in this way.
    :return: Session
    """

    
app = FastAPI()

# with this - use dao classes powered by sqlalchemy sessions anywhere in your project. no more passing sessions as args 
# here and there.
app.add_middleware(DaoSessionBinderMiddleware, master=get_db, replica=get_db)

➡️ How a typical data listing API would look like using fastapi-listing:

from fastapi_listing import ListingService, FastapiListing
from fastapi_listing import loader
from app.dao import EmployeeDao # More information is available in docs


@loader.register()
class EmployeeListingService(ListingService):

    default_srt_on = "Employee.emp_no" # configure default field to use for sorting data set.
    default_dao = EmployeeDao
    default_page_size = 2 # default page size. accepts dynamic vals from client

    def get_listing(self):
        fields_to_read = ["emp_no", "birth_date", "first_name",
                          "last_name", "gender", "hire_date", "image"]
        resp = FastapiListing(self.request, self.dao, fields_to_fetch=fields_to_read
                              ).get_response(self.MetaInfo(self))
        return resp

➡️ Just call EmployeeListingService(request).get_listing() from FastAPI routers:

from fastapi import APIRouter
from fastapi_listing.paginator import ListingPage # Automatic Listing api doc Generation. You can use it as adapter to change meta info in page layout.

from app.service import EmployeeListingService

router = APIRouter(prefix="/emps")

@router.get('/', response_model=ListingPage[EmployeeListingDetail])
def get_emps(request: Request):
    return EmployeeListingService(request).get_listing()

➡️ Use pydantic to avoid re-writing field_to_fetch:

@loader.register()
class EmployeeListingService(ListingService):

    default_srt_on = "Employee.emp_no"
    default_dao = EmployeeDao
    default_page_size = 2

    def get_listing(self):
        # your pydantic model contains custom non sqlalchemy model fields? pass custom_fields=True
        resp = FastapiListing(self.request, self.dao, pydantic_serializer=EmployeeListingDetail
                              ).get_response(self.MetaInfo(self))
        return resp
        

Thinking about adding filters???

Don't worry I've got you covered😎

➡️ Say you want to add filter on Employee for:

1. gender - return only Employees belonging to 'X' gender where X could be anything.
2. DOB - return Employees belonging to a specific range of DOB.
3. First Name - return Employees only starting with specific first names.

from fastapi_listing.filters import generic_filters # collection of inbuilt filters


@loader.register()
class EmployeeListingService(ListingService):

    filter_mapper = {
        "gdr": ("Employee.gender", generic_filters.EqualityFilter),
        "bdt": ("Employee.birth_date", generic_filters.MySqlNativeDateFormateRangeFilter),
        "fnm": ("Employee.first_name", generic_filters.StringStartsWithFilter),
    }
    

Check out docs for supported list of filters. Additionally, you can create custom filters as well. Check reference below 📝.

Thinking about adding Sorting???

I won't leave you hanging there as well😎

@loader.register()
class EmployeeListingService(ListingService):
    sort_mapper = {
        "cd": "Employee.emp_no",
        "bdt": "Employee.birth_date"
    }

Provided features are not meeting your requirements???

It is customizable.😎

➡️ You can write custom:

Query

Filters

Sorter

Paginator

Features

• Easy-to-use API for listing and formatting data
• Built-in support for pagination, sorting and filtering
• Well defined interface for filter, sorter, paginator
• Support Dependency Injection for easy testing
• Room to adapt the existing remote client query param semantics
• Write standardise listing APIs that will be understood by generations of upcoming developers
• Write listing features which is easy on human mind to extend or understand
• Break down the most complex listing data APIs into digestible piece of code

With FastAPI Listing you won't end up like

Documentation

View full documentation at: https://fastapi-listing.readthedocs.io ██▓░️░️░️░️░️░️░️

Feedback, Questions?

Any form of feedback and questions are welcome! Please create an issue 💭 here.