xime 0.1.0

Spring Boot-inspired dependency injection and convention framework for Python backends

XIME Framework

English | Tiếng Việt

A Python backend framework inspired by Spring Boot's conventions — built to respect Python's philosophy.

---

XIME is not another HTTP framework. Taking inspiration from Spring Boot's convention-over-configuration approach, it sits on top of FastAPI, SQLAlchemy, and gRPC — providing a convention engine, automatic dependency injection, and architectural guardrails so you can focus on business logic instead of wiring.

# Before XIME — wire everything manually
container.user_service = providers.Singleton(
    UserService,
    repository=container.user_repository,
    transaction=container.transaction_manager,
)

# With XIME — just write your class
class UserService:
    def __init__(
        self,
        repository: UserRepository,
        transaction: TransactionManager,
    ):
        self.repository = repository
        self.transaction = transaction

XIME reads your type hints, scans your packages, builds the dependency graph, validates it at startup, and wires everything together — automatically.

---

Why XIME?

Python has excellent libraries for HTTP, databases, and serialization. What it lacks is a convention layer that:

• Automatically discovers and wires dependencies from constructor type hints
• Enforces architectural boundaries through directory structure
• Validates the dependency graph at startup — not at runtime when a user hits an endpoint
• Provides a consistent structure for Clean Architecture / DDD / Modular Monolith projects

XIME fills that gap. It does not replace FastAPI or SQLAlchemy — it makes them easier to use at scale.

---

How It Works

Application Code
      ↓
   XIME Core          ← scanning, DI, lifecycle, config
      ↓
Dependency Injector   ← runtime DI engine
      ↓
Python Objects

XIME's startup pipeline:

1. Load framework configuration (config/dependency.py)
2. Load runtime configuration (resources/application.yml)
3. Scan declared packages
4. Resolve type hints
5. Build dependency graph
6. Validate graph — detect cycles, missing implementations, ambiguous bindings
7. Create singletons
8. Start adapters (FastAPI, gRPC, ...)

If anything is wrong, the app fails immediately at startup with a clear error — not later in production.

---

Installation

pip install xime

Optional starters:

pip install xime[web]        # uvicorn (ASGI server)
pip install xime[sqlalchemy] # async SQLAlchemy
pip install xime[jwt]        # JWT auth
pip install xime[scheduler]  # cron-style tasks
pip install xime[grpc]       # gRPC adapter
pip install xime[all]        # everything above

---

Quick Start

# app/main.py — REST only
from xime import Application
from xime.adapters.web import WebAdapter

app = Application()
app.use(WebAdapter())
app.run()

# app/main.py — REST + gRPC simultaneously
from xime import Application
from xime.adapters.web import WebAdapter
from xime.adapters.grpc import GrpcAdapter

app = Application()
app.use(WebAdapter())
app.use(GrpcAdapter())
app.run()

# app/main.py — Multiple servers (public API + internal admin)
from xime import Application
from xime.adapters.web import WebAdapter

app = Application()
app.use(WebAdapter())                              # server_id="default", port from application.yml
app.use(WebAdapter("admin", "127.0.0.1", 8081))   # server_id="admin", explicit host/port
app.run()

# app/config/dependency.py
from xime import BindingConfig

dependency = BindingConfig()
dependency.scan("application.usecase", "infrastructure.repository")
dependency.bind({UserRepository: JpaUserRepository})

# app/api/rest/user_controller.py
from xime.adapters.web.routing import get, post

class UserController:
    prefix = "/users"

    def __init__(self, use_case: GetUserUseCase) -> None:
        self._use_case = use_case

    @get("/{user_id}", response_model=UserResponse)
    async def get_user(self, user_id: int) -> UserResponse:
        return await self._use_case.execute(user_id)

# app/main.py
from xime import Application
from xime.adapters.web import WebAdapter

app = Application()
app.use(WebAdapter())
app.run()

python app/main.py

---

Features

Feature	Description
Constructor Injection	Declare dependencies as constructor params — XIME wires them
Directory-Driven DI	Package location determines component role — no annotations
Interface Binding	Explicit Protocol → implementation mapping, validated at startup
Fail Fast	Circular deps, missing implementations, ambiguous bindings → startup error
Lifecycle Hooks	PostConstruct, PreDestroy for managed startup/shutdown
Initialization Order	dependency.order([A, B, C]) — control post_construct() execution order across independent classes
Multi-Server	Multiple WebAdapter / GrpcAdapter / SocketAdapter per process, each with its own server_id
Event Bus	Internal pub/sub for decoupled domain events
Request Context	Per-request data via ContextVar, set by adapters
Security Context	AuthenticationManager, AuthorizationManager in core
Two-Layer Config	Framework config (Python) + Runtime config (YAML)
Transaction API	Explicit async with self.transaction(): — no hidden AOP
Class-Based Controllers	Controllers are DI singletons, methods map to routes
Code-First gRPC	Write Python DTOs, XIME generates .proto + stubs; field-number stability via lock file
Socket Adapter	Unix Domain Socket IPC for same-host Native Engine calls (Linux); @command / @stream

---

Starters

Optional modules, similar to spring-boot-starter-*:

Starter	What it provides	Status
xime.starters.sqlalchemy	Async DB session, SqlAlchemyTransactionManager	✅ Implemented
xime.starters.jwt	JWT signing, verification, middleware	✅ Implemented
xime.starters.scheduler	Cron-style task scheduling	✅ Implemented
xime.starters.redis	Redis client integration	🔲 Planned
xime.starters.cache	Cache abstraction layer	🔲 Planned

---

Design Principles

• Explicit over implicit — binding, routing, config are always declared, never auto-discovered by magic
• Constructor injection only — no @inject, no field injection, no @autowired
• No annotations for roles — @service, @repository, @component do not exist; directory determines role
• Fail fast — errors surface at startup, not at runtime
• Thin wrapper — XIME does not rewrite FastAPI, SQLAlchemy, or gRPC; it orchestrates them

---

Project Status

XIME is in active development (v0.1.0 — Alpha). The following are implemented: core DI, lifecycle, event bus, security context, configuration, JWT starter, scheduler starter, SQLAlchemy starter, Web adapter (FastAPI + routing), gRPC adapter (proto-first + code-first), Socket adapter (Unix Domain Socket IPC), multi-server support, and initialization order (dependency.order()). WebSocket support is partial. Redis and Cache starters are planned.

---

Contributing

XIME is a solo project that needs community help to grow. There is still ground to cover: completing WebSocket support, Redis/Cache starters, CLI scaffolding, testing utilities, and more.

Ways to contribute:

• Read the architecture docs to understand the design
• Pick an open area from the roadmap
• Open an issue to discuss a feature or bug
• Submit a pull request

Please read CONTRIBUTING before opening a PR.

---

Documentation

Document	Description
Getting Started	First app in 5 minutes
Architecture	How XIME is structured internally
Core Concepts	DI, interface binding, scopes
Configuration	Framework config + runtime YAML
Routing	Class-based controllers, route decorators
Transaction	Explicit transaction management
Code-First gRPC	Generate .proto from Python DTOs; field-number stability; xime grpc generate/check
Socket Adapter	Unix Domain Socket IPC for same-host Native Engine calls
Starters	SQLAlchemy, JWT, Scheduler
Testing	DI overrides, fakes, test utilities
Contributing	How to contribute, roadmap

---

License

MIT