codex-platform 0.1.0__py3-none-any.whl

codex_platform/notifications/registry.py

@@ -0,0 +1,71 @@
+"""
+codex_platform.notifications.channels.registry
+=============================================
+Auto-discovers available delivery channels based on configuration.
+
+Usage:
+    registry = ChannelRegistry()
+    registry.register("smtp", lambda cfg: SmtpChannel(cfg) if cfg.SMTP_HOST else None)
+    registry.register("sendgrid", lambda cfg: SendGridChannel(cfg) if cfg.SENDGRID_API_KEY else None)
+    channels = registry.build_channels(settings)
+    # → [SmtpChannel, SendGridChannel]  (только те, чей конфиг заполнен)
+"""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from .orchestrator import DeliveryChannel
+
+log = logging.getLogger(__name__)
+
+
+class ChannelRegistry:
+    """
+    Registry for delivery channels.
+    Channels register with a factory function that returns a channel or None.
+    build_channels() creates only the channels whose config is available.
+    """
+
+    def __init__(self) -> None:
+        self._factories: list[tuple[str, Callable[[Any], DeliveryChannel | None]]] = []
+
+    def register(
+        self,
+        name: str,
+        factory: Callable[[Any], DeliveryChannel | None],
+    ) -> None:
+        """
+        Register a channel factory.
+
+        Args:
+            name: Human-readable channel name (for logging).
+            factory: Callable that takes config and returns DeliveryChannel or None.
+                     Return None if the channel's config is missing/incomplete.
+        """
+        self._factories.append((name, factory))
+
+    def build_channels(self, config: Any) -> list[DeliveryChannel]:
+        """Build the list of available channels from all registered factories.
+
+        Calls each factory with ``config``. A channel is included only when the
+        factory returns a non-``None`` instance that also reports ``is_available() == True``.
+
+        Args:
+            config: Application settings object passed verbatim to every factory.
+
+        Returns:
+            Ordered list of ready-to-use :class:`DeliveryChannel` instances.
+        """
+        channels: list[DeliveryChannel] = []
+        for name, factory in self._factories:
+            try:
+                channel = factory(config)
+                if channel is not None and channel.is_available():
+                    channels.append(channel)
+                    log.info("ChannelRegistry | %s enabled", name)
+                else:
+                    log.debug("ChannelRegistry | %s skipped (not configured)", name)
+            except Exception:
+                log.exception("ChannelRegistry | %s factory failed", name)
+        return channels

codex_platform/notifications/renderer.py

