django-slack-tools 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

django_slack_tools/slack_messages/message_templates/python.py

@@ -0,0 +1,38 @@
+# noqa: D100
+from __future__ import annotations
+
+import logging
+from typing import Any, TypeVar
+
+from .base import BaseTemplate
+
+_PyObj = TypeVar("_PyObj", dict, list, str)
+
+logger = logging.getLogger(__name__)
+
+
+class PythonTemplate(BaseTemplate[_PyObj]):
+    """Template that renders a dictionary."""
+
+    def __init__(self, template: _PyObj) -> None:
+        """Initialize the template."""
+        self.template = template
+
+    def render(self, context: dict[str, Any]) -> _PyObj:  # noqa: D102
+        logger.debug("Rendering template %r with context %r", self.template, context)
+        result = _format_obj(self.template, context=context)
+        logger.debug("Rendered template %r to %r", self.template, result)
+        return result
+
+
+def _format_obj(obj: _PyObj, *, context: dict[str, Any]) -> _PyObj:
+    if isinstance(obj, dict):
+        return {key: _format_obj(value, context=context) for key, value in obj.items()}
+
+    if isinstance(obj, list):
+        return [_format_obj(item, context=context) for item in obj]
+
+    if isinstance(obj, str):
+        return obj.format_map(context)
+
+    return obj

django_slack_tools/slack_messages/messenger.py

@@ -0,0 +1,158 @@
+# noqa: D100
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from django_slack_tools.slack_messages.backends import BaseBackend
+from django_slack_tools.slack_messages.middlewares import BaseMiddleware
+from django_slack_tools.slack_messages.request import MessageBody, MessageHeader, MessageRequest
+from django_slack_tools.slack_messages.template_loaders import BaseTemplateLoader, TemplateNotFoundError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from django_slack_tools.slack_messages.message_templates import BaseTemplate
+    from django_slack_tools.slack_messages.response import MessageResponse
+
+logger = logging.getLogger(__name__)
+
+
+class Messenger:
+    """Messenger class that sends message using templates and middlewares.
+
+    Components evaluated in order:
+
+    1. Request processing middlewares
+    2. Load template by key and render message in-place
+    4. Send message
+    5. Response processing middlewares (in reverse order)
+    """
+
+    def __init__(
+        self,
+        *,
+        template_loaders: Sequence[BaseTemplateLoader],
+        middlewares: Sequence[BaseMiddleware],
+        messaging_backend: BaseBackend,
+    ) -> None:
+        """Initialize the Messenger.
+
+        Args:
+            template_loaders: A sequence of template loaders.
+                It is tried in order to load the template and the first one that returns a template is used.
+            middlewares: A sequence of middlewares.
+                Middlewares are applied in the order they are provided for request, and in reverse order for response.
+            messaging_backend: The messaging backend to be used.
+        """
+        # Validate the template loaders
+        for tl in template_loaders:
+            if not isinstance(tl, BaseTemplateLoader):
+                msg = f"Expected inherited from {BaseTemplateLoader!s}, got {type(tl)}"
+                raise TypeError(msg)
+
+        self.template_loaders = template_loaders
+
+        # Validate the middlewares
+        for mw in middlewares:
+            if not isinstance(mw, BaseMiddleware):
+                msg = f"Expected inherited from {BaseMiddleware!s}, got {type(mw)}"
+                raise TypeError(msg)
+
+        self.middlewares = middlewares
+
+        # Validate the messaging backend
+        if not isinstance(messaging_backend, BaseBackend):
+            msg = f"Expected inherited from {BaseBackend!s}, got {type(messaging_backend)}"
+            raise TypeError(msg)
+
+        self.messaging_backend = messaging_backend
+
+    def send(
+        self,
+        to: str,
+        *,
+        template: str | None = None,
+        context: dict[str, str],
+        header: MessageHeader | dict[str, Any] | None = None,
+    ) -> MessageResponse | None:
+        """Simplified shortcut for `.send_request()`."""
+        header = MessageHeader.model_validate(header or {})
+        request = MessageRequest(template_key=template, channel=to, context=context, header=header)
+        return self.send_request(request=request)
+
+    def send_request(self, request: MessageRequest) -> MessageResponse | None:
+        """Sends a message request and processes the response."""
+        logger.info("Sending request: %s", request)
+        _request = self._process_request(request)
+        if _request is None:
+            return None
+
+        self._render_message(_request)
+        response = self._deliver_message(_request)
+        _response = self._process_response(response)
+        if _response is None:
+            return None
+
+        logger.info("Response: %s", _response)
+        return response
+
+    def _process_request(self, request: MessageRequest) -> MessageRequest | None:
+        """Processes the request with middlewares in forward order."""
+        for middleware in self.middlewares:
+            logger.debug("Processing request (%s) with middleware %s", request, middleware)
+            new_request = middleware.process_request(request)
+            if new_request is None:
+                logger.warning("Middleware %s returned `None`, skipping remaining middlewares", middleware)
+                return None
+
+            request = new_request
+
+        logger.debug("Request after processing: %s", request)
+        return request
+
+    def _render_message(self, request: MessageRequest) -> None:
+        """Updates the request with rendered message, in-place."""
+        if request.body is not None:
+            logger.debug("Request already has a body, skipping rendering")
+            return
+
+        if request.template_key is None:
+            msg = "Template key is required to render the message"
+            raise ValueError(msg)
+
+        template = self._get_template(request.template_key)
+        logger.debug("Rendering request %s with template: %s", request, template)
+        rendered = template.render(request.context)
+        request.body = MessageBody.model_validate(rendered)
+
+    def _get_template(self, key: str) -> BaseTemplate:
+        """Loads the template by key."""
+        for loader in self.template_loaders:
+            template = loader.load(key)
+            if template is not None:
+                return template
+
+        msg = f"Template with key '{key}' not found"
+        raise TemplateNotFoundError(msg)
+
+    def _deliver_message(self, request: MessageRequest) -> MessageResponse:
+        """Invoke the messaging backend to deliver the message."""
+        logger.debug("Delivering message request: %s", request)
+        response = self.messaging_backend.deliver(request)
+        logger.debug("Response after delivery: %s", response)
+        return response
+
+    def _process_response(self, response: MessageResponse) -> MessageResponse | None:
+        """Processes the response with middlewares in reverse order."""
+        for middleware in reversed(self.middlewares):
+            logger.debug("Processing response (%s) with middleware: %s", response, middleware)
+            new_response = middleware.process_response(response)
+            if new_response is None:
+                logger.warning("Middleware %s returned `None`, skipping remaining middlewares", middleware)
+                return None
+
+            response = new_response
+
+        logger.debug("Response after processing: %s", response)
+        return response

