Forem: David Landup

How to Access the Request Object in Mitsuki Controllers

David Landup — Sun, 14 Dec 2025 14:26:36 +0000

In Mitsuki, you'd usually work abstractions like @QueryParam and RequestBody that handle the details of HTTP requests for you. However, sometimes you need to access the raw request object to read headers, inspect client details, or manage cookies.

This guide shows you how to directly access the underlying starlette.requests.Request object in your controller methods.

The `Request` Type Hint

The easiest way to get the request object is to add a parameter to your controller method and type-hint it as Request. Mitsuki's dependency injection system will automatically provide the object for you.

Here’s how you can inject the request to read its properties:

from mitsuki import RestController, GetMapping
from starlette.requests import Request

@RestController("/api")
class HomeController:
    @GetMapping("/info")
    # The : Request type-hinted object is resolved via Mitsuki's DI
    async def get_request_info(self, request: Request) -> dict:
        return {
            "user_agent": request.headers.get("User-Agent", "Unknown"),
            "client_host": request.client.host,
            "client_port": request.client.port,
            "cookies": request.cookies,
            "path": request.url.path,
        }

Because Mitsuki is built on Starlette, the injected object is a standard starlette.requests.Request instance, giving you access to its features.

Combining with Other Parameters

Injecting the request object doesn't interfere with Mitsuki's other features. You can combine it with path variables, query parameters, and request bodies:

from mitsuki import RestController, GetMapping, QueryParam
from starlette.requests import Request

@RestController("/api/users")
class UserController:
    @GetMapping("/{user_id}")
    async def get_user_and_log_ip(
        self,
        request: Request,
        user_id: int,
        verbose: bool = QueryParam(default=False)
    ) -> dict:
        # Log the client's IP address for auditing purposes... or whatever.
        logger.info(f"Request for user {user_id} received from IP: {request.client.host}")

        # Your regular business logic
        user = await self.service.get_user(user_id)

        return user

Next Steps

Explore the docs: For more on how requests are being handled, controllers work, etc. check out the official Mitsuki Controllers documentation.

Happy coding! ❀

Guide to Path Variables and Query Parameters in Mitsuki Controllers

David Landup — Sat, 29 Nov 2025 13:34:02 +0000

How to Handle URL Parameters in Mitsuki Controllers

A guide to reading path variables and query parameters with automatic type conversion.

Mitsuki

Mitsuki, is a web development framework, focused on bringing enterprise strength without the enterprise pain to Python.

It's opinionated, lightweight and performant.

Introduction

REST APIs usually involve reading dynamic data directly from the URL.

This data generally comes in two forms:

Path variables: which identify a specific resource (e.g., /posts/some_id)
Query parameters: which are usually used for sorting or filtering collections (e.g., /posts?popular=true).

Mitsuki makes handling both of these trivial and type-safe, allowing you to define complex URL-based data retrieval with minimal code.

Setup

For the purposes of this guide, let's create a simple Post entity, a @CrudRepository to access its data, and a @Service to contain our business logic:

from dataclasses import dataclass
from typing import List, Optional
from mitsuki import Entity, Id, CrudRepository, Service

# 1. The Entity: Defines the Post data model
@Entity()
@dataclass
class Post:
    id: int = Id()
    title: str = ""
    published: bool = True

# 2. The Repository: The data access layer for Posts
@CrudRepository(entity=Post)
class PostRepository:
    # Gets standard CRUD methods automatically.
    async def find_by_published(self, published: bool) -> List[Post]: ...

    # For custom filtering with pagination, we use @Query
    @Query("""
        SELECT p FROM Post p
        WHERE p.title LIKE :title_pattern AND p.published = :published
        ORDER BY p.id DESC
    """)
    async def search_paginated(self, title_pattern: str, published: bool, limit: int, offset: int) -> List[Post]: ...

# 3. The Service: Contains business logic
@Service()
class PostService:
    def __init__(self, repo: PostRepository):
        # Mitsuki automatically injects the PostRepository here
        self.repo = repo

    async def get_by_id(self, post_id: int) -> Optional[Post]:
        return await self.repo.find_by_id(post_id)

    async def search(self, q: str, published: bool, page: int, size: int) -> List[Post]:
        offset = page * size
        return await self.repo.search_paginated(
            title_pattern=f"%{q}%",
            published=published,
            limit=size,
            offset=offset
        )

Path Variables: Accessing Resource Identifiers