@@ -0,0 +1,111 @@
+"""
+codex_platform.notifications.renderer
+======================================
+Jinja2-based HTML template renderer for notification workers.
+
+OPTIONAL DEPENDENCY
+-------------------
+This module requires ``jinja2`` which is NOT included in the default
+``codex-platform`` installation.
+
+There are two delivery modes:
+
+  Mode 1 — Worker renders templates itself (needs Jinja2):
+      Worker receives ``template_name`` + ``context_data``,
+      renders HTML internally, then sends via SMTP.
+
+  Mode 2 — Pre-rendered HTML (no Jinja2 needed):
+      Django (or any other layer) renders the template and passes
+      ready ``html_content`` directly to the workers for delivery only.
+
+If you are using Mode 1, add the following to your project dependencies:
+
+    # pyproject.toml
+    dependencies = [
+        "jinja2>=3.1",
+    ]
+
+    # or via pip
+    pip install jinja2
+
+Usage
+-----
+    from codex_platform.notifications.renderer import TemplateRenderer
+
+    renderer = TemplateRenderer(templates_dir="/path/to/workers/templates")
+    html = renderer.render("booking/bk_confirmation.html", context={...})
+
+Template directory structure (recommended)
+------------------------------------------
+    templates/
+    ├── base_email.html
+    ├── booking/
+    │   ├── bk_confirmation.html
+    │   └── bk_cancellation.html
+    ├── contacts/
+    │   └── ct_receipt.html
+    └── marketing/
+        └── mk_reengagement.html
+"""
+
+import logging
+import os
+
+log = logging.getLogger(__name__)
+
+try:
+    from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+    _JINJA2_AVAILABLE = True
+except ImportError:
+    _JINJA2_AVAILABLE = False
+
+
+class TemplateRenderer:
+    """
+    Jinja2 HTML template renderer.
+
+    Requires ``jinja2`` — install via ``pip install codex-platform[jinja2]``.
+
+    Raises:
+        RuntimeError: If jinja2 is not installed.
+        FileNotFoundError: If the templates directory does not exist.
+    """
+
+    def __init__(self, templates_dir: str) -> None:
+        if not _JINJA2_AVAILABLE:
+            raise RuntimeError(
+                "jinja2 is not installed. "
+                "Run: pip install codex-platform[jinja2]\n"
+                "If you are passing pre-rendered html_content to the workers, "
+                "you do not need TemplateRenderer at all."
+            )
+
+        if not os.path.exists(templates_dir):
+            raise FileNotFoundError(f"Templates directory not found: {templates_dir}")
+
+        self.env = Environment(
+            loader=FileSystemLoader(templates_dir),
+            autoescape=select_autoescape(["html", "xml"]),
+        )
+        self.templates_dir = templates_dir
+        log.info("TemplateRenderer | initialized with dir='%s'", templates_dir)
+
+    def render(self, template_name: str, context: dict[str, object]) -> str:
+        """
+        Render a template with the given context.
+
+        Args:
+            template_name: Relative path to template (e.g. 'booking/bk_confirmation.html').
+            context: Dictionary of variables passed to the template.
+
+        Returns:
+            Rendered HTML string.
+
+        Raises:
+            jinja2.TemplateNotFound: If the template file does not exist.
+            jinja2.TemplateError: On rendering errors.
+        """
+        log.debug("TemplateRenderer | rendering template='%s'", template_name)
+        template = self.env.get_template(template_name)
+        return template.render(context)

codex_platform/redis_service/__init__.py

@@ -0,0 +1,59 @@
+"""
+codex_platform.redis_service
+==========================
+Async Redis service with mixin architecture.
+
+Requires ``redis.asyncio.Redis`` client. All methods are async-only.
+
+Quick start::
+
+    from codex_platform.redis_service import RedisService
+
+    service = RedisService(client=redis_client)
+    await service.set_hash_json("my_key", "field", {"a": 1})
+
+Custom composition::
+
+    from codex_platform.redis_service import BaseRedisService, HashMixin, StreamMixin
+
+    class MyRedisService(BaseRedisService, HashMixin, StreamMixin):
+        pass
+
+Key Registry::
+
+    from codex_platform.redis_service import UserKey
+
+    await service.get_hash_json(UserKey(), "profile", user_id=42)
+"""
+
+from .base import BaseRedisService
+from .keys import BaseRedisKey, SessionKey, UserKey
+from .operations import (
+    HashOperations,
+    JsonModuleOperations,
+    JsonStringOperations,
+    ListOperations,
+    PipelineOperations,
+    SetOperations,
+    StringOperations,
+    ZSetOperations,
+)
+from .service import RedisService
+
+__all__ = [
+    "BaseRedisService",
+    "RedisService",
+    # Operations
+    "HashOperations",
+    "SetOperations",
+    "ListOperations",
+    "StringOperations",
+    "ZSetOperations",
+    "JsonStringOperations",
+    "JsonModuleOperations",
+    "PipelineOperations",
+    # Key Registry
+    "BaseRedisKey",
+    "UserKey",
+    "SessionKey",
+]

codex_platform/redis_service/base.py

