xime 0.2.0

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

XIME Framework

Spring Boot-style developer experience for Python - without betraying Python's philosophy.

Documentation · Examples

---

XIME is not another HTTP framework. 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)
      |
  DI Container         (core/container, built-in)
      |
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

Adapters and starters are optional - install only what you need:

pip install "xime[web]"          # Uvicorn ASGI server
pip install "xime[sqlalchemy]"   # async DB sessions + transactions
pip install "xime[jwt]"          # JWT authentication
pip install "xime[scheduler]"    # cron-style task scheduling
pip install "xime[grpc]"         # gRPC adapter (code-first)
pip install "xime[socket]"       # Unix domain socket IPC
pip install "xime[all]"          # everything above

Requires Python 3.12+.

---

Quick Start

1. Define a controller - a plain class; methods map to routes.

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

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)

2. Configure dependency injection - declare which packages to scan and bind interfaces to implementations.

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

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

3. Bootstrap the application.

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

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

4. Run it.

python app/main.py

Need more than REST? Add another adapter to the same process:

# 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()

# Multiple servers in one process (public API + internal admin)
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()

---

Command-Line Interface

Installing xime also installs the xime command (no extra package needed). It powers the code-first gRPC workflow:

xime grpc generate     # generate .proto + stubs from your Python DTOs
xime grpc check        # verify generated artifacts are in sync
xime grpc client       # generate a typed client SDK from .proto

---

Example Projects

The best way to learn XIME is to read real code. These open-source projects are built on the framework - clone them, run them, and use them as references for structuring your own service:

Project	What it demonstrates	Good for
xime-shop-example	An e-commerce demo using a straightforward layered architecture.	Getting started
data-service	A production-grade microservice: Hexagonal / DDD, gRPC, SQLAlchemy, multi-tenant sharding. The most complete reference.	Real-world patterns
notification-service	An async, IO-bound notification microservice with event-driven patterns.	Async & events
xime-grpc-socket-example	One app serving gRPC (code-first, dynamic mTLS) and Unix Domain Sockets side by side, with shared @command / @stream contracts and different security models.	Multi-transport

New to XIME? Start with xime-shop-example for the fundamentals, then study data-service for full Hexagonal/DDD patterns at production scale.

---

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 to implementation mapping, validated at startup
Fail Fast	Circular deps, missing implementations, ambiguous bindings cause a startup error
Lifecycle Hooks	PostConstruct, PreDestroy for managed startup/shutdown
Initialization Order	dependency.order([A, B, C]) controls 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
gRPC Client SDK	Generate a typed Pydantic client from .proto, inject via DI; deadlines + typed errors
Dynamic mTLS	Certificate rotation without restart for both inbound servers and outbound clients
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.2.0, Alpha). Implemented: core DI, lifecycle, event bus, security context, configuration, JWT starter, scheduler starter, SQLAlchemy starter, Web adapter (FastAPI + routing, custom middleware & exception handlers), gRPC adapter (proto-first + code-first, dynamic mTLS), gRPC client SDK (typed, DI-injected, deadlines + typed errors), Socket adapter (Unix Domain Socket IPC), multi-server support, and initialization order (dependency.order()). WebSocket support is partial. Redis and Cache starters are planned.

---

Documentation

Full documentation lives in the GitHub repository:

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; dynamic mTLS
gRPC Client SDK	Generate a typed client SDK; inject it via DI; deadlines, typed errors, dynamic mTLS
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

---

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.

---

License

Released under the MIT License.