Path variables are used to capture parts of the URL path, most commonly for resource IDs. You define a path variable in your mapping decorator with curly braces {} and accept it as an argument in your controller method.

Let's create an endpoint to fetch a specific post by its ID:

from mitsuki import RestController, GetMapping
from typing import Optional
from ..services.post_service import PostService
from ..domain.post import Post

@RestController("/api/posts")
class PostController:
    def __init__(self, post_service: PostService):
        # The PostService is automatically injected by Mitsuki's DI container
        self.post_service = post_service

    @GetMapping("/{post_id}")
    async def get_post_by_id(self, post_id: int) -> Optional[Post]:
        print(f"Fetching post with ID: {post_id}")
        print(f"Type of post_id is: {type(post_id)}")

        post = await self.post_service.get_by_id(post_id)

        return post

There are two key things happening here:

Name Matching: Mitsuki automatically matches the {post_id} in the path to the post_id argument in the method.
Automatic Type Conversion: By type-hinting post_id: int, you tell Mitsuki to convert the incoming path segment from a string to an integer. If a client requests /api/posts/abc, Mitsuki will automatically respond with a 400 Bad Request error because "abc" cannot be converted to an integer.

Query Parameters: Filtering and Sorting

Query parameters are the key-value pairs that appear after the ? in a URL. They are ideal for optional filters, search queries, or pagination controls.

To read query parameters, you use the @QueryParam decorator on your method arguments. Let's add a search endpoint to our PostController.

# Continuing inside the PostController class...
from mitsuki import QueryParam

@GetMapping("/search")
async def search_posts(
    self,
    q: str = QueryParam(required=True),
    published: bool = QueryParam(default=True),
    page: int = QueryParam(default=0),
    size: int = QueryParam(default=10)
) -> List[Post]:
    # Example Request: /api/posts/search?q=mitsuki&published=true&page=0&size=20
    #
    # q: "mitsuki" (required string)
    # published: True (boolean, defaults to True)
    # page: 0 (integer, defaults to 0)
    # size: 20 (integer, defaults to 10)

    posts = await self.post_service.search(q, published, page, size)
    return posts

Let's break down how @QueryParam works:

Required Parameter: q: str = QueryParam(required=True) explicitly marks the q parameter as mandatory. If a client makes a request without it, Mitsuki will automatically return a 400 Bad Request error with a descriptive message.
Optional Parameter with Default: published: bool = QueryParam(default=True) is optional. If the published parameter is missing from the URL, its value will be True. The type hint ensures that values like "true", "1", or "on" are correctly converted to the boolean True.
Optional Parameter defaulting to None: If you were to define a parameter as size: Optional[int] = QueryParam(default=None), it would default to None if not provided. A plain QueryParam() also creates an optional parameter that defaults to None.

Next Steps

You've seen how Mitsuki's declarative approach makes it easy to read and validate data from a URL. This type-safe mechanism helps prevent common bugs and cleans up your controller logic.

Explore the docs: For a full list of available decorators and validation options, see the official Controllers & Request Handling documentation.
Handle Request Bodies: Now that you can read data from a URL, learn how to handle data sent in the request body by reading our guide to @RequestBody.

Happy coding! ❀

Guide to Mitsuki Repositories: From Zero to Full CRUD

David Landup — Sat, 29 Nov 2025 06:34:42 +0000

Introduction

The data access layer is the foundation of web applications, sitting at the bottom of the layered architectures that power enterprise code.

Mitsuki's data layer, centered around the @CrudRepository decorator, is designed to help you prototype in early stages as well as orchestrate more complex queries down the line, maximizing your time to focus on business logic. It allows you to define a complete, high-performance data access layer by writing a simple interface, letting the framework handle the implementation.

In this guide, you'll learn how to go from a simple interface to a data access layer, starting with zero-code CRUD and progressively adding more complex logic with Query DSL, native SQL, and custom SQLAlchemy queries.

Mitsuki

Mitsuki, is a web development framework, focused on bringing enterprise strength without the enterprise pain to Python.

It's opinionated, lightweight and performant.

Domain Objects - `@Entity`

Before any repository, we need a data model for that repository (i.e. an object that maps onto a database table).

In Mitsuki, this is a @dataclass decorated with @Entity. It tells Mitsuki that this object maps to a database table:

from dataclasses import dataclass
from mitsuki import Entity, Id, Column

