Metadata-Version: 2.4
Name: backlooms
Version: 0.1.0
Summary: Python Backlooms framework
Author-email: Vladimir Perekladov <gleero@gmail.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: dependency-injector==4.48.2
Requires-Dist: pydantic==2.12.4
Requires-Dist: pydantic-settings==2.12.0
Requires-Dist: typer==0.20.0
Provides-Extra: dev
Requires-Dist: aiosqlite==0.21.0; extra == "dev"
Requires-Dist: black==25.11.0; extra == "dev"
Requires-Dist: build==1.3.0; extra == "dev"
Requires-Dist: bumpversion==0.6.0; extra == "dev"
Requires-Dist: coverage==7.12.0; extra == "dev"
Requires-Dist: greenlet==3.2.4; extra == "dev"
Requires-Dist: httpx==0.27.2; extra == "dev"
Requires-Dist: pre-commit==4.5.0; extra == "dev"
Requires-Dist: pyright==1.1.407; extra == "dev"
Requires-Dist: pytest==9.0.1; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: pytest-xdist==3.7.0; extra == "dev"
Requires-Dist: setuptools==80.9.0; extra == "dev"
Requires-Dist: twine==6.2.0; extra == "dev"
Requires-Dist: wheel==0.45.1; extra == "dev"
Provides-Extra: security
Requires-Dist: base58==2.1.1; extra == "security"
Requires-Dist: pwdlib==0.3.0; extra == "security"
Requires-Dist: pwdlib[argon2]==0.3.0; extra == "security"
Requires-Dist: python-jose==3.5.0; extra == "security"
Requires-Dist: random-password-generator==2.2.0; extra == "security"
Provides-Extra: db
Requires-Dist: alembic==1.17.2; extra == "db"
Requires-Dist: asyncpg==0.31.0; extra == "db"
Requires-Dist: fastapi-filter==2.0.1; extra == "db"
Requires-Dist: psycopg2-binary==2.9.11; extra == "db"
Requires-Dist: SQLAlchemy==2.0.44; extra == "db"
Requires-Dist: sqlmodel==0.0.27; extra == "db"
Requires-Dist: base58==2.1.1; extra == "db"
Requires-Dist: pwdlib==0.3.0; extra == "db"
Requires-Dist: pwdlib[argon2]==0.3.0; extra == "db"
Requires-Dist: python-jose==3.5.0; extra == "db"
Requires-Dist: random-password-generator==2.2.0; extra == "db"
Provides-Extra: fastapi
Requires-Dist: fastapi==0.122.0; extra == "fastapi"
Requires-Dist: uvicorn==0.38.0; extra == "fastapi"
Provides-Extra: full
Requires-Dist: dependency-injector==4.48.2; extra == "full"
Requires-Dist: pydantic==2.12.4; extra == "full"
Requires-Dist: pydantic-settings==2.12.0; extra == "full"
Requires-Dist: typer==0.20.0; extra == "full"
Requires-Dist: fastapi==0.122.0; extra == "full"
Requires-Dist: uvicorn==0.38.0; extra == "full"
Requires-Dist: alembic==1.17.2; extra == "full"
Requires-Dist: asyncpg==0.31.0; extra == "full"
Requires-Dist: fastapi-filter==2.0.1; extra == "full"
Requires-Dist: psycopg2-binary==2.9.11; extra == "full"
Requires-Dist: SQLAlchemy==2.0.44; extra == "full"
Requires-Dist: sqlmodel==0.0.27; extra == "full"
Requires-Dist: base58==2.1.1; extra == "full"
Requires-Dist: pwdlib==0.3.0; extra == "full"
Requires-Dist: pwdlib[argon2]==0.3.0; extra == "full"
Requires-Dist: python-jose==3.5.0; extra == "full"
Requires-Dist: random-password-generator==2.2.0; extra == "full"

# Backlooms

Backlooms is a modular Python framework designed for building robust microservices with a strong focus on background workers, dependency injection, and seamless integration with FastAPI and SQLAlchemy.

It provides a structured way to manage your application's lifecycle, configuration, and command-line interface.

## Key Features

- **Application Orchestration**: A central `Application` class to wire up configuration, dependency injection, workers, and server adapters.
- **Dependency Injection**: Effortless DI powered by `dependency-injector`, with automatic module wiring and a convenient `@inject` decorator.
- **Background Workers**: A standardized way to define long-lived background tasks with graceful shutdown and lifecycle management.
- **FastAPI Integration**: Out-of-the-box support for FastAPI via a dedicated server adapter.
- **Database Layer**: Built-on top of SQLAlchemy and SQLModel, providing a clean Repository pattern and migration support (via Alembic).
- **Flexible Auth**: Modular authentication system supporting JWT, Bearer tokens, and password-based login.
- **Async CLI**: Unified command-line interface based on Typer, with native support for `async` commands.

## Installation

```bash
pip install backlooms
```

*Note: Depending on your needs, you might want to install extra dependencies:*
```bash
pip install "backlooms[db]"       # For database support
pip install "backlooms[fastapi]"  # For FastAPI integration
pip install "backlooms[full]"     # For all features
```

## Quick Start

### 1. Define Configuration

```python
from backlooms import BaseConfig

class MyConfig(BaseConfig):
    PROJECT_NAME: str = "My Microservice"
    DATABASE_URL: str = "postgresql+asyncpg://user:pass@localhost/db"
```

### 2. Set Up Dependency Injection

```python
from backlooms import DIContainer, inject
from dependency_injector import providers
from dependency_injector.wiring import Provide

class MyContainer(DIContainer):
    # Your services and repositories go here
    # config is automatically available as a provider
    pass

@inject
async def my_function(service = Provide[MyContainer.my_service]):
    await service.do_something()
```

### 3. Create a Background Worker

```python
from backlooms.workers import BaseWorker
from contextlib import asynccontextmanager

class MyWorker(BaseWorker):
    NAME = "my-worker"
    DESCRIPTION = "Does important background work"

    @asynccontextmanager
    async def lifespan(self):
        print("Worker starting...")
        yield self
        print("Worker stopping...")
```

### 4. Run the Application

```python
from backlooms import Application
from backlooms.workers import WorkerRegistry
from backlooms.server.adapters.fastapi import FastAPIServerAdapter
from fastapi import APIRouter

# Setup workers
registry = WorkerRegistry()
registry.add(MyWorker)

# Setup server
router = APIRouter()
adapter = FastAPIServerAdapter(router=router, host="0.0.0.0", port=8000)

app = Application(
    config=MyConfig(),
    container_cls=MyContainer,
    workers=registry,
    server_adapter=adapter
)

if __name__ == "__main__":
    app.run()
```

## CLI Usage

Backlooms automatically generates a CLI for your application.

- **Run a specific worker**:
  ```bash
  python main.py run my-worker
  ```

- **Start server and all workers**:
  ```bash
  python main.py start
  ```

- **Start only the server**:
  ```bash
  python main.py start --server-only
  ```

- **Selective workers**:
  ```bash
  python main.py start --without-my-worker
  ```

## Database & Repositories

Backlooms encourages the use of the Repository pattern.

```python
from backlooms.db import BaseRepository
from sqlmodel import SQLModel, Field

class User(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    username: str

class UserRepository(BaseRepository[User, None]):
    model = User
```

## Authentication

The framework provides an `IdentityManager` to handle multiple authentication providers.

```python
from backlooms.auth import IdentityManager
from backlooms.auth.providers.password import PasswordProvider

# Register providers in your container
identity_manager = IdentityManager(
    auth_service=...,
    user_service=...,
    providers=[PasswordProvider()]
)
```
