Skip to content

Commit 38130e1

Browse files
hmpfhmpf
committed
Move common destination functionality to parent class
.. also make it easioer to validate the settings-field with a django form.
1 parent a18cfcc commit 38130e1

File tree

8 files changed

+478
-229
lines changed

8 files changed

+478
-229
lines changed

‎changelog.d/+cleanup-destination-plugins.changed.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Moved a lot of common infrastructure from our NotificationMedium subclasses to
2+
the parent. This should make it easier to create more media of high quality.
3+
Also, it should make it easier to use the plugins for validating the
4+
settings-file elsewhere than just the API.
5+
6+
This might break 3rd party notification plugins.

‎docs/integrations/notifications/writing-notification-plugins.rst‎

Lines changed: 101 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -28,29 +28,49 @@ implement the following:
2828
Class constants
2929
---------------
3030

31-
You need to set the constants `MEDIA_SLUG`, `MEDIA_NAME` and
32-
`MEDIA_JSON_SCHEMA`.
33-
34-
The media name is the name of the service you want to send notifications by.
35-
This is used only for display purposes so you might want to keep it short and
36-
sweet. So for example `Email`, `SMS` or `MS Teams`.
37-
38-
The media slug is the slugified version of that, so the name simplified to only
39-
contain lowercase letters, numbers, underscores and hyphens. Always have it
40-
start with a letter, a-z. For example `email`, `sms` or `msteams`.
41-
42-
The media `json schema <https://json-schema.org/>`_ is a representation of how
43-
a destination that will be used by this notification plugin should look like.
44-
Such a destination should include all necessary information that is needed to
45-
send notifications with your notification plugin. In case of SMS that is a
46-
phone number or for MS Teams a webhook.
31+
You must set the constants ``MEDIA_SLUG`, `MEDIA_NAME`` and
32+
``MEDIA_JSON_SCHEMA``. If your plugin only takes or needs a single
33+
configuration flag you should also set ``MEDIA_SETTINGS_KEY``.
34+
35+
MEDIA_NAME
36+
The media name is the name of the service you want to send notifications by.
37+
This is used only for display purposes so you might want to keep it short
38+
and sweet. So for example ``"Email"``, ``"SMS"`` or ``"MS Teams"``.
39+
40+
MEDIA_SLUG
41+
The media slug is the slugified version of that, so the name simplified to
42+
only contain lowercase letters, numbers, underscores and hyphens. Always
43+
have it start with a letter, a-z. For example ``"email"``, ``"sms"`` or
44+
``"msteams"``.
45+
46+
MEDIA_JSON_SCHEMA
47+
The media `json schema <https://json-schema.org/>`_ is a representation of
48+
how a destination that will be used by this notification plugin should look
49+
like, so that it is possible to autogenerate a form with javascript. It will
50+
be accessible via the API. Such a destination should include all necessary
51+
information that is needed to send notifications with your notification
52+
plugin. In case of SMS that is a phone number or for MS Teams a webhook.
53+
54+
MEDIA_SETTINGS_KEY
55+
The media settings key is the name of the most important key in the settings
56+
JSON field. It is used to cut down on the amount of code you need to write
57+
if there is only one piece of config you need to send the notification.
58+
Among other things, it is used to check for duplicate entries, so in a way
59+
it acts as the primary key for your plugin. For that reason, it must be
60+
required in the json schema. For example for an email plugin this would be
61+
"email_address".
62+
63+
Form
64+
The ``forms.Form`` used to validate the settings-field.
4765

4866
Class methods for sending notifications
4967
---------------------------------------
5068

5169
.. autoclass:: argus.notificationprofile.media.base.NotificationMedium
5270
:members: send
5371

72+
This MUST be overridden.
73+
5474
The ``send`` method is the method that does the actual sending of the
5575
notification. It gets the Argus event and a list of destinations as input and
5676
returns a boolean indicating if the sending was successful.
@@ -62,35 +82,73 @@ The rest is very dependent on the notification medium and, if used, the Python
6282
library. The given event can be used to extract relevant information that
6383
should be included in the message that will be sent to each destination.
6484

65-
Class methods for destinations
66-
------------------------------
85+
Helper class methods
86+
--------------------
6787

6888
.. autoclass:: argus.notificationprofile.media.base.NotificationMedium
6989
:members: get_label, has_duplicate, raise_if_not_deletable, update, validate
7090
:noindex:
7191

