♡ ｡ ₊°༺❤︎༻°₊ ｡ ♡
_ __ __ _
____ ___ (_) /________ __/ /__(_)
/ __ `__ \/ / __/ ___/ / / / //_/ /
/ / / / / / / /_(__ ) /_/ / ,< / /
/_/ /_/ /_/_/\__/____/\__,_/_/|_/_/
°❀˖ ° °❀⋆.ೃ࿔*:･ ° ❀˖°
Come with me, take the journey. ❀
Enterprise patterns of Spring Boot, development speed and flexibility of Python.
No compromises.
pip install mitsukiCreate 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.pyHit it:
curl http://localhost:8000/hello/world
# {"message": "Hello, world!"}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.
Bootstrap new projects with the mitsuki CLI.
mitsuki initThis 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:
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
Mitsuki brings enterprise strength without enterprise 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.
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.
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.
Services tend to evolve into certain time-tested patterns. Mitsuki supports them architecturally. Just write code - and it all fits into place.
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.
- Declarative over imperative. Express intent, not implementation.
- Enterprise patterns, no ceremony.
- Type hints are contracts.
- Fast by design, minimal overhead.
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.
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.
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) -> boolBut it also allows you to simply define method names, and auto-generates SQL for you:
@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): ...Or write queries 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 just write your own ORM-backed implementations:
from mitsuki import CrudRepository, Entity, Id, Column
from dataclasses import dataclass
@Entity()
@dataclass
class Post:
id: int = Id()
title: str = ""
author: str = ""
views: int = 0
@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()]Query DSL Parsing - Method names become queries:
find_by_email(email)→SELECT * WHERE email = ?find_by_age_greater_than(age)→SELECT * WHERE age > ?count_by_status(status)→SELECT COUNT(*) WHERE status = ?
Run background jobs with the @Scheduled decorator.
from mitsuki import Service, Scheduled
@Service()
class ReportService:
@Scheduled(cron="0 0 * * *") # Every hour
async def generate_hourly_report(self):
print("Generating hourly report...")
@Scheduled(fixed_rate=60000) # Every minute
async def check_system_health(self):
print("Checking system health...")Or use syntactic sugar:
from mitsuki import Service, Scheduled
@Service()
class ReportService:
@Scheduled(cron="@daily") # Equivalent to "0 0 0 * * *"
async def check_system_health(self):
print("Checking system health...")Handle multipart/form-data file uploads easily.
from mitsuki import RestController, PostMapping, FormFile, UploadFile
@RestController("/api/uploads")
class UploadController:
@PostMapping("/")
async def upload_file(self, file: UploadFile = FormFile()):
await file.save(f"uploads/{file.filename}")
return {"filename": file.filename, "size": file.size}from mitsuki import Configuration, Profile, Provider
@Configuration
@Profile("development")
class DevConfig:
@Provider
def database_url(self) -> str:
return "sqlite:///dev.db"
@Configuration
@Profile("production")
class ProdConfig:
@Provider
def database_url(self) -> str:
return "postgresql://prod-server/db"Run in dev:
MITSUKI_PROFILE=development python app.pyRun in production:
MITSUKI_PROFILE=production python app.pySame code, different environments. Keeps everything across environments explicit and readable.
Create application.yml (optional):
server:
port: 8000
host: 0.0.0.0
database:
url: sqlite:///app.db
logging:
level: INFOInject config into code:
from mitsuki import Configuration, Value
@Configuration
class AppConfig:
port: int = Value("${server.port:8000}")
db_url: str = Value("${database.url}")Supports application-profile.yml, enabling you to centrally define configurations for different environments easily.
| Guide | What's Inside |
|---|---|
| Overview | Architecture, DI, how everything fits together |
| Decorators Reference | Complete decorator guide (@Service, @RestController, etc.) |
| Repositories & Entities | Data layer, auto-repositories, query DSL |
| Controllers | REST endpoints, request mapping, parameters |
| Profiles | Environment-specific configuration |
| Configuration | application.yml, @Value, environment vars |
| CLI | Command-line interface for project scaffolding |
| Database Queries | Custom queries, SQLAlchemy integration |
| Response Entities | HTTP responses, status codes, headers |
| Validation | Request/response validation |
| JSON Serialization | Automatic serialization of complex types |
| Logging | Configuring and using logging |
| File Uploads | Handling multipart file uploads |
| Scheduled Tasks | Background jobs with @Scheduled |
| Metrics | Application monitoring and metrics |
| OpenAPI | Auto-generated API documentation with Swagger/ReDoc/Scalar |
A basic example with a domain object, CRUD repository and REST controller/router:
from mitsuki import Application, RestController, Service, CrudRepository, Entity, GetMapping, Id, Column
from dataclasses import dataclass
@Entity()
@dataclass
class User:
id: int = Id()
name: str = ""
email: str = Column(unique=True, default="")
@CrudRepository(entity=User)
class UserRepository:
pass # find_by_id, find_all, save, delete - all auto-implemented
@Service()
class UserService:
def __init__(self, repo: UserRepository):
self.repo = repo
async def get_user(self, user_id: int) -> User:
return await self.repo.find_by_id(user_id)
@RestController("/api/users")
class UserController:
def __init__(self, service: UserService):
self.service = service
@GetMapping("/{id}")
async def get(self, id: str) -> dict:
user = await self.service.get_user(int(id))
return {"id": user.id, "name": user.name, "email": user.email}
@Application
class MyApp:
pass
if __name__ == "__main__":
MyApp.run()What just happened?
UserRepositorygotfind_by_id(),find_all(),save(),delete()for free- Dependencies wired automatically (no factories, no setup)
- Database created on startup (SQLite by default)
- JSON API running on port 8000
Found a bug? Have an idea? PRs welcome.
- Fork it
- Create your feature branch
- Write tests
- Submit a PR
Built with ❀ for developers who want enterprise patterns without enterprise pain.