Skip to main content

FastAPI Toolbox

中文文档 | English

A Python library that provides common utilities and features for FastAPI development, including static file cache control and advanced logging system.

Installation

uv add fastapi-toolbox
pip install fastapi-toolbox

Or install directly from GitHub:

uv add git+https://github.com/wynemo/fastapi-utils.git
pip install git+https://github.com/wynemo/fastapi-utils.git

Features

Running Server

fastapi-toolbox provides an advanced logging system based on loguru, supporting log configuration in multi-process environments.

Basic Usage

from fastapi import FastAPI
from fastapi_toolbox import logger, run_server
import uvicorn
import logging

app = FastAPI()

@app.get("/")
async def read_root():
    logger.info("Hello World accessed")
    return {"Hello": "World"}

if __name__ == "__main__":

    def filter_sqlalchemy(record):
        if record.name.startswith("sqlalchemy"):
            if record.levelno < logging.ERROR:
                return True

    run_server(
        "main:app",
        host="127.0.0.1",
        port=8000,
        workers=1,
        log_file="logs/app.log", # Log rotation
        filter_callbacks=[filter_sqlalchemy],
        reload=True  # Enable hot reload (development only)
    )

Hot Reload Mode

The reload parameter enables automatic server restart when code changes are detected. This is useful during development:

run_server(
    "main:app",
    host="127.0.0.1",
    port=8000,
    reload=True,  # Enable hot reload
    reload_dirs=["src"],  # Optional: specify directories to watch
)

Note:

  • Hot reload mode uses fork internally, which differs from multi-process mode (workers >= 2) that uses spawn
  • File logging behaves differently in reload mode to avoid multiple processes writing to the same file
  • Do not use reload=True in production

Environment Variable Configuration

  • LOG_LEVEL: Set log level (DEBUG, INFO, WARNING, ERROR), defaults to INFO
  • JSON_LOGS: Set to "1" to enable JSON format logs, defaults to standard format

Key Features

  • Multi-process Support: UvicornConfig ensures logs work properly in multi-process environments
  • Auto Rotation: Supports log rotation by file size and time
  • Unified Interception: Automatically intercepts standard library logging and forwards to loguru
  • Flexible Configuration: Supports environment variables and code configuration

StaticFilesCache

StaticFilesCache is an enhanced version of FastAPI StaticFiles, providing configurable cache control for static files.

Basic Usage

from fastapi import FastAPI
from fastapi_toolbox import StaticFilesCache
import os

app = FastAPI()

# Example 1: Using default cache policy (cache disabled)
front_folder = os.path.join(os.path.dirname(__file__), "frontend/dist")
app.mount("/", StaticFilesCache(directory=front_folder), name="static")

# Example 2: Using custom cache policy
app.mount("/static", StaticFilesCache(
    directory="static_files",
    cachecontrol="max-age=3600"  # Cache for 1 hour
), name="static")

Key Features

  • Auto Cache Control: Automatically adds Cache-Control response headers for .html and .txt files
  • Configurable Policy: Customize cache behavior via cachecontrol parameter
  • Full Compatibility: Inherits from FastAPI StaticFiles, retaining all original functionality

Parameters

Parameter Description Default
directory Static files directory path Required
cachecontrol Cache-Control header value "no-cache, no-store, must-revalidate"
Other parameters Same as standard StaticFiles -

Common Cache Strategies

# Disable cache (suitable for development)
cachecontrol="no-cache, no-store, must-revalidate"

# Short-term cache (suitable for frequently updated resources)
cachecontrol="max-age=3600"  # 1 hour

# Long-term cache (suitable for rarely changed resources)
cachecontrol="public, max-age=86400"  # 1 day

# Private cache, must revalidate
cachecontrol="private, must-revalidate"

Practical Use Cases

Suitable for scenarios where you need to serve static files for frontend SPA applications:

# Access http://127.0.0.1:8000/index.html to view the frontend page
front_folder = os.path.join(os.path.dirname(__file__), "frontend/dist")
app.mount("/", StaticFilesCache(directory=front_folder), name="static")

With this configuration, HTML files will not be cached by the browser, ensuring users always get the latest version of the frontend application.

NextJSRouteMiddleware

NextJSRouteMiddleware is a middleware for handling Next.js static export routes. When a request returns 404, it attempts to find the corresponding .html file.

Basic Usage

from fastapi import FastAPI
from fastapi_toolbox import NextJSRouteMiddleware

app = FastAPI()

# Add middleware
app.add_middleware(
    NextJSRouteMiddleware,
    static_dir="frontend/dist",
    skip_prefixes=["/api", "/static", "/docs", "/openapi.json", "/redoc"],
)

Parameters

Parameter Description Default
static_dir Static files directory path Required
skip_prefixes List of path prefixes to skip processing []
index_file Default filename for root path (without extension) "index"

