Mitsuki
Python's flexibility and productivity, Spring Boot's battle-tested enterprise patterns.
Install / Use
/learn @DavidLandup0/MitsukiREADME
♡ ｡ ₊°༺❤︎༻°₊ ｡ ♡
_ __ __ _
____ ___ (_) /________ __/ /__(_)
/ __ `__ \/ / __/ ___/ / / / //_/ /
/ / / / / / / /_(__ ) /_/ / ,< / /
/_/ /_/ /_/_/\__/____/\__,_/_/|_/_/
°❀˖ ° °❀⋆.ೃ࿔*:･ ° ❀˖°
Quickstart
pip install mitsuki
Create app.py:
from mitsuki import Application, RestController, GetMapping
@RestController("/") # Or @Router or @Controller
class HelloController:
@Get("/hello/{name}") # Or @GetMapping
async def hello(self, name: str) -> dict:
return {"message": f"Hello, {name}!"}
@Application
class App:
pass
if __name__ == "__main__":
App.run()
Run it:
python app.py
Hit it:
curl http://localhost:8000/hello/world
# {"message": "Hello, world!"}
OpenAPI Generation
Mitsuki automatically generates an OpenAPI 3.0 specification for your API, and supports Swagger, Redocly and Scalar UIs.
All can run in parallel, and a preferred UI gets exposed at /docs:
- Swagger UI:
http://localhost:8000/swagger - ReDoc:
http://localhost:8000/redoc - Scalar:
http://localhost:8000/scalar - Preferred:
http://localhost:8000/docs# Any one of the three above - OpenAPI JSON:
http://localhost:8000/openapi.json
No configuration needed.
CLI Tool
Bootstrap new projects with the mitsuki CLI.
mitsuki init
This will guide you through creating a new project with a clean structure and will auto-generate controllers, services, repositories, and configuration for different environments:
my_app/
src/
domain/ # @Entity classes
repository/ # @CrudRepository classes
service/ # @Service classes
controller/ # @RestController classes
__init__.py
app.py # Application entry point
application.yml # Base configuration
application-dev.yml # Development configuration
application-stg.yml # Staging configuration
application-prod.yml # Production configuration
.gitignore
README.md
Start it:
python src/app.py
2025-11-20 02:04:45,960 - mitsuki - INFO -
2025-11-20 02:04:45,960 - mitsuki - INFO - ♡ ｡ ₊°༺❤︎༻°₊ ｡ ♡
2025-11-20 02:04:45,960 - mitsuki - INFO - _ __ __ _
2025-11-20 02:04:45,960 - mitsuki - INFO - ____ ___ (_) /________ __/ /__(_)
2025-11-20 02:04:45,960 - mitsuki - INFO - / __ `__ \/ / __/ ___/ / / / //_/ /
2025-11-20 02:04:45,960 - mitsuki - INFO - / / / / / / / /_(__ ) /_/ / ,< / /
2025-11-20 02:04:45,960 - mitsuki - INFO - /_/ /_/ /_/_/\__/____/\__,_/_/|_/_/
2025-11-20 02:04:45,960 - mitsuki - INFO - °❀˖ ° °❀⋆.ೃ࿔*:･ ° ❀˖°
2025-11-20 02:04:45,960 - mitsuki - INFO -
2025-11-20 02:04:45,960 - mitsuki - INFO - :: Mitsuki :: (0.1.2)
2025-11-20 02:04:45,960 - mitsuki - INFO -
2025-11-20 02:04:45,960 - mitsuki - INFO - Mitsuki application starting on http://127.0.0.1:8000
2025-11-20 02:04:45,961 - _granian - INFO - Starting granian (main PID: 19002)
2025-11-20 02:04:45,967 - _granian - INFO - Listening at: http://127.0.0.1:8000
2025-11-20 02:04:45,976 - _granian - INFO - Spawning worker-1 with PID: 19005
2025-11-20 02:04:46,370 - _granian.workers - INFO - Started worker-1
2025-11-20 02:04:46,370 - _granian.workers - INFO - Started worker-1 runtime-1
And hit the docs on http://127.0.0.1:8000/docs:
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
Why Mitsuki?
Mitsuki brings battle-tested web application patterns strength without introducing high complexity.
This is achieved through bringing dependency injection, declarative controllers, and auto-repositories to Python without the ceremony. It's highly inspired by Spring Boot in its early stages.
Conceptually, you can think of it as a structured dependency injection framework with syntactic sugar and tooling built on top of Starlette and Granian/Uvicorn.
High-Performance and Lightweight
Mitsuki is lightweight, and internally uses Granian for low-level server and Starlette for ASGI. As such - it's as fast as Starlette on Granian. Performance-wise - it ranks in the same category as as Spring Boot (Java) and Express (Node/JavaScript), and higher than FastAPI (Python), Flask (Python) or Django (Python).
For more, read the README.md in /benchmarks.
Productivity
Convention over configuration allows you to focus on business code, not glue. Mitsuki provides sensible default conventions, while allowing you to customize any level whenever you'd like.
Enterprise Patterns at Low Cognitive Cost
Services tend to evolve into certain time-tested patterns. Mitsuki supports them architecturally. Just write code - and it all fits into place.
Server-Agnostic
Mitsuki isn't tied to a single server library. We currently support uvicorn and granian, with experimental support for socketify. We use starlette as an intermediary ASGI-compliant layer.
┌──────────────────────────┐
│ Mitsuki Application │
└────────────┬─────────────┘
│
▼
┌────────────────────────┐
│ Starlette ASGI │
│ Framework │
└────────────┬───────────┘
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌───────────┐
│ Granian │ │ Uvicorn │ │ Socketify │
└─────────┘ └─────────┘ └───────────┘
In the future - we will likely not commit to only following the ASGI specification, with plans to support RSGI and likely a custom framework to directly leverage granian, uvicorn and socketify other than through the ASGI interface.
We want to maintain the key components in a plug-and-play fashion, staying up to date with the landscape of tooling. This means not locking the framework into a single paradigm.
Core Design Principles
- Declarative over imperative. Express intent, not implementation.
- Enterprise patterns, no ceremony.
- Type hints are contracts.
- Fast by design, minimal overhead.
Core Concepts
Mituski architecturally encourages a logical separation of code into three main categories:
- Controllers (representation layer)
- Services (business layer)
- Repositories (data layer)
And uses those assumptions to enhance developer experience, reducing boilerplate, and provides reasonable defaults for most implementation.
To maximize this - you only need to understand a few core concepts.
Dependency Injection
Formally, Mitsuki performs Inversion of Control (IoC), which is achieved through Dependency Injection (DI). It does this automatically, so you don't have to resolve dependencies yourself.
In other words - you define dependencies semantically, and Mitsuki handles how they're created, injected, and resolved.
In yet other words - you define a thing, and a @Provider puts it into a global container that enables you to use the thing in any part of your application, without having to instantiate it or injecting it manually:
@Service()
class EmailService:
async def send(self, to: str, message: str):
print(f"Sending to {to}: {message}")
@Service()
class UserService:
def __init__(self, email_service: EmailService):
# Mitsuki sees EmailService in __init__, wires it automatically
self.email = email_service
async def notify_user(self, email: str):
await self.email.send(email, "You've got mail!")
Type hints are enough. Mitsuki handles the rest.
^ This also makes it super simple to define configurations for how you want objects to be built, and simply put them into the mix for them to be used. Want to change Mitsuki's formatter? Inject it into the container and it'll override the formatter in it. Want to change Mitsuki's serializer? Inject it into the container and it'll override the serializer in it.
Mitsuki then distributes your objects across the entire codebase.
Auto-Repositories - Write Interfaces, Get Implementations
Repositories (data layer) support three levels of methods. CRUD with pagination is auto-supported, just by defining a type:
@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
But it also allows you to simply def