@Entity()
@dataclass
class User:
    id: int = Id()
    name: str = ""
    email: str = Column(unique=True, default="")
    active: bool = True

This simple class is all we need to define the users table, complete with an auto-incrementing id, a name, a unique email, and an active status.

Alternatively, you can use a UUID:

from dataclasses import dataclass
from mitsuki import Entity, UUIDv7, Column

@Entity()
@dataclass
class User:
    id: int = UUIDv7()
    name: str = ""
    email: str = Column(unique=True, default="")
    active: bool = True

With support for UUIDv1, UUIDv4, UUIDv5, UUIDv7.

Level 1: Zero-Code CRUD with `@CrudRepository`

To get a fully functional (basic) data access layer for our User entity, we only need to define an empty class decorated with @CrudRepository:

from mitsuki import CrudRepository
from ..models.user import User

@CrudRepository(entity=User)
class UserRepository:
    """
    A complete data access layer for the User entity.
    All methods listed below are automatically implemented.
    """
    pass

By simply defining this interface, UserRepository is instantly equipped with a full suite of asynchronous CRUD methods:

Method Signature	Description
`save(entity: User) -> User`	Creates or updates a user.
`find_by_id(id: int) -> User	None`
`find_all(page, size, sort_by, sort_desc)`	Finds all users, with optional pagination and sorting.
`delete(entity: User) -> None`	Deletes a user object from the database.
`delete_by_id(id: int) -> None`	Deletes a user by their primary key.
`count() -> int`	Returns the total number of users.
`exists_by_id(id: int) -> bool`	Checks if a user with the given ID exists.

You can inject this repository into a service and use these methods immediately, with no implementation required:

from mitsuki import Service
from ..repositories.user_repository import UserRepository

@Service()
class UserService:
    def __init__(self, repo: UserRepository):
        self.repo = repo

    async def create_new_user(self, name: str, email: str) -> User:
        new_user = User(name=name, email=email)
        # The .save() method is provided by @CrudRepository
        return await self.repo.save(new_user)

Level 2: Query DSL

What about custom queries? For common WHERE clauses, you don't need to write SQL. Mitsuki includes a Query DSL (Domain-Specific Language) that generates queries by parsing method names.

You just define the method signature in your repository; Mitsuki provides the implementation:

from typing import List, Optional
from mitsuki import CrudRepository
from ..models.user import User

@CrudRepository(entity=User)
class UserRepository:
    # Translates to: SELECT * FROM user WHERE email = ?
    async def find_by_email(self, email: str) -> Optional[User]: ...

    # Translates to: SELECT * FROM user WHERE active = ?
    async def find_by_active(self, active: bool) -> List[User]: ...

    # You can combine fields and operators
    # Translates to: SELECT * FROM user WHERE active = ? AND age > ?
    async def find_by_active_and_age_greater_than(
        self, active: bool, age: int
    ) -> List[User]: ...

    # Also works for counting and checking existence
    # Translates to: SELECT COUNT(*) FROM user WHERE active = ?
    async def count_by_active(self, active: bool) -> int: ...

This declarative approach is simple, readable, and covers a wide range of common query patterns without a single line of SQL.

Level 3: Taking Control with `@Query`

For queries that are too complex or long for the Query DSL, the @Query decorator gives you full control to write your own SQL.

Mitsuki supports two syntaxes:

SQLAlchemy ORM-style
Native SQL

SQLAlchemy ORM-style Syntax (Default)

This syntax queries your Entities and attributes, not your database tables and columns. It's the recommended approach as it's database-agnostic and less prone to errors if you happen to change your column names:

from mitsuki import Query

@CrudRepository(entity=User)
class UserRepository:
    # ... other methods

    @Query("""
        SELECT u FROM User u
        WHERE u.age BETWEEN :min_age AND :max_age
        AND u.active = :active
        ORDER BY u.name
    """)
    async def find_active_in_age_range(
        self, min_age: int, max_age: int, active: bool = True
    ) -> List[User]: ...

FROM User u: We select from the User entity, aliased as u.
WHERE u.age: We filter on the .age attribute of the entity.
:min_age: Named parameters in the query are automatically mapped to the method's arguments.

Native SQL Syntax

If you need to use a database-specific feature or prefer writing raw SQL, you can use native=True. This queries the database tables and columns directly:

from mitsuki import Query