How It Works

  1. Requests matching skip_prefixes are passed through directly
  2. Other requests are processed normally
  3. If 404 is returned and path doesn't start with /_next, it looks for the corresponding .html file
  4. For example: /about → looks for frontend/dist/about.html
  5. Root path / → looks for frontend/dist/index.html

Practical Example

from fastapi import FastAPI
from fastapi_toolbox import NextJSRouteMiddleware, StaticFilesCache
import os

app = FastAPI()

front_folder = os.path.join(os.path.dirname(__file__), "frontend/dist")

# Add Next.js route middleware
app.add_middleware(
    NextJSRouteMiddleware,
    static_dir=front_folder,
    skip_prefixes=[
        "/api",
        "/static",
        "/_next",
        "/docs",
        "/openapi.json",
        "/redoc",
        "/favicon.ico",
    ],
)

# Mount static files
app.mount("/", StaticFilesCache(directory=front_folder), name="static")

Settings

Settings is a configuration class based on pydantic-settings that supports loading configuration from environment variables or .env files.

Basic Usage

from fastapi_toolbox import Settings, settings

# Use the default settings instance (automatically loads from environment variables or .env)
print(settings.DATABASE_URL)

# Or create a custom Settings class
class MySettings(Settings):
    DATABASE_URL: str = "postgresql://user:pass@localhost:5432/mydb"
    API_KEY: str = "default-key"

my_settings = MySettings()

Key Features

  • Environment Variable Support: Automatically loads from environment variables
  • .env File Support: Automatically reads .env files
  • Inheritance Friendly: Easily extend with custom configuration fields
  • Type Safe: Full Pydantic validation and type checking

Database

fastapi-toolbox provides a set of database utilities based on SQLModel, making it easy to integrate databases into your FastAPI application.

Basic Usage

from fastapi import FastAPI, Depends
from fastapi_toolbox import init_database, get_session, create_db_and_tables
from sqlmodel import Session, SQLModel, Field

app = FastAPI()

# Define your models
class User(SQLModel, table=True):
    id: int = Field(primary_key=True)
    name: str
    email: str

# Initialize database on startup
@app.on_event("startup")
def on_startup():
    init_database(database_url="sqlite:///./test.db")
    create_db_and_tables()

# Use dependency injection to get database sessions
@app.get("/users")
def get_users(session: Session = Depends(get_session)):
    return session.exec(select(User)).all()

@app.post("/users")
def create_user(user: User, session: Session = Depends(get_session)):
    session.add(user)
    session.commit()
    session.refresh(user)
    return user

Configuration Methods

init_database supports three configuration methods (in order of priority):

from fastapi_toolbox import Settings, init_database

# Method 1: Pass database_url directly
init_database(
    database_url="postgresql://user:pass@localhost:5432/mydb",
    echo=True,  # Enable SQL logging
    pool_size=10
)

# Method 2: Use custom Settings instance
class MySettings(Settings):
    DATABASE_URL: str = "postgresql://user:pass@prod:5432/prod_db"

my_settings = MySettings()
init_database(settings_instance=my_settings)

# Method 3: Use default settings (reads from .env or environment variables)
# Set DATABASE_URL in .env or environment
init_database()

Available Functions

Function Description
init_database() Initialize database engine with flexible configuration options
get_engine() Get the database engine instance (auto-initializes if needed)
get_session() Dependency injection function for database sessions
create_db_and_tables() Create all tables based on SQLModel models

Build

uv build

Publish

uv publish

Enter __token__ as username and then enter your PyPI token

License

MIT

Metadata

Release files for fastapi-toolbox 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fastapi-toolbox 0.7.1
File Size Uploaded Provenance Actions
fastapi_toolbox-0.7.1.tar.gz 59.7 kB Without provenance Details for fastapi_toolbox-0.7.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fastapi-toolbox 0.7.1
File Interpreter ABI Platform Actions
fastapi_toolbox-0.7.1-py3-none-any.whl Python 3 none any Details for fastapi_toolbox-0.7.1-py3-none-any.whl

Total release size: 75.1 kB

Release files / fastapi_toolbox-0.7.1.tar.gz

Download URL fastapi_toolbox-0.7.1.tar.gz
Size 59.7 kB
Tags Source
SHA-256 checksum
How to use checksums
4e04f4ffd3516c3a39a606d7f5d8878513a7088ad754e83ac5352c6eef4c2cd7
BLAKE2b-256 checksum
How to use checksums
9e94aa51ad995316731bd09d81bbce52a2ea140539fcbfcd58d2dbefd7bb41a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / fastapi_toolbox-0.7.1-py3-none-any.whl

Download URL fastapi_toolbox-0.7.1-py3-none-any.whl
Size 15.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f7be169943aaa44277448a8d02a9ef3957acd4a979cd0d3fd0a2b9d385ec115e
BLAKE2b-256 checksum
How to use checksums
e6d045cbea185a8f23ffa8f0952de6919548b88ed6b42384ff374c44f4430fb8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for fastapi-toolbox 0.7.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page