Metadata-Version: 2.4
Name: openstoreplugin
Version: 0.1.0
Summary: A library to base your controller plugins for Open Store
License-File: LICENSE
Keywords: open,openstore,store,openstoreplugin,plugin
Author: Alexi Desvignes Nouvel
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: authentik-client (==2026.5.6)
Requires-Dist: docker (>=7.1.0,<8.0.0)
Requires-Dist: email-validator (>=2.3.0,<3.0.0)
Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
Requires-Dist: pydantic (>=2.13.4,<3.0.0)
Project-URL: Documentation, https://github.com/AlexiDN/openstoreplugin/wiki
Project-URL: Repository, https://github.com/AlexiDN/openstoreplugin
Description-Content-Type: text/markdown

# OpenStorPlugin

[![pipeline status](https://gitlab.autonhomeserver.com/open/python/libs/openstoreplugin/badges/main/pipeline.svg)](https://gitlab.autonhomeserver.com/open/python/libs/openstoreplugin/-/commits/main)
[![coverage report](https://gitlab.autonhomeserver.com/open/python/libs/openstoreplugin/badges/main/coverage.svg)](https://gitlab.autonhomeserver.com/open/python/libs/openstoreplugin/-/commits/main)
[![codecov](https://codecov.io/gh/AlexiDN/openstoreplugin/branch/main/graph/badge.svg)](https://codecov.io/gh/AlexiDN/openstoreplugin)

## Features

- **`BaseConfig` — Config model with Jinja2 interpolation** — Pydantic models whose string fields are automatically resolved against a shared config dictionary. Supports chained variables, nested access, inheritance, strict/lenient modes, and per-field opt-out.
- **`@task()` decorator** — Declare typed, documented tasks on your controller. Tasks are auto-discovered and validated against the method signature at runtime.
- **`ControllerPlugin` base class** — Ready-to-extend controller with `install` / `uninstall` lifecycle, idempotent Authentik provider & application creation, Docker deployment orchestration, and bind-mount management.
- **`ControllerHooks`** — Callback interface (`save_config`) letting `ControllerPlugin` persist configuration changes back into the store, passed in at construction.
- **`DockerEngineConnector`** — Manage containers, networks, inspect, and exec commands against a local Docker daemon.
- **`AuthentikConnector`** — Create OAuth2 providers and applications via the Authentik API.
- **Smarthost models** — Typed configuration models for Traefik, Authentik, LDAP, and Docker services.
- **Jinja2 sandbox** — Config templates are rendered in a sandboxed environment that blocks unsafe attribute access (dunder, method calls).

## Installation

```bash
pip install openstoreplugin
```
## Usage

Define your application configuration by subclassing `BaseConfig`:

```python
from openstoreplugin import BaseConfig, ControllerPlugin
from openstoreplugin.models import ApplicationConfiguration, OpenStoreConfigModel


class MyAppConfig(ApplicationConfiguration):
    """Override or extend the base config."""

    pass


class MyController(ControllerPlugin):
    """Your custom controller logic."""

    def _install(self, time_to_start: int) -> None:
        # Your install logic here
        pass

    def _uninstall(self, cleanup_volumes: bool) -> None:
        # Your uninstall logic here
        pass


store_config = OpenStoreConfigModel(...)
app_config = MyAppConfig(...)
controller = MyController(app_config, store_config, hooks=MyControllerHooks())

# List available tasks
for name, task in controller.get_tasks().items():
    print(f"{name}: {task.description}")

# Execute a task
controller.execute_task("Install", time_to_start=120)
```

## License 

The project is released under the MIT License.

## Project Status

> **NOTE** <br>
> The project is currently in development phase. If you have any remark or question feel free to open an Issue