@CrudRepository(entity=User)
class UserRepository:
    # ... other methods

    # Example using a PostgreSQL-specific function
    @Query("""
        SELECT * FROM "user"
        WHERE email ILIKE :pattern
        AND created_at > NOW() - INTERVAL '30 days'
    """, native=True)
    async def find_by_email_pattern(self, pattern: str) -> List[User]: ...

FROM "user": We select from the actual database table named user.
ILIKE: A PostgreSQL-specific operator for case-insensitive pattern matching.

Level 4: Custom SQLAlchemy Methods

For the highest level of control, especially for dynamically constructed queries, you can simply write a complete method implementation using SQLAlchemy Core, similar to how you would in Flask or FastAPI.

Every repository provides a self.get_connection() method that gives you direct, managed access to a SQLAlchemy connection:

from sqlalchemy import select, and_
from mitsuki.data import get_database_adapter

@CrudRepository(entity=User)
class UserRepository:
    # ... other methods

    async def find_dynamically(
        self, name_pattern: Optional[str], min_age: Optional[int]
    ) -> List[User]:
        """Builds a query dynamically based on which filters are provided."""
        adapter = get_database_adapter()
        user_table = adapter.get_table(User)

        query = select(user_table)
        conditions = []

        if name_pattern:
            conditions.append(user_table.c.name.like(f"%{name_pattern}%"))
        if min_age is not None:
            conditions.append(user_table.c.age >= min_age)

        if conditions:
            query = query.where(and_(*conditions))

        async with self.get_connection() as conn:
            result = await conn.execute(query)
            # Manually map the results back to User objects
            return [User(**dict(row._mapping)) for row in result.fetchall()]

This approach gives you programmatic access to SQLAlchemy's powerful query builder, allowing for complex, conditional logic that would be difficult to express in a static string.

Conclusion

You've seen how Mitsuki's repositories provide a layered approach to data access.

You can start with zero-effort CRUD, graduate to the expressive Query DSL, and take full control with custom SQL or SQLAlchemy when you need it.

This allows you to be highly productive while never sacrificing power.

Next Steps

Explore the docs: For a full list of supported keywords and operators, check out the official Repositories & Data Layer documentation.
Build on your work: Now that you have a powerful repository, learn how to use it in a @RestController to expose your data via a REST API.

Happy coding! ❀

How to Create Your First Mitsuki REST API from Scratch

David Landup — Sat, 29 Nov 2025 05:48:59 +0000

A step-by-step guide to using the mitsuki init CLI, understanding the generated project, and running your first high-performance web server.

Mitsuki

Mitsuki, is a web development framework, focused on bringing enterprise strength without the enterprise pain to Python.

It's opinionated, lightweight and performant.

Bootstrapping Mitsuki Projects

When you get a spark of inspiration, the first thing that comes to mind isn't boilerplate setup. It's standard, usually the same, and you might even have a project starter skeleton sitting on your device already.

When starting something new - I want to focus on the system design, business logic and value proposition. Thus, I heavily use my own templates.

Let's go from an empty folder to a fully functional, high-performance API in a single minute!

Step 1: Install Mitsuki

Mitsuki is available on PyPI. Installing it will also install the CLI tool:

$ pip install mitsuki

Step 2: mitsuki init 🪄

Let's use the built-in CLI to scaffold a complete project structure.
Run the following command in your terminal:

$ mitsuki init

The CLI will launch an interactive wizard to guide you. Let's create a simple API for a blog:

$ mitsuki init
Application name: blog_api
Description (optional): API for my new blog
Database type [sqlite/postgresql/mysql] (sqlite):
Create starter domain? [Y/n]: y
Domain name (e.g., User, Product): Post
Add another domain? [y/N]: n

Successfully created Mitsuki application: blog_api

You can immediately spin it up and fire requests to it:

python3 -m blog_api.src.app

Starts the server:

2025-11-29 10:30:15,132 - mitsuki - INFO     -
2025-11-29 10:30:15,132 - mitsuki - INFO     -     ♡ ｡ ₊°༺❤︎༻°₊ ｡ ♡
2025-11-29 10:30:15,132 - mitsuki - INFO     -               _ __             __   _
2025-11-29 10:30:15,132 - mitsuki - INFO     -    ____ ___  (_) /________  __/ /__(_)
2025-11-29 10:30:15,132 - mitsuki - INFO     -   / __ `__ \/ / __/ ___/ / / / //_/ /
2025-11-29 10:30:15,132 - mitsuki - INFO     -  / / / / / / / /_(__  ) /_/ / ,< / /
2025-11-29 10:30:15,132 - mitsuki - INFO     - /_/ /_/ /_/_/\__/____/\__,_/_/|_/_/
2025-11-29 10:30:15,132 - mitsuki - INFO     -     °❀˖ ° °❀⋆.ೃ࿔*:･  ° ❀˖°
2025-11-29 10:30:15,132 - mitsuki - INFO     -
2025-11-29 10:30:15,132 - mitsuki - INFO     - :: Mitsuki ::                (v0.1.3)
2025-11-29 10:30:15,132 - mitsuki - INFO     -
2025-11-29 10:30:15,133 - _granian - INFO     - Starting granian...
2025-11-29 10:30:15,139 - _granian - INFO     - Listening at: http://127.0.0.1:8000

And you can just send requests to it:

curl -X POST http://localhost:8000/api/post \
-H "Content-Type: application/json" \
-d '{}'

The API will respond with the newly created post, complete with a uuid, created_at, and updated_at timestamp:

{
  "id": "018ecb71-d556-7000-8000-000000000001",
  "created_at": "2025-11-29T10:35:00.123456",
  "updated_at": "2025-11-29T10:35:00.123456"
}

However - it's worth taking a look at what's inside first, customizing your Post domain object, and understanding the structure first.

Step 3: Anatomy of a Mitsuki Project

While you can really have any structure you want in a Mitsuki project, a sensible default structure is baked into the scaffold.

Let's pop the hood and see what mitsuki init created for us inside the blog_api directory:

blog_api/
  blog_api/
    src/
      controller/       # 🚪 The front door for your API requests
      domain/           # 🏗️ The blueprint for your data (Post)
      repository/       # 🗄️ The bridge that talk to your database
      service/          # 🧠 The brain where your business logic lives
      app.py            # ❤️ The heart of your application
      __init__.py
    __init__.py
  application.yml       # ⚙️ The main control panel for settings
  application-dev.yml   # 🛠️ Settings for your development environment
  application-prod.yml  # 🚀 Settings for production
  .gitignore
  README.md

What's Inside? Fully Functional API

This isn't just a collection of empty folders; it's a fully wired application.

The Post domain you specified in the beginning was created, with a corresponding RestController, Service, and CrudRepository -giving you a working CRUD API right out of the box.

Your PostController controller imports your PostService and exposes endpoints to create posts, return existing ones, and delete them:

import uuid
from typing import List
from mitsuki import RestController, GetMapping, PostMapping, DeleteMapping, QueryParam
from ..service.post_service import PostService


@RestController("/api/posts")
class PostController:
    """REST API controller for Post resources."""

    def __init__(self, service: PostService):
        self.service = service

    @GetMapping("")
    async def list_all(
        self,
        page: int = QueryParam(default=0),
        size: int = QueryParam(default=100)
    ):
        """GET /api/posts?page=0&size=100"""
        return await self.service.get_all(page=page, size=size)

    @GetMapping("/{id}")
    async def get_by_id(self, id: str):
        """GET /api/posts/123e4567-e89b-12d3-a456-426614174000"""
        entity = await self.service.get_by_id(uuid.UUID(id))
        if not entity:
            return {"error": "Not found"}, 404
        return entity

    @PostMapping("")
    async def create(self, body: dict):
        """POST /api/posts"""
        entity = await self.service.create()
        return entity, 201

    @DeleteMapping("/{id}")
    async def delete(self, id: str):
        """DELETE /api/posts/123e4567-e89b-12d3-a456-426614174000"""
        deleted = await self.service.delete(uuid.UUID(id))
        if not deleted:
            return {"error": "Not found"}, 404
        return {"success": True}

Your Post @Entity, contains only the ID, created_at and updated_at fields. Don't forget to add other fields you want here, like a body, or title:

import uuid
from dataclasses import dataclass
from datetime import datetime
from mitsuki import Entity, UUIDv7, Field


@Entity()
@dataclass
class Post:
    """Post domain object."""
    id: uuid.UUID = UUIDv7()
    created_at: datetime = Field(update_on_create=True)
    updated_at: datetime = Field(update_on_save=True)

Your PostRepository contains all the CRUD implementations by default in Mitsuki, as well as pointers for Query DSL, and custom query methods:

from typing import Optional, List
from mitsuki import CrudRepository, Query, Modifying
from ..domain.post import Post


@CrudRepository(entity=Post)
class PostRepository:
    """
    Repository for Post entities.

    Auto-implemented CRUD methods (you can just call these as-is):
    - save(entity) - Create or update
    - find_by_id(id) - Find by primary key
    - find_all(page, size, sort_by, sort_desc) - Paginated query
    - delete(entity) - Delete entity
    - delete_by_id(id) - Delete by ID
    - count() - Count all entities
    - exists_by_id(id) - Check existence

    Auto-generated query methods (define signature only):
    Examples:
        async def find_by_name(self, name: str) -> Optional[Post]: ...
        async def find_by_status(self, status: str) -> List[Post]: ...
        async def find_by_created_at_greater_than(self, created_at) -> List[Post]: ...

    Custom @Query methods:
        @Query("SELECT e FROM Post e WHERE e.status = :status ORDER BY e.created_at DESC")
        async def find_active_sorted(self, status: str) -> List[Post]: ...

    Custom @Modifying queries (UPDATE/DELETE):
        @Modifying
        @Query("UPDATE Post SET status = :status WHERE id = :id")
        async def update_status(self, id: int, status: str) -> int: ...

    Custom methods with direct database access:
        async def custom_complex_query(self, param: str) -> List[dict]:
            async with self.connection as conn:
                result = await conn.execute("SELECT * FROM table WHERE field = :param", {"param": param})
                return [dict(row) for row in result]
    """

    # Add your custom query methods here
    pass

And your PostService, where your business logic lives, currently just wraps the repository for database operations. Add your business-specific logic here:

import uuid
from typing import List, Optional
from mitsuki import Service
from ..domain.post import Post
from ..repository.post_repository import PostRepository


@Service()
class PostService:
    """Service layer for Post business logic."""

    def __init__(self, repo: PostRepository):
        self.repo = repo

    async def get_all(self, page: int = 0, size: int = 100) -> List[Post]:
        """Get all posts with pagination"""
        return await self.repo.find_all(page=page, size=size)

    async def get_by_id(self, id: uuid.UUID) -> Optional[Post]:
        """Get post by ID"""
        return await self.repo.find_by_id(id)

    async def create(self) -> Post:
        """Create new post"""
        entity = Post(id=None)
        return await self.repo.save(entity)

    async def delete(self, id: uuid.UUID) -> bool:
        """Delete post by ID"""
        exists = await self.repo.exists_by_id(id)
        if not exists:
            return False
        await self.repo.delete_by_id(id)
        return True

Step 4: Liftoff! Running Your Server 🚀

Time to spin up the server:

cd blog_api
python3 -m blog_api.src.app

You'll be greeted by the Mitsuki startup log:

2025-11-29 10:30:15,132 - mitsuki - INFO     -
2025-11-29 10:30:15,132 - mitsuki - INFO     -     ♡ ｡ ₊°༺❤︎༻°₊ ｡ ♡
2025-11-29 10:30:15,132 - mitsuki - INFO     -               _ __             __   _
2025-11-29 10:30:15,132 - mitsuki - INFO     -    ____ ___  (_) /________  __/ /__(_)
2025-11-29 10:30:15,132 - mitsuki - INFO     -   / __ `__ \/ / __/ ___/ / / / //_/ /
2025-11-29 10:30:15,132 - mitsuki - INFO     -  / / / / / / / /_(__  ) /_/ / ,< / /
2025-11-29 10:30:15,132 - mitsuki - INFO     - /_/ /_/ /_/_/\__/____/\__,_/_/|_/_/
2025-11-29 10:30:15,132 - mitsuki - INFO     -     °❀˖ ° °❀⋆.ೃ࿔*:･  ° ❀˖°
2025-11-29 10:30:15,132 - mitsuki - INFO     -
2025-11-29 10:30:15,132 - mitsuki - INFO     - :: Mitsuki ::                (v0.1.3)
2025-11-29 10:30:15,132 - mitsuki - INFO     -
2025-11-29 10:30:15,133 - _granian - INFO     - Starting granian...
2025-11-29 10:30:15,139 - _granian - INFO     - Listening at: http://127.0.0.1:8000