72-
Your implementation of ``get_label`` should show a reasonable representation
73-
for a destination of that type that makes it easy to identify. For SMS that
74-
would simply be the phone number.
75-
76-
The method ``has_duplicate`` will receive a QuerySet of destinations and a dict
77-
of settings for a possible destination and should return True if a destination
78-
with such settings exists in the given QuerySet.
79-
80-
``raise_if_not_deletable`` should check if a given destination can be deleted.
81-
This is used in case some destinations are synced from an outside source and
82-
should not be able to be deleted by a user. If that is the case a
83-
``NotDeletableError`` should be raised. If not simply return None.
84-
85-
The method ``update`` only has to be implemented if the regular update method
86-
of Django isn't sufficient. This can be the case if additional settings need to
87-
be updated.
88-
89-
Finally the function ``validate`` makes sure that a destination with the given
90-
settings can be updated or created. The function ``has_duplicate`` can be used
91-
here to ensure that not two destinations with the same settings will be
92-
created. Additionally the settings themselves should also be validated. For
93-
example for SMS the given phone number will be checked. Django forms can be
94-
helpful for validation. A ``ValidationError`` should be raised if the given
95-
settings are invalid and the validated and cleaned data should be returned if
96-
not.
92+
With a little luck you might not need to override any of these.
93+
94+
clean
95+
This method will do any additional cleaning beyond what is defined by the
96+
defined ``Form``. Expects a valid form instance and optional
97+
DestinationConfig instance, and returns the updated valid form instance. If
98+
you have fields that shouldn't be set by a user, or values that need extra
99+
conversion, you can do that in this method. Use the passed in instance if
100+
you need to fall back to defaults. This method should not be used to
101+
validate anything and thus should never raise a validation Exception.
102+
103+
get_label
104+
Your implementation of ``get_label`` should show a reasonable representation
105+
for a destination of that type that makes it easy to identify. For SMS that
106+
would simply be the phone number. By default it shows the label stored in
107+
the destination. If no label has been set, it uses MEDIA_SETTINGS_KEY to
108+
look up the most important piece of information in the settings and uses
109+
that directly. The included plugins need not override ``get_label`` for this
110+
reason. If the label would be very long, for instance if the needed setting
111+
is a very long url (40+ characters), you ought to write your own
112+
``get_label``.
113+
114+
get_relevant_destination_settings
115+
Used by ``send``. You should only need to override this if the key in
116+
MEDIA_SETTINGS_KEY is insuffcient to look up the actual configuration of the
117+
destinations of the type set by MEDIA_SLUG.
118+
119+
has_duplicate
120+
The method ``has_duplicate`` will receive a QuerySet of destinations and
121+
a dict of settings for a possible destination and should return True if
122+
a destination with such settings exists in the given QuerySet. By default it
123+
will use MEDIA_SETTINGS_KEY to lookup the most important piece of
124+
information in the settings.
125+
126+
raise_if_not_deletable
127+
``raise_if_not_deletable`` should check if a given destination can be
128+
deleted. This is necessary in case the destination is in use by a profile,
129+
or some destinations are synced from an outside source or otherwise
130+
auto-generated, and should not be able to be deleted by a user. If that is
131+
the case a ``NotDeletableError`` should be raised. If not simply return
132+
None.
133+
134+
update
135+
The method ``update`` only has to be implemented if the regular update
136+
method is insufficient. This can be the case if there is more than one
137+
key-value pair in settings that need to be updated.
138+
139+
validate
140+
The function ``validate`` makes sure that a destination with the given
141+
settings can be updated or created. It uses the ``validate_settings`` method
142+
to validate the settings-field, a form (CommonDestinationConfigForm) to
143+
validate the media and label-fields, and an optional DestinationConfig
144+
instance for the sake of the ``clean``-method. The validated form is
145+
returned if ok, otherwise a ``ValidationError`` should be raised. It is
146+
unlikely that you will ever need to override this method.
147+
148+
validate_settings
149+
This method validates the actual contents of the settings-field using the
150+
``Form`` that is defined and an optional DestinationConfig instance for the
151+
sake of the ``clean``-method. The function ``has_duplicate`` can be used
152+
here to ensure that no two destinations with the same settings will be
153+
created. A ``ValidationError`` should be raised if the given settings are
154+
invalid, and the validated and cleaned data should be returned if not.

‎src/argus/notificationprofile/media/__init__.py‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@
2424

2525
LOG = logging.getLogger(__name__)
2626

27-
2827
__all__ = [
2928
"api_safely_get_medium_object",
3029
"send_notification",
@@ -42,6 +41,17 @@
4241
MEDIA_CLASSES_DICT = {media_class.MEDIA_SLUG: media_class for media_class in _media_classes}
4342

4443

44+
class DestinationPluginError(Exception):
45+
pass
46+
47+
48+
def get_medium_object(media_slug: str):
49+
try:
50+
return MEDIA_CLASSES_DICT[str(media_slug)]
51+
except KeyError as e:
52+
raise DestinationPluginError(f'Medium "{media_slug}" is not installed.') from e
53+
54+
4555
def api_safely_get_medium_object(media_slug):
4656
try:
4757
obj = MEDIA_CLASSES_DICT[media_slug]

0 commit comments

Comments
 (0)