django_slack_tools/slack_messages/middlewares/__init__.py

@@ -0,0 +1,4 @@
+from .base import BaseMiddleware
+from .django import DjangoDatabasePersister, DjangoDatabasePolicyHandler
+
+__all__ = ("BaseMiddleware", "DjangoDatabasePersister", "DjangoDatabasePolicyHandler")

django_slack_tools/slack_messages/middlewares/base.py

@@ -0,0 +1,34 @@
+# noqa: D100
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from django_slack_tools.slack_messages.request import MessageRequest
+    from django_slack_tools.slack_messages.response import MessageResponse
+
+
+class BaseMiddleware:
+    """Base class for middleware components."""
+
+    def process_request(self, request: MessageRequest) -> MessageRequest | None:  # pragma: no cover
+        """Process the incoming requests.
+
+        Args:
+            request: Message request.
+
+        Returns:
+            MessageRequest objects or `None`.
+        """
+        return request
+
+    def process_response(self, response: MessageResponse) -> MessageResponse | None:  # pragma: no cover
+        """Processes a sequence of MessageResponse objects and returns the processed sequence.
+
+        Args:
+            response: Message response.
+
+        Returns:
+            MessageResponse objects or `None`.
+        """
+        return response

django_slack_tools/slack_messages/middlewares/django.py