Step 5: See Your API in Action

Mitsuki automatically generates OpenAPI documentation for your API. No work needed.

Open your browser and navigate to http://localhost:8000/docs:

You'll find an interactive API documentation page where you can see all your endpoints and even test them directly from the browser.

Either through the terminal, or through the API UI, try creating a new post:

curl -X POST http://localhost:8000/api/post \
-H "Content-Type: application/json" \
-d '{}'

The API will respond with the newly created post:

{
  "id": "018ecb71-d556-7000-8000-000000000001",
  "created_at": "2025-11-29T10:35:00.123456",
  "updated_at": "2025-11-29T10:35:00.123456"
}

Your Journey Has Just Begun

In just a minute, you've bootstrapped a complete API with Mitsuki.

Not a "Hello World" app, you have a functional application starter with a database model, a REST API, and interactive documentation.

This is the benefit of convention over configuration. Mitsuki lets you focus on what truly matters: your business logic, and the value you want to deliver.

Next Steps

Ready to learn more?

Dive into the Official Documentation to explore custom queries, dependency injection, and more.
Add new fields to your Post entity in src/domain/post.py.
Implement unique business logic in your PostService at src/service/post_service.py.

Happy coding! ❀

Introducing Mitsuki - Spring Boot Enterprise Patterns and Speed with Python's Flexibility

