Metadata-Version: 2.4
Name: framework-m-core
Version: 0.5.6
Summary: Core protocols and dependency injection for Framework M
Author: Framework M Contributors
License: MIT
Requires-Python: >=3.12
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: cyclopts>=3.0.0
Requires-Dist: dependency-injector>=4.41.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# Framework M Core

[![PyPI version](https://badge.fury.io/py/framework-m-core.svg)](https://badge.fury.io/py/framework-m-core)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitLab Pipeline Status](https://gitlab.com/castlecraft/framework-m/badges/main/pipeline.svg)](https://gitlab.com/castlecraft/framework-m/-/pipelines)

Core protocols and dependency injection container for Framework M.

## Installation

```bash
pip install framework-m-core
```

Or with `uv`:

```bash
uv add framework-m-core
```

## What's Included

### Protocol Interfaces (Ports)

Framework M Core defines the protocol interfaces that adapters must implement:

| Protocol | Purpose |
|----------|---------|
| `RepositoryProtocol` | CRUD operations for documents |
| `EventBusProtocol` | Publish/subscribe events |
| `PermissionProtocol` | Authorization with RLS |
| `StorageProtocol` | File storage abstraction |
| `JobQueueProtocol` | Background job processing |
| `CacheProtocol` | Caching layer |
| `NotificationProtocol` | Email/SMS notifications |
| `SearchProtocol` | Full-text search |
| `PrintProtocol` | PDF generation |
| `I18nProtocol` | Internationalization |

### Domain Base Classes

- `BaseDocType` - Base class for all document types
- `BaseController` - Lifecycle hooks (validate, before_save, after_save, etc.)
- `SubmittableMixin` - For documents with submit/cancel workflow

### Dependency Injection

Built on `dependency-injector` for clean, testable code:

```python
from framework_m_core.container import Container

container = Container()
container.wire(modules=["my_app.services"])
```

### CLI Framework

Built on `cyclopts` for powerful command-line interfaces:

```python
from framework_m_core.cli import app

@app.command
def my_command():
    """My custom command."""
    pass
```

## Usage

This package is typically used as a dependency of `framework-m` or `framework-m-standard`. 
For most applications, install the full `framework-m` package instead.

## License

MIT License - see [LICENSE](https://gitlab.com/castlecraft/framework-m/blob/main/LICENSE) for details.