@@ -0,0 +1,218 @@
+# noqa: D100
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Literal
+
+from slack_bolt import App
+from slack_sdk.errors import SlackApiError
+
+from django_slack_tools.slack_messages.models import SlackMessage, SlackMessageRecipient, SlackMessagingPolicy
+from django_slack_tools.slack_messages.request import MessageHeader, MessageRequest
+
+from .base import BaseMiddleware
+
+if TYPE_CHECKING:
+    from django_slack_tools.slack_messages.messenger import Messenger
+    from django_slack_tools.slack_messages.response import MessageResponse
+
+logger = logging.getLogger(__name__)
+
+
+class DjangoDatabasePersister(BaseMiddleware):
+    """Persist message history to database. If request is `None`, will do nothing."""
+
+    def __init__(self, *, slack_app: App | None = None, get_permalink: bool = False) -> None:
+        """Initialize the middleware.
+
+        Args:
+            slack_app: Slack app instance to use for certain tasks, such as getting permalinks.
+            get_permalink: If `True`, will try to get the permalink of the message.
+        """
+        if get_permalink and not isinstance(slack_app, App):
+            msg = "`slack_app` must be an instance of `App` if `get_permalink` is set `True`."
+            raise ValueError(msg)
+
+        self.slack_app = slack_app
+        self.get_permalink = get_permalink
+
+    def process_response(self, response: MessageResponse) -> MessageResponse | None:  # noqa: D102
+        request = response.request
+        if request is None:
+            logger.warning("No request found in response, skipping persister.")
+            return response
+
+        logger.debug("Getting permalink for message: %s", response)
+        if self.get_permalink:  # noqa: SIM108
+            permalink = self._get_permalink(channel=request.channel, ts=response.ts)
+        else:
+            permalink = ""
+
+        logger.debug("Persisting message history to database: %s", response)
+        try:
+            history = SlackMessage(
+                id=request.id_,
+                channel=request.channel,
+                header=request.header.model_dump(),
+                body=request.body.model_dump() if request.body else {},
+                ok=response.ok,
+                permalink=permalink,
+                ts=response.ts,
+                parent_ts=response.parent_ts or "",
+                request=request.model_dump(),
+                response=response.model_dump(exclude={"request"}),
+                exception=response.error or "",
+            )
+            history.save()
+        except Exception:
+            logger.exception("Error while saving message history: %s", response)
+
+        return response
+
+    def _get_permalink(self, *, channel: str, ts: str | None) -> str:
+        """Get permalink of the message. It returns empty string on error."""
+        if not self.slack_app:
+            logger.warning("Slack app not provided, cannot get permalink.")
+            return ""
+
+        if not ts:
+            logger.warning("No message ts provided, cannot get permalink.")
+            return ""
+
+        try:
+            response = self.slack_app.client.chat_getPermalink(channel=channel, message_ts=ts)
+            return response.get("permalink", default="")
+        except SlackApiError as err:
+            logger.debug("Error while getting permalink: %s", exc_info=err)
+            return ""
+
+
+OnPolicyNotExists = Literal["create", "default", "error"]
+
+
+class DjangoDatabasePolicyHandler(BaseMiddleware):
+    """Middleware to handle Slack messaging policies stored in the database.
+
+    Be cautious when using this middleware because it includes functionality to distribute messages to multiple recipients,
+    which could lead to unwanted infinite loop or recursion if used improperly.
+
+    This middleware contains a secondary protection against infinite loops by injecting a context key to the message context.
+    If the key is found in the context, the middleware will stop the message from being sent. So be careful when modifying the context.
+    """  # noqa: E501
+
+    _RECURSION_DETECTION_CONTEXT_KEY = "__final__"
+    """Recursion detection key injected to message context for fanned-out messages to provide secondary protection against infinite loops."""  # noqa: E501
+
+    def __init__(
+        self,
+        *,
+        messenger: Messenger | str,
+        on_policy_not_exists: OnPolicyNotExists = "error",
+    ) -> None:
+        """Initialize the middleware.
+
+        This middleware will load the policy from the database and send the message to all recipients.
+
+        Args:
+            messenger: Messenger instance or name to use for sending messages.
+                The messenger instance should be different from the one used in the policy handler,
+                because this middleware cannot properly handle fanned-out messages modified by this middleware.
+                Also, there are chances of infinite loops if the same messenger is used.
+            on_policy_not_exists: Action to take when policy is not found.
+        """
+        if on_policy_not_exists not in ("create", "default", "error"):
+            msg = f'Unknown value for `on_policy_not_exists`: "{on_policy_not_exists}"'
+            raise ValueError(msg)
+
+        self._messenger = messenger
+        self.on_policy_not_exists = on_policy_not_exists
+
+    # * It's not desirable to put import in the method,
+    # * but it's the only way to avoid circular imports for now (what's the fix?)
+    @property
+    def messenger(self) -> Messenger:
+        """Get the messenger instance. If it's a string, will get the messenger from the app settings."""
+        if isinstance(self._messenger, str):
+            from django_slack_tools.app_settings import get_messenger
+
+            self._messenger = get_messenger(self._messenger)
+
+        return self._messenger
+
+    def process_request(self, request: MessageRequest) -> MessageRequest | None:  # noqa: D102
+        # TODO(lasuillard): Hacky way to stop the request, need to find a better way
+        #                   Some extra field (request.meta) could be added to share control context
+        if request.context.get(self._RECURSION_DETECTION_CONTEXT_KEY, False):
+            return request
+
+        code = request.channel
+        policy = self._get_policy(code=code)
+        if not policy.enabled:
+            logger.debug("Policy %s is disabled, skipping further messaging", policy)
+            return None
+
+        requests: list[MessageRequest] = []
+        for recipient in policy.recipients.all():
+            default_context = self._get_default_context(recipient)
+            context = {
+                **default_context,
+                **request.context,
+                self._RECURSION_DETECTION_CONTEXT_KEY: True,
+            }
+            header = MessageHeader.model_validate(
+                {
+                    **policy.header_defaults,
+                    **request.header.model_dump(),
+                },
+            )
+            req = MessageRequest(channel=recipient.channel, template_key=policy.code, context=context, header=header)
+            requests.append(req)
+
+        # TODO(lasuillard): How to provide users the access the newly created messages?
+        #                   currently, it's possible with persisters but it would require some additional work
+        # TODO(lasuillard): Can `sys.setrecursionlimit` be used to prevent spamming if recursion occurs?
+        for req in requests:
+            self.messenger.send_request(req)
+
+        # Stop current request
+        return None
+
+    def _get_policy(self, *, code: str) -> SlackMessagingPolicy:
+        """Get the policy for the given code."""
+        try:
+            policy = SlackMessagingPolicy.objects.get(code=code)
+        except SlackMessagingPolicy.DoesNotExist:
+            if self.on_policy_not_exists == "create":
+                logger.warning("No policy found for template key, creating one: %s", code)
+                policy = self._create_policy(code=code)
+            elif self.on_policy_not_exists == "default":
+                policy = SlackMessagingPolicy.objects.get(code="DEFAULT")
+            elif self.on_policy_not_exists == "error":
+                raise
+            else:
+                msg = f'Unknown value for `on_policy_not_exists`: "{self.on_policy_not_exists}"'
+                raise ValueError(msg) from None
+
+        return policy
+
+    def _create_policy(self, *, code: str) -> SlackMessagingPolicy:
+        """Create a policy with the given code.
+
+        Policy created is disabled by default, thus no message will be sent.
+        To modify the default policy creation behavior, simply override this method.
+        """
+        policy = SlackMessagingPolicy.objects.create(
+            code=code,
+            enabled=False,
+            template_type=SlackMessagingPolicy.TemplateType.UNKNOWN,
+        )
+        default_recipients = SlackMessageRecipient.objects.filter(alias="DEFAULT")
+        policy.recipients.set(default_recipients)
+        return policy
+
+    def _get_default_context(self, recipient: SlackMessageRecipient) -> dict:
+        """Create default context for the recipient."""
+        mentions = [mention.mention for mention in recipient.mentions.all()]
+        return {
+            "mentions": mentions,
+        }