David Landup — Sat, 29 Nov 2025 05:14:58 +0000

Introduction

Introducing Mitsuki: Spring Boot enterprise patterns meeting Python's flexibility and ecosystem! 🚀🐍

Get started in a single file with just a few lines, or have mitsuki init create your file structure, domain objects, and auto-implement repositories with CRUD operations. ✨

It's a structured way to build web applications/REST APIs, and benefits from assumptions on that structure. You already know the patterns - Mitsuki brings them to your fingertips. 💻

Performance-wise - it brings your Python applications into the range of Java/JS applications on consumer hardware. 📊

Check it out on GitHub :)

Bootstrapping Projects in a Minute - from Zero to Functional Starter

Okay, let's go beyond "Hello World" - how long does it take to go from zero to something more functional? Something with a database connection, a domain object, a repository with CRUD capabilities, service and controller?

About a single minute. ✨

Here's a live example, of starting a Mitsuki project, which includes:

Project setup
Domain object
Entity controller, service and repository with functional CRUD

Gifs don't work here :(
Here's a link.

Automatic OpenAPI Generation

If you like Swagger, Redoc or Scalar - Mitsuki auto-generates all of these for you. You can disable any one of them, have them all, and choose a default UI to show at /docs.

Not a single line is required to get bootstrapped, and you can customize them easily:

Supercharging Data Layer Repositories: Auto-CRUD and Query DSL

Basic CRUD functionality is oftentimes boilerplate, especially in the first couple of steps of development. Basic SQL queries are also highly predictable.

Mitsuki includes Query DSL - which lets you write function names, and infers the SQL from them. Of course, you can also write your own queries in SQL (native), SQL (SQLAlchemy ORM syntax) or SQLAlchemy itself.

Given an @Entity, any @CrudRepository aware of an entity will allow you to just... run CRUD operations on it. save() it, find_by_id(), delete() them - no implementation needed:

@Entity()
@dataclass
class Post:
    id: int = Id()
    title: str = ""
    author: str = ""
    views: int = 0

@CrudRepository(entity=Post)
class PostRepository:
    # Built-in methods (auto-implemented):
    # - find_by_id(id) -> Post | None
    # - find_all(page=0, size=10) -> List[Post]
    # - save(entity: Post) -> Post
    # - delete(entity: Post) -> None
    # - count() -> int
    # - exists_by_id(id) -> bool

Or, you want to find_by_field()? find_by_active_true()? Just define the method names - they get converted into SQL:

@CrudRepository(entity=Post)
class PostRepository:
    # Mitsuki turns these into SQL queries
    async def find_by_email(self, email: str): ...
    async def find_by_username(self, username: str): ...

find_by_email(email) → SELECT * WHERE email = ?
find_by_age_greater_than(age) → SELECT * WHERE age > ?
count_by_status(status) → SELECT COUNT(*) WHERE status = ?

Or just write @Query implementations yourself:

@CrudRepository(entity=Post)
class PostRepository:

    @Query("""
            SELECT u FROM User u
            WHERE u.active = :active
            ORDER BY u.created_at DESC
        """)
    async def find_active_users(self, active: bool, limit: int, offset: int): ...

Or use SQLALchemy:

@CrudRepository(entity=Post)
class PostRepository:
    # Or write custom SQLAlchemy
    async def find_popular_posts(self):
        async with self.get_connection() as conn:
            query = select(Post).where(Post.views > 1000)
            result = await conn.execute(query)
            return [dict(row._mapping) for row in result.fetchall()]

