III API base

III FastAPI Common base
Go to pypi now

Usage

Config

The later config will override the previous one.

This table shows the predefined environment variables.

from pathlib import Path

from api_helper.config import load_config

# Load config
load_config(Path(__file__).parent / ".env")

# Load default config in the directory (.env)
load_config(Path(__file__).parent)

FastAPI example

To config the FastAPI by env, read the Config section.

from pathlib import Path

from api_helper import FastAPI, success_response

app: FastAPI = FastAPI(base_folder=Path(__file__).parent)
# Optional to setup sentry
app.setup_sentry("sentry_dsn")


@app.get("/")
def home():
    return success_response("Hello, World!")


# Start the app and enjoy
app.run("127.0.0.1", 5000)

# Start the app with OpenAPI, for example
app.run(show_swagger=True)

Use FastAPI with auto-reload

To use the reload method, you need to pass reload=True and app="main:app" to the run method.
If you don't pass them, the reload will not work. See the sample code below.

from pathlib import Path

from api_helper import FastAPI

# Must declared before running into main code block
app: FastAPI = FastAPI(base_folder=Path(__file__).parent.parent)

if __name__ == "__main__":
    # Pass the app as a string to uvicorn.run to enable auto-reload
    app.run(app="test:app", reload=True)

Custom Logger Format

If you want to customize the Logger format, you can pass log_builder to the FastAPI object.
The following example shows how to customize the logger format.
See below sample for more information.

from pathlib import Path

from api_helper import FastAPI
from api_helper.config import LoggerBuilder

# To customize the logger format, you can pass the log_builder to FastAPI
log_builder: LoggerBuilder = LoggerBuilder(Path(__file__).parent)
log_builder.formatters = {}  # For example, we change the formatter to empty
app: FastAPI = FastAPI(base_folder=Path(__file__).parent, log_builder=log_builder)

# Or if you prefer the default, you can extend the default formatter
# For example, you can change the root level to DEBUG with default formatter
log_builder: LoggerBuilder = LoggerBuilder(Path(__file__).parent, config={"root": {"level": "DEBUG"}})
app: FastAPI = FastAPI(base_folder=Path(__file__).parent, log_builder=log_builder)

# Or pass as parameter start with the `logging_` keyword, it will be passed to the LoggerBuilder
# It is the same as the previous example
app: FastAPI = FastAPI(base_folder=Path(__file__).parent, logging_config={"root": {"level": "DEBUG"}})

Response

Expose the SuccessModel and ErrorModel to represent the response.

sample:

from api_helper.generic import SuccessModel
from api_helper import success_response
from fastapi import Response


# Basic usage
@route.get("/", response_model=SuccessModel)
def get() -> Response:
    return success_response("Hello, World!")


# If you have custom data, you can pass it to the success_response
@route.get("/", response_model=SuccessModel[list[User]])
def get() -> Response:
    return success_response(session.exec(select(User)).all())


# If you use paginate
@route.get("/items", response_model=SuccessModel[Pagination[User]])
def list_items() -> Response:
    return success_response(paginate(session=session, query=select(User)))

Database

Alembic

The Alembic class is an easy way to check Alembic status by code.
You can use the Alembic class to check the Alembic status.

properties:

• current: The current revision. If not current, return empty string.
• head: The head revision. If not head, return empty string.
• upgradeable: If the current is not head, return True.
• scrip_direrctory: The ScriptDirectory object, used by alembic.

functions:

• get_config(): Get the Alembic config object. You can pass it to alembic env.py file.
• upgrade(): Upgrade to the revision, if not provided, it will upgrade to the head.

SQLModel Pagination

To reduce the boilerplate code, you can use the paginate function to get the pagination object.

parameters:

• session: The session object from the database.
• query: The query object from the database. It can use where, limit, offset, etc.
• page: The page number, default is 1.
• per_page: The number of items per page, default is 10.

sample code:

from api_helper.database import paginate
from sqlmodel import SQLModel


# For example, you have a SQLModel
class User(SQLModel, table=True):
    id: int
    name: str


# You can use the paginate function to get the pagination
# The paginate function will return the pagination object
pagination = paginate(session=session, query=select(User))

# You will get something like this
{
    "items": [],
    "pagination": {
        "total": 0,
        "page": 1,
        "pages": 1,
        "per_page": 10,
        "prev": None,
        "next": None,
    }
}

For fastAPI routes, you can also use common_query as a quick dependency.

from api_helper import success_response
from api_helper.database import common_query
from api_helper.database import paginate
from api_helper.types import PaginateQuery

from fastapi import Depends
from fastapi import Response

@route.get("/sample")
def list_items(
    *,
    session: Session = Depends(get_session),
    # Here, we use common_query as a dependency, it provides the page and per_page query
    page_query: PaginateQuery = Depends(common_query),
) -> Response:
    return success_response(
        paginate(session=session, query=select(DiffItem), page=page_query.page, per_page=page_query.per_page)
    )

Changelogs

0.1.4

bugs:

• Fix MRO error on UUIDModel and TimestampModel.

Breaking changes:

• Rename database.model to database.mixin and related class names.

0.1.3

feat:

• Add UUIDModel, TimestampModel for sqlmodel more easier to use.

0.1.2

feat:

• Add common_query function for common use query. It can use like normal Depends.

0.1.1

bugs:

• alembic object won't get the sql_str property correctly.

0.1.0

Feats:

• Add new alembic class for easier to get alembic status, see the Alembic section for more information.
• Add paginate function for those who use SQLmodel, see the SQLModel section for more information.
• Add SuccessModel and ErrorModel for easier to return the response, see the Response section for more information.
• Add Singleton pattern to avoid multiple instances.

Chore:

• Move errors into module.
• Update database requirements.