django_slack_tools/slack_messages/migrations/0001_initial.py

@@ -3,7 +3,7 @@
 import django.db.models.deletion
 from django.db import migrations, models
 
-import django_slack_tools.utils.slack.django
+import django_slack_tools.slack_messages.validators
 
 
 class Migration(migrations.Migration):
@@ -152,7 +152,7 @@ class Migration(migrations.Migration):
                         blank=True,
                         default=dict,
                         help_text="Default header values applied to messages on creation.",
-                        validators=[django_slack_tools.utils.slack.django.header_validator],
+                        validators=[django_slack_tools.slack_messages.validators.header_validator],
                         verbose_name="Default header",
                     ),
                 ),
@@ -207,7 +207,7 @@ class Migration(migrations.Migration):
                     "header",
                     models.JSONField(
                         help_text="Slack control arguments. Allowed fields are `mrkdwn`, `parse`, `reply_broadcast`, `thread_ts`, `unfurl_links`, `unfurl_media`.",  # noqa: E501
-                        validators=[django_slack_tools.utils.slack.django.header_validator],
+                        validators=[django_slack_tools.slack_messages.validators.header_validator],
                         verbose_name="Header",
                     ),
                 ),
@@ -215,7 +215,7 @@ class Migration(migrations.Migration):
                     "body",
                     models.JSONField(
                         help_text="Message body. Allowed fields are `attachments`, `body`, `text`, `icon_emoji`, `icon_url`, `metadata`, `username`.",  # noqa: E501
-                        validators=[django_slack_tools.utils.slack.django.body_validator],
+                        validators=[django_slack_tools.slack_messages.validators.body_validator],
                         verbose_name="Body",
                     ),
                 ),

django_slack_tools/slack_messages/migrations/0005_alter_slackmessagingpolicy_template_type.py