Why Another Web Dev Framework?

I worked in both research and enterprise and have built a lot of services in Python and Java, and they converge to using similar patterns, regardless of how different the architectures and domains are (web apps, ML research, distributed systems, etc.)

After writing a lot of Python, I was missing a framework that strongly supported some of these patterns formally, and find that this structure lets you make assumptions that can really boost dev experience on long term projects.

Microframeworks are great. They let you get started with a single file of a few lines, but (in my opinion) lack the structure you want on long term projects, working with teams, so you end up making that structure yourself anyway. In doing so, you get a small initial boost in productivity, but at the cost of your productivity in the future.

Mitsuki tries to both allow you to start quick and easy with a single file in a few lines, but also be more friendly to you and your team through time, by giving structure to your development process.

Thus, I made an early version of a framework heavily inspired by Spring Boot. The core idea is that you can do enterprise apps without the enterprise pain, in Python, with high performance.

Want a simple REST API? app.py with a few lines.
Want a decent starter with auto-implemented CRUD? mitsuki init to get a starter project with domain classes, services, controllers and repositories.
Performance? Similar to Express and Spring Boot (in Docker, on an M1 MacBook Pro, 8GB of RAM), out of the box, no configuration needed.

Lightweight

Despite the "fancy sounding" terminology, Mitsuki itself is very lightweight, and only adds a very small overhead (10%) over the components that power it (namely, Starlette and Granian). I don't want to commit to ASGI only, and a future version will likely rewrite this core logic to leverage granian further.

There is a lot of ground left to cover, lots of docs to write, examples to explore, features to expand. I'm also planning to write a few tools that leverage the structure of the framework to increase DX within enterprise teams.

But before any of that, I'm looking for feedback.
Yay or nay? :)

Benchmarks

P.S. On the topic of performance and benchmarks, there are a few remarks in the repo's /benchmarks directory. Yes, most benchmarks are arbitrary, heavily gameable, and your bottleneck is likely going to be your business logic, not the framework, anyways. Yes, Spring Boot and Elysia will likely have higher ceilings, so running on a stronger CPU will likely change the order of the benchmark. Yes, there's a million variables that affect these. Yes, granian is written in Rust, not Python.

The point of the benchmark is threefold:

This is the sort of experience you get out of the box, on your device and where you'll deploy it (Dockerized on small instance most likely)
Python web apps can stand shoulder to shoulder with JS/Java performance-wise
Despite the seeming complexity around dependency injection, state tracking, etc., Mitsuki is pretty lightweight.

Forem: David Landup

How to Access the Request Object in Mitsuki Controllers

The Request Type Hint

Combining with Other Parameters

Next Steps

Guide to Path Variables and Query Parameters in Mitsuki Controllers

How to Handle URL Parameters in Mitsuki Controllers

Mitsuki

Introduction

Setup

Path Variables: Accessing Resource Identifiers

Query Parameters: Filtering and Sorting

Next Steps

Guide to Mitsuki Repositories: From Zero to Full CRUD

Introduction

Mitsuki

Domain Objects - @Entity

Level 1: Zero-Code CRUD with @CrudRepository

Level 2: Query DSL

Level 3: Taking Control with @Query

SQLAlchemy ORM-style Syntax (Default)

Native SQL Syntax

Level 4: Custom SQLAlchemy Methods

Conclusion

Next Steps

How to Create Your First Mitsuki REST API from Scratch

Mitsuki

Bootstrapping Mitsuki Projects

Step 1: Install Mitsuki

Step 2: mitsuki init 🪄

Step 3: Anatomy of a Mitsuki Project

What's Inside? Fully Functional API

Step 4: Liftoff! Running Your Server 🚀

Step 5: See Your API in Action

Your Journey Has Just Begun

Next Steps

Introducing Mitsuki - Spring Boot Enterprise Patterns and Speed with Python's Flexibility

Introduction

Bootstrapping Projects in a Minute - from Zero to Functional Starter

Automatic OpenAPI Generation

Supercharging Data Layer Repositories: Auto-CRUD and Query DSL

Why Another Web Dev Framework?

Lightweight

Benchmarks

The `Request` Type Hint

Domain Objects - `@Entity`

Level 1: Zero-Code CRUD with `@CrudRepository`

Level 3: Taking Control with `@Query`