Propose INotifier

changes/8200.feature

@@ -0,0 +1,2 @@
+Implement interface INotifier to allow extensions to send custom notifications.
+Skip CKAN email sending if smtp server is not defined.

ckan/config/config_declaration.yaml

@@ -1674,6 +1674,23 @@ groups:
         example: ckan-errors@example.com
         description: This controls from which email the error messages will come from.
 
+  - annotation: Notifier settings
+    options:
+      - key: ckan.notifier.notify_all
+        type: bool
+        default: false
+        example: "true"
+        description: |
+          Send notification to all plugins if True, otherwise only to the
+          first plugin implementing ``INotifier.notify_recipient``.
+
+      - key: ckan.notifier.always_send_email
+        type: bool
+        default: true
+        example: "false"
+        description: |
+          Send email notifications to users even if they have already been
+          notified by plugins.
 
   - annotation: Background Job Settings
     options:

ckan/lib/mailer.py

@@ -17,6 +17,7 @@
 
 
 import ckan
+from ckan import plugins
 import ckan.model as model
 import ckan.lib.helpers as h
 from ckan.lib.base import render
@@ -180,10 +181,27 @@ def mail_recipient(recipient_name: str,
     '''
     site_title = config.get('ckan.site_title')
     site_url = config.get('ckan.site_url')
-    return _mail_recipient(
-        recipient_name, recipient_email,
-        site_title, site_url, subject, body,
-        body_html=body_html, headers=headers, attachments=attachments)
+    notify_all = config.get('ckan.notifier.notify_all')
+    notification_sent = False
+    for plugin in plugins.PluginImplementations(plugins.INotifier):
+        # Allow extensions to use other notification methods
+        notification_sent = plugin.notify_recipient(
+            recipient_name, recipient_email, subject,
+            body, body_html, headers, attachments
+        )
+        if notification_sent and not notify_all:
+            break
+
+    # send an email ONLY if we have smtp settings available
+    always_send_email = config.get('ckan.notifier.always_send_email')
+    if notification_sent and not always_send_email:
+        return
+    if config.get('smtp.server'):
+        _mail_recipient(
+            recipient_name, recipient_email,
+            site_title, site_url, subject, body,
+            body_html, headers, attachments
+        )
 
 
 def mail_user(recipient: model.User,

ckan/plugins/interfaces.py

@@ -7,8 +7,8 @@
 from __future__ import annotations
 
 from typing import (
-    Any, Callable, Iterable, Mapping, Optional, Sequence,
-    TYPE_CHECKING, Union,
+    Any, Callable, IO, Iterable, Mapping, Optional, Sequence,
+    TYPE_CHECKING, Tuple, Union
 )
 
 from flask.blueprints import Blueprint
@@ -31,6 +31,14 @@
     from ckan.config.declaration import Declaration, Key
 
 
+AttachmentWithType = Union[
+    Tuple[str, IO[str], str],
+    Tuple[str, IO[bytes], str]
+]
+AttachmentWithoutType = Union[Tuple[str, IO[str]], Tuple[str, IO[bytes]]]
+Attachment = Union[AttachmentWithType, AttachmentWithoutType]
+
+
 __all__ = [
     u'Interface',
     u'IMiddleware',
@@ -63,6 +71,7 @@
     u'IApiToken',
     u'IClick',
     u'ISignal',
+    u'INotifier',
 ]
 
 
@@ -2180,3 +2189,71 @@ def get_signal_subscriptions(self):
 
         """
         return {}
+
+
+class INotifier(Interface):
+    """
+    Allow plugins to add custom notification mechanisms. CKAN by default uses
+    email notifications. This interface allows plugins to add custom
+    notification mechanisms.
+
+    You can skip CKAN email notifications with
+    ``ckan.notifier.always_send_email=False`` (defaults: ``True``)
+    in your configuration file.
+    You can allow multiple plugins to send notifications by setting
+    ``ckan.notifier.notify_all=True`` (defaults: ``False``).
+    If ``False``, only the first plugin
+    that returns ``True`` for ``notify_recipient`` will send the notification.
+
+    """
+
+    def notify_recipient(
+        self,
+        recipient_name: str,
+        recipient_email: str,
+        subject: str,
+        body: str,
+        body_html: Optional[str] = None,
+        headers: Optional[dict[str, Any]] = None,
+        attachments: Optional[Iterable[Attachment]] = None
+    ) -> bool:
+        '''Sends an notification to a user.
+
+        .. note:: This custom notification could replace the default
+            email mechanism.
+
+        :param recipient_name: the name of the recipient
+        :type recipient: string
+        :param recipient_email: the email address of the recipient
+        :type recipient: string
+
+        :param subject: the notification subject
+        :type subject: string
+        :param body: the notification body, in plain text
+        :type body: string
+        :param body_html: the notification body, in html format (optional)
+        :type body_html: string
+        :headers: extra headers to add to notification, in the form
+            {'Header name': 'Header value'}
+        :type: dict
+        :attachments: a list of tuples containing file attachments to add to
+            the notification.
+            Tuples should contain the file name and a file-like
+            object pointing to the file contents::
+
+                [
+                    ('some_report.csv', file_object),
+                ]
+
+            Optionally, you can add a third element to the tuple containing the
+            media type::
+
+                [
+                    ('some_report.csv', file_object, 'text/csv'),
+                ]
+        :type: list
+
+        :returns: True if the notification was sent successfully,
+                  False otherwise
+        '''
+        return False

ckanext/example_inotifier/plugin.py

@@ -0,0 +1,63 @@
+"""
+Two test notifiers
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+from ckan import plugins
+
+
+log = logging.getLogger(__name__)
+
+
+class ExampleINotifier1Plugin(plugins.SingletonPlugin):
+    plugins.implements(plugins.INotifier, inherit=True)
+
+    def notify_recipient(
+        self,
+        recipient_name: str,
+        recipient_email: str,
+        subject: str,
+        body: str,
+        body_html: Optional[str] = None,
+        headers: Optional[dict[str, Any]] = None,
+        attachments: Any = None
+    ) -> bool:
+
+        msg = (
+            f'Notification [1] example for {recipient_name} '
+            f'<{recipient_email}> '
+            f'with subject {subject} and body {body} or {body_html} '
+            f'and headers {headers} and attachments {attachments}'
+        )
+        log.info(msg)
+
+        # Here you would send an email to the recipient
+        return True
+
+
+class ExampleINotifier2Plugin(plugins.SingletonPlugin):
+    plugins.implements(plugins.INotifier, inherit=True)
+
+    def notify_recipient(
+        self,
+        recipient_name: str,
+        recipient_email: str,
+        subject: str,
+        body: str,
+        body_html: Optional[str] = None,
+        headers: Optional[dict[str, Any]] = None,
+        attachments: Any = None
+    ) -> bool:
+
+        msg = (
+            f'Notification [2] example for {recipient_name} '
+            f'<{recipient_email}> '
+            f'with subject {subject} and body {body} or {body_html} '
+            f'and headers {headers} and attachments {attachments}'
+        )
+        log.info(msg)
+
+        # Here you would send an email to the recipient
+        return True

ckanext/example_inotifier/test/test_plugin.py

@@ -0,0 +1,62 @@
+import pytest
+from unittest.mock import patch
+from ckan.lib.mailer import mail_recipient
+
+
+test_email = {
+    "recipient_name": "Bob",
+    "recipient_email": "bob@example.com",
+    "subject": "Meeting",
+    "body": "The meeting is cancelled",
+    "headers": {"header1": "value1"},
+}
+
+
+@pytest.mark.ckan_config(
+    "ckan.plugins", "example_inotifier1 example_inotifier2"
+)
+@pytest.mark.usefixtures("with_plugins", "non_clean_db")
+class TestINotifier:
+
+    @pytest.mark.ckan_config("ckan.notifier.always_send_email", "true")
+    @pytest.mark.ckan_config("ckan.notifier.notify_all", "true")
+    @patch("ckan.lib.mailer._mail_recipient")
+    @patch("ckanext.example_inotifier.plugin.ExampleINotifier1Plugin.notify_recipient")
+    @patch("ckanext.example_inotifier.plugin.ExampleINotifier2Plugin.notify_recipient")
+    def test_inotifier_full(self, nr2, nr1, mr):
+        mail_recipient(**test_email)
+        mr.assert_called()
+        assert mr.call_args_list[0][0][0] == test_email["recipient_name"]
+
+        nr1.assert_called()
+        assert nr1.call_args_list[0][0][0] == test_email["recipient_name"]
+        nr2.assert_called()
+        assert nr2.call_args_list[0][0][0] == test_email["recipient_name"]
+
+    @pytest.mark.ckan_config("ckan.notifier.always_send_email", "false")
+    @pytest.mark.ckan_config("ckan.notifier.notify_all", "true")
+    @patch("ckan.lib.mailer._mail_recipient")
+    @patch("ckanext.example_inotifier.plugin.ExampleINotifier1Plugin.notify_recipient")
+    @patch("ckanext.example_inotifier.plugin.ExampleINotifier2Plugin.notify_recipient")
+    def test_mail_inotifier_no_mail(self, nr2, nr1, mr):
+        mail_recipient(**test_email)
+        # We do not send email because we send custom notifications
+        mr.assert_not_called()
+        nr1.assert_called()
+        assert nr1.call_args_list[0][0][0] == test_email["recipient_name"]
+        nr2.assert_called()
+        assert nr2.call_args_list[0][0][0] == test_email["recipient_name"]
+
+    @pytest.mark.ckan_config("ckan.notifier.always_send_email", "false")
+    @pytest.mark.ckan_config("ckan.notifier.notify_all", "false")
+    @patch("ckan.lib.mailer._mail_recipient")
+    @patch("ckanext.example_inotifier.plugin.ExampleINotifier1Plugin.notify_recipient")
+    @patch("ckanext.example_inotifier.plugin.ExampleINotifier2Plugin.notify_recipient")
+    def test_inotifier_no_mail_just_one(self, nr2, nr1, mr):
+        mail_recipient(**test_email)
+        # We do not send email because we send custom notifications
+        mr.assert_not_called()
+        nr1.assert_called()
+        assert nr1.call_args_list[0][0][0] == test_email["recipient_name"]
+        # We just send the first notification
+        nr2.assert_not_called()

setup.cfg

@@ -138,6 +138,8 @@ ckan.plugins =
     example_icolumntypes = ckanext.example_icolumntypes.plugin:ExampleIColumnTypesPlugin
     example_icolumnconstraints = ckanext.example_icolumnconstraints.plugin:ExampleIColumnConstraintsPlugin
     example_idatadictionaryform = ckanext.example_idatadictionaryform.plugin:ExampleIDataDictionaryFormPlugin
+    example_inotifier1 = ckanext.example_inotifier.plugin:ExampleINotifier1Plugin
+    example_inotifier2 = ckanext.example_inotifier.plugin:ExampleINotifier2Plugin
 
 ckan.system_plugins =
     synchronous_search = ckan.lib.search:SynchronousSearchPlugin