Metadata-Version: 2.4
Name: xime
Version: 0.1.0
Summary: Spring Boot-inspired dependency injection and convention framework for Python backends
Project-URL: Homepage, https://github.com/nguyen-huu-thang/xime-framework
Project-URL: Repository, https://github.com/nguyen-huu-thang/xime-framework
Project-URL: Issues, https://github.com/nguyen-huu-thang/xime-framework/issues
Author-email: Nguyễn Hữu Thắng <nguyen-huu-thang@outlook.com>
License: MIT License
        
        Copyright (c) 2025 Nguyễn Hữu Thắng
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: backend,convention,dependency-injection,fastapi,framework,spring-boot
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: dependency-injector>=4.41.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: apscheduler>=4.0; extra == 'all'
Requires-Dist: grpcio-tools>=1.60; extra == 'all'
Requires-Dist: grpcio>=1.60; extra == 'all'
Requires-Dist: msgpack>=1.0; extra == 'all'
Requires-Dist: protobuf>=4.25; extra == 'all'
Requires-Dist: pyjwt>=2.8; extra == 'all'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'all'
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20; extra == 'dev'
Requires-Dist: anyio>=4.0; extra == 'dev'
Requires-Dist: apscheduler>=4.0; extra == 'dev'
Requires-Dist: asyncpg>=0.29; extra == 'dev'
Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
Requires-Dist: grpcio>=1.60; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: msgpack>=1.0; extra == 'dev'
Requires-Dist: protobuf>=4.25; extra == 'dev'
Requires-Dist: pyjwt>=2.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'dev'
Provides-Extra: grpc
Requires-Dist: grpcio-tools>=1.60; extra == 'grpc'
Requires-Dist: grpcio>=1.60; extra == 'grpc'
Requires-Dist: protobuf>=4.25; extra == 'grpc'
Provides-Extra: jwt
Requires-Dist: pyjwt>=2.8; extra == 'jwt'
Provides-Extra: scheduler
Requires-Dist: apscheduler>=4.0; extra == 'scheduler'
Provides-Extra: socket
Requires-Dist: msgpack>=1.0; extra == 'socket'
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'sqlalchemy'
Provides-Extra: web
Requires-Dist: uvicorn[standard]>=0.27; extra == 'web'
Description-Content-Type: text/markdown

# XIME Framework

**English** | [Tiếng Việt](README-vn.md)

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

```python
# 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

```text
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

```bash
pip install xime
```

Optional starters:

```bash
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

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

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

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

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

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

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

```python
# 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)
```

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

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

```bash
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](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/architecture.md) to understand the design
- Pick an open area from the [roadmap](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/contributing.md#roadmap)
- Open an issue to discuss a feature or bug
- Submit a pull request

Please read [CONTRIBUTING](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/contributing.md) before opening a PR.

---

## Documentation

| Document | Description |
| --- | --- |
| [Getting Started](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/getting-started.md) | First app in 5 minutes |
| [Architecture](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/architecture.md) | How XIME is structured internally |
| [Core Concepts](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/core-concepts.md) | DI, interface binding, scopes |
| [Configuration](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/configuration.md) | Framework config + runtime YAML |
| [Routing](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/routing.md) | Class-based controllers, route decorators |
| [Transaction](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/transaction.md) | Explicit transaction management |
| [Code-First gRPC](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/grpc-codefirst.md) | Generate `.proto` from Python DTOs; field-number stability; `xime grpc generate/check` |
| [Socket Adapter](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/socket-adapter.md) | Unix Domain Socket IPC for same-host Native Engine calls |
| [Starters](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/starters.md) | SQLAlchemy, JWT, Scheduler |
| [Testing](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/testing.md) | DI overrides, fakes, test utilities |
| [Contributing](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/contributing.md) | How to contribute, roadmap |

---

## License

MIT
