XIME is a convention layer for Python microservices. It sits on top of FastAPI, SQLAlchemy and gRPC - providing automatic dependency injection, startup-time graph validation, and architectural guardrails so you can focus on business logic instead of wiring.

Seven ways in: HTTP, WebSocket, gRPC, Unix sockets, MQTT, Modbus TCP and OPC UA - one application, one dependency graph, one lifecycle. Talking to a PLC and serving a browser are the same kind of work here.

And it scales without a process manager in front of it. Since 0.8, share_load() plus a count: in the config makes the processes share one listening socket - no gunicorn, no supervisor, no nginx balancing between ports. Measured 2026-08-25: 1.97x throughput on two processes, 3.75x on four.

# 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.

What it borrows from Spring Boot, and what it deliberately drops

The debt is real and worth naming: starters, and failing at startup rather than in production. Ask for a dependency nothing can supply and the process refuses to boot, with the class and parameter named.

What XIME drops is just as deliberate, because these are the parts that do not survive the trip into Python:

So "Spring Boot for Python" is the wrong shorthand. The right one is one dependency graph, many front doors - and one of those doors opens onto industrial hardware.

Why not dependency-injector, injector, or lagom?

These are solid libraries. XIME used to lean on dependency-injector for its singleton storage layer, but as of 0.6 the registry is hand-rolled (a plain dict keyed by the class object), so XIME has no third-party DI dependency at all. The difference is scope:

If you only need DI, use dependency-injector or lagom. If you want a full convention layer that wires DI, HTTP, gRPC, transactions, and lifecycle together - use XIME.

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[redis]"        # Redis client + cache backend
pip install "xime[grpc]"         # gRPC adapter (code-first)
pip install "xime[socket]"       # Unix domain socket IPC
pip install "xime[mqtt]"         # MQTT adapter (pub/sub + RPC over MQTT v5)
pip install "xime[s3]"           # S3 / MinIO storage backend
pip install "xime[mail]"         # SMTP email sending (aiosmtplib)
pip install "xime[modbus]"       # Modbus TCP adapter (master + slave)
pip install "xime[opcua]"        # OPC UA adapter (client + server)
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 -m app.main

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

📦 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:

New to XIME? Start with xime-shop-example for the fundamentals, then study data-service for full Hexagonal/DDD patterns at production scale. To see one app speak gRPC and sockets at once, read xime-grpc-socket-example.

Features

Starters

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

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. The following are implemented: core DI (hand-rolled singleton registry, no third-party DI dependency) with dynamic interface binding (one Protocol → many impls, swapped at runtime), lifecycle, event bus, security context, configuration, JWT starter (audience/issuer enforcement, keysets addressed by kid, clock leeway, required claims), scheduler starter, SQLAlchemy starter, Cache + Redis starters, Storage starter (local filesystem + S3/MinIO) with HTTP file streaming (Range download, chunked upload), Web adapter (FastAPI + routing, pure-ASGI request-context & JWT middleware, custom middleware & exception handlers, DI/config-aware middleware via Inject/FromConfig markers + first-class configure_cors), gRPC adapter (proto-first + code-first, typed server streaming, dynamic mTLS), gRPC client SDK (typed, DI-injected, deadlines + typed errors + automatic retry), Socket adapter (Unix Domain Socket IPC), MQTT adapter (pub/sub + RPC over MQTT v5), Modbus adapter (declarative device model, master polling + slave mode), OPC UA adapter (node models, subscriptions, server mode, full security), multi-server support, WebSocket (@ws routing, handshake authentication over Sec-WebSocket-Protocol, close-on-token-expiry), and initialization order (dependency.order()).

0.8 adds a multi-process runtime: share_load() with a supervisor, watchdog and primary promotion; RefData (shared memory for data that has a durable source); Store on LMDB (state that has none); ProcessLink (inter-process bus); opt-in /healthz and /readyz; and the xime init / xime config / xime check command-line tools.

The core is covered by 2500+ tests.

See the CHANGELOG for release history.

Documentation

Contributing

XIME is a solo project that needs community help to grow. There is still ground to cover: multi-process runtime, 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.