@@ -0,0 +1,69 @@
+"""
+codex_platform.redis_service.base
+=================================
+Core Redis infrastructure components.
+
+Contains:
+- catch_redis_errors — decorator that converts redis-py errors to domain exceptions
+- BaseRedisService — base class holding a Redis connection
+"""
+
+import logging
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from redis.asyncio import Redis
+from redis.exceptions import ConnectionError, RedisError, TimeoutError
+
+from codex_platform.redis_service.exceptions import RedisConnectionError, RedisServiceError
+
+log = logging.getLogger(__name__)
+
+
+def catch_redis_errors(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator that converts redis-py exceptions into typed domain exceptions.
+
+    Never suppresses errors — always re-raises as a domain exception.
+    Preserves the original traceback via ``raise ... from e``.
+
+    Catches:
+        - ``ConnectionError``, ``TimeoutError`` → :exc:`RedisConnectionError`
+        - ``RedisError`` → :exc:`RedisServiceError`
+
+    Does NOT catch:
+        ``JSONDecodeError``, ``TypeError`` — data-specific errors are caught
+        in individual operations and re-raised as :exc:`RedisDataError`.
+    """
+
+    @wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return await func(*args, **kwargs)
+        except (ConnectionError, TimeoutError) as e:
+            msg = f"Network failure in {func.__name__}: {e}"
+            log.exception("Redis | error=connection_failed fn='%s'", func.__name__)
+            raise RedisConnectionError(msg) from e
+        except RedisError as e:
+            msg = f"Operation failed in {func.__name__}: {e}"
+            log.exception("Redis | error=operation_failed fn='%s'", func.__name__)
+            raise RedisServiceError(msg) from e
+
+    return wrapper
+
+
+class BaseRedisService:
+    """Base class that holds a Redis connection.
+
+    Inherit from this class when building a service that wraps a Redis client
+    but does not need the full :class:`~codex_platform.redis_service.service.RedisService`
+    composition.
+    """
+
+    def __init__(self, client: Redis) -> None:
+        """Initialize the service with an existing async Redis client.
+
+        Args:
+            client: An already-constructed ``redis.asyncio.Redis`` instance.
+        """
+        self.redis_client = client

codex_platform/redis_service/exceptions.py

@@ -0,0 +1,20 @@
+"""
+codex_platform.redis_service.exceptions
+=======================================
+Кастомные исключения для работы с Redis.
+
+Используй эти классы в бизнес-логике вместо redis.exceptions.*
+чтобы не зависеть от внутренностей redis-py.
+"""
+
+
+class RedisServiceError(Exception):
+    """Базовый класс для всех ошибок слоя Redis."""
+
+
+class RedisConnectionError(RedisServiceError):
+    """Ошибки сети: таймауты, недоступность сервера, обрывы связи."""
+
+
+class RedisDataError(RedisServiceError):
+    """Ошибки контента: битый JSON, несовпадение типов."""

codex_platform/redis_service/keys.py

@@ -0,0 +1,110 @@
+"""
+codex_platform.redis_service.keys
+================================
+Redis Key Registry — typed, centralized key definitions.
+
+Eliminates "magic strings" and prevents key format mismatches
+across multiple containers (bot, workers, API) that share the same Redis.
+
+Usage::
+
+    class UserKey(BaseRedisKey):
+        template = "u:{user_id}"
+
+    key = UserKey().build(user_id=42)          # → "u:42"
+
+    # Or via resolve_key:
+    from codex_platform.redis_service.keys import resolve_key
+    resolve_key(UserKey(), user_id=42)         # → "u:42"
+    resolve_key("u:42")                        # → "u:42"
+
+Extending for project-specific keys::
+
+    from codex_platform.redis_service.keys import BaseRedisKey
+
+    class JobStatusKey(BaseRedisKey):
+        template = "arq:job:{job_id}:status"
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseRedisKey(ABC):
+    """
+    Abstract base for all Redis key definitions.
+
+    Subclass and define `template` with ``{placeholder}`` syntax.
+    Call ``.build(**kwargs)`` to construct the final key string.
+    """
+
+    @property
+    @abstractmethod
+    def template(self) -> str:
+        """Key template string with ``{placeholder}`` syntax."""
+
+    def build(self, **kwargs: Any) -> str:
+        """Build the final key string by formatting the template with keyword arguments.
+
+        Args:
+            **kwargs: Values for each placeholder defined in ``template``.
+
+        Returns:
+            Fully resolved Redis key string.
+
+        Raises:
+            ValueError: If a required placeholder argument is missing.
+        """
+        try:
+            return self.template.format(**kwargs)
+        except KeyError as e:
+            raise ValueError(f"Missing key argument: {e} for template '{self.template}'") from e
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(template={self.template!r})"
+
+
+def resolve_key(key: "str | BaseRedisKey", **kwargs: Any) -> str:
+    """Resolve a key that is either a plain string or a ``BaseRedisKey`` instance.
+
+    If ``key`` is a :class:`BaseRedisKey`, calls ``key.build(**kwargs)``.
+    If ``key`` is a plain string, returns it unchanged.
+
+    Args:
+        key: Redis key string or a ``BaseRedisKey`` instance.
+        **kwargs: Placeholder values forwarded to ``BaseRedisKey.build``.
+
+    Returns:
+        Resolved Redis key string.
+
+    Example::
+
+        resolve_key(UserKey(), user_id=42)   # → "u:42"
+        resolve_key("u:42")                  # → "u:42"
+    """
+    return key.build(**kwargs) if isinstance(key, BaseRedisKey) else key
+
+
+# ---------------------------------------------------------------------------
+# Shared keys — common across all services
+# ---------------------------------------------------------------------------
+
+
+class UserKey(BaseRedisKey):
+    """User data hash. Args: user_id."""
+
+    template = "u:{user_id}"
+
+
+class SessionKey(BaseRedisKey):
+    """Session data. Args: token."""
+
+    template = "sess:{token}"
+
+
+__all__ = [
+    "BaseRedisKey",
+    "resolve_key",
+    "UserKey",
+    "SessionKey",
+]

codex_platform/redis_service/managers/__init__.py

@@ -0,0 +1,18 @@
+"""
+codex_platform.redis_service.managers
+=======================================
+Business-logic managers built on top of Operations.
+
+Create project-specific managers here::
+
+    from codex_platform.redis_service.managers import BaseRedisManager
+    from codex_platform.redis_service.operations import HashOperations
+
+    class SiteSettingsManager(BaseRedisManager):
+        async def get_settings(self) -> dict:
+            return await self.hash.get_all("site:settings") or {}
+"""
+
+from .base_manager import BaseRedisManager
+
+__all__ = ["BaseRedisManager"]

codex_platform/redis_service/managers/base_manager.py

@@ -0,0 +1,31 @@
+"""
+codex_platform.redis_service.managers.base_manager
+====================================================
+Base class for Redis business-logic managers.
+"""
+
+from redis.asyncio import Redis
+
+from codex_platform.redis_service.operations import HashOperations, StringOperations
+
+
+class BaseRedisManager:
+    """Base manager that initialises common Redis operation helpers.
+
+    Subclass and add only the operation attributes your manager actually needs.
+
+    Example::
+
+        class SiteSettingsManager(BaseRedisManager):
+            async def get_settings(self) -> dict:
+                return await self.hash.get_all("site:settings") or {}
+    """
+
+    def __init__(self, redis_client: Redis) -> None:
+        """Initialize the manager with an existing async Redis client.
+
+        Args:
+            redis_client: An already-constructed ``redis.asyncio.Redis`` instance.
+        """
+        self.hash = HashOperations(redis_client)
+        self.string = StringOperations(redis_client)

codex_platform/redis_service/operations/__init__.py

@@ -0,0 +1,19 @@
+from .hash import HashOperations
+from .json_module import JsonModuleOperations
+from .json_string import JsonStringOperations
+from .list_ import ListOperations
+from .pipeline import PipelineOperations
+from .set_ import SetOperations
+from .string import StringOperations
+from .zset import ZSetOperations
+
+__all__ = [
+    "HashOperations",
+    "StringOperations",
+    "ListOperations",
+    "SetOperations",
+    "ZSetOperations",
+    "JsonStringOperations",
+    "JsonModuleOperations",
+    "PipelineOperations",
+]