@@ -0,0 +1,46 @@
+# Generated by Django 4.2.17 on 2024-12-31 13:40
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.db import migrations, models
+
+if TYPE_CHECKING:
+    from django.db.backends.base.schema import BaseDatabaseSchemaEditor
+    from django.db.migrations.state import StateApps
+
+
+def _change_dict_to_python(apps: StateApps, schema_editor: BaseDatabaseSchemaEditor) -> None:
+    db_alias = schema_editor.connection.alias
+    model_type = apps.get_model("slack_messages", "SlackMessagingPolicy")
+    model_type.objects.using(db_alias).filter(template_type="D").update(template_type="P")
+
+
+def _revert_python_to_dict(apps: StateApps, schema_editor: BaseDatabaseSchemaEditor) -> None:
+    db_alias = schema_editor.connection.alias
+    model_type = apps.get_model("slack_messages", "SlackMessagingPolicy")
+    model_type.objects.using(db_alias).filter(template_type="P").update(template_type="D")
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("slack_messages", "0004_slackmessagingpolicy_template_type"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="slackmessagingpolicy",
+            name="template_type",
+            field=models.CharField(
+                choices=[("P", "Python"), ("DJ", "Django"), ("DI", "Django Inline"), ("?", "Unknown")],
+                default="P",
+                help_text="Type of message template.",
+                max_length=2,
+                verbose_name="Template type",
+            ),
+        ),
+        migrations.RunPython(
+            code=_change_dict_to_python,
+            reverse_code=_revert_python_to_dict,
+        ),
+    ]

django_slack_tools/slack_messages/migrations/0006_alter_slackmessage_id.py

@@ -0,0 +1,26 @@
+# Generated by Django 4.2.18 on 2025-03-13 14:03
+
+import uuid
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("slack_messages", "0005_alter_slackmessagingpolicy_template_type"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="slackmessage",
+            name="id",
+            field=models.CharField(
+                default=uuid.uuid4,
+                editable=False,
+                max_length=255,
+                primary_key=True,
+                serialize=False,
+                unique=True,
+            ),
+        ),
+    ]

django_slack_tools/slack_messages/models/mention.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from django.db import models
 from django.utils.translation import gettext_lazy as _
 
-from django_slack_tools.utils.model_mixins import TimestampMixin
+from django_slack_tools.utils.django.model_mixins import TimestampMixin
 
 
 class SlackMentionManager(models.Manager["SlackMention"]):

django_slack_tools/slack_messages/models/message.py

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
+import uuid
+
 from django.db import models
 from django.utils.translation import gettext_lazy as _
 
-from django_slack_tools.utils.model_mixins import TimestampMixin
-from django_slack_tools.utils.slack import body_validator, header_validator
+from django_slack_tools.slack_messages.validators import body_validator, header_validator
+from django_slack_tools.utils.django.model_mixins import TimestampMixin
 
 from .messaging_policy import SlackMessagingPolicy
 
@@ -18,6 +20,7 @@ class SlackMessageManager(models.Manager["SlackMessage"]):
 class SlackMessage(TimestampMixin, models.Model):
     """An Slack message."""
 
+    id = models.CharField(primary_key=True, unique=True, max_length=255, default=uuid.uuid4, editable=False)
     policy = models.ForeignKey(
         SlackMessagingPolicy,
         verbose_name=_("Messaging Policy"),

django_slack_tools/slack_messages/models/message_recipient.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from django.db import models
 from django.utils.translation import gettext_lazy as _
 
-from django_slack_tools.utils.model_mixins import TimestampMixin
+from django_slack_tools.utils.django.model_mixins import TimestampMixin
 
 from .mention import SlackMention
 

django_slack_tools/slack_messages/models/messaging_policy.py

@@ -7,8 +7,8 @@ from typing import TYPE_CHECKING
 from django.db import models
 from django.utils.translation import gettext_lazy as _
 
-from django_slack_tools.utils.model_mixins import TimestampMixin
-from django_slack_tools.utils.slack import header_validator
+from django_slack_tools.slack_messages.validators import header_validator
+from django_slack_tools.utils.django.model_mixins import TimestampMixin
 
 from .message_recipient import SlackMessageRecipient
 
@@ -26,7 +26,7 @@ class SlackMessagingPolicy(TimestampMixin, models.Model):
     class TemplateType(models.TextChoices):
         """Possible template types."""
 
-        DICT = "D", _("Dictionary")
+        PYTHON = "P", _("Python")
         "Dictionary-based template."
 
         DJANGO = "DJ", _("Django")
@@ -66,7 +66,7 @@ class SlackMessagingPolicy(TimestampMixin, models.Model):
         help_text=_("Type of message template."),
         max_length=2,
         choices=TemplateType.choices,
-        default=TemplateType.DICT,
+        default=TemplateType.PYTHON,
     )
     template: models.JSONField[Any] = models.JSONField(
         verbose_name=_("Message template object"),