Merge branch 'master' of https://github.com/inventree/InvenTree into matmair/issue2519

InvenTree/plugin/__init__.py

@@ -1,3 +1,7 @@
+"""
+Utility file to enable simper imports
+"""
+
 from .registry import plugin_registry
 from .plugin import InvenTreePlugin
 from .integration import IntegrationPluginBase

InvenTree/plugin/builtin/integration/mixins.py

@@ -3,6 +3,8 @@ Plugin mixin classes
 """
 
 import logging
+import json
+import requests
 
 from django.conf.urls import url, include
 from django.db.utils import OperationalError, ProgrammingError
@@ -80,6 +82,7 @@ class ScheduleMixin:
 
     ALLOWABLE_SCHEDULE_TYPES = ['I', 'H', 'D', 'W', 'M', 'Q', 'Y']
 
+    # Override this in subclass model
     SCHEDULED_TASKS = {}
 
     class MixinMeta:
@@ -180,6 +183,25 @@ class ScheduleMixin:
             logger.warning("unregister_tasks failed, database not ready")
 
 
+class EventMixin:
+    """
+    Mixin that provides support for responding to triggered events.
+
+    Implementing classes must provide a "process_event" function:
+    """
+
+    def process_event(self, event, *args, **kwargs):
+        # Default implementation does not do anything
+        raise NotImplementedError
+
+    class MixinMeta:
+        MIXIN_NAME = 'Events'
+
+    def __init__(self):
+        super().__init__()
+        self.add_mixin('events', True, __class__)
+
+
 class UrlsMixin:
     """
     Mixin that enables custom URLs for the plugin
@@ -373,3 +395,113 @@ class ActionMixin:
             "result": self.get_result(),
             "info": self.get_info(),
         }
+
+
+class APICallMixin:
+    """
+    Mixin that enables easier API calls for a plugin
+
+    Steps to set up:
+    1. Add this mixin before (left of) SettingsMixin and PluginBase
+    2. Add two settings for the required url and token/passowrd (use `SettingsMixin`)
+    3. Save the references to keys of the settings in `API_URL_SETTING` and `API_TOKEN_SETTING`
+    4. (Optional) Set `API_TOKEN` to the name required for the token by the external API - Defaults to `Bearer`
+    5. (Optional) Override the `api_url` property method if the setting needs to be extended
+    6. (Optional) Override `api_headers` to add extra headers (by default the token and Content-Type are contained)
+    7. Access the API in you plugin code via `api_call`
+
+    Example:
+    ```
+    from plugin import IntegrationPluginBase
+    from plugin.mixins import APICallMixin, SettingsMixin
+
+
+    class SampleApiCallerPlugin(APICallMixin, SettingsMixin, IntegrationPluginBase):
+        '''
+        A small api call sample
+        '''
+        PLUGIN_NAME = "Sample API Caller"
+
+        SETTINGS = {
+            'API_TOKEN': {
+                'name': 'API Token',
+                'protected': True,
+            },
+            'API_URL': {
+                'name': 'External URL',
+                'description': 'Where is your API located?',
+                'default': 'reqres.in',
+            },
+        }
+        API_URL_SETTING = 'API_URL'
+        API_TOKEN_SETTING = 'API_TOKEN'
+
+        def get_external_url(self):
+            '''
+            returns data from the sample endpoint
+            '''
+            return self.api_call('api/users/2')
+    ```
+    """
+    API_METHOD = 'https'
+    API_URL_SETTING = None
+    API_TOKEN_SETTING = None
+
+    API_TOKEN = 'Bearer'
+
+    class MixinMeta:
+        """meta options for this mixin"""
+        MIXIN_NAME = 'API calls'
+
+    def __init__(self):
+        super().__init__()
+        self.add_mixin('api_call', 'has_api_call', __class__)
+
+    @property
+    def has_api_call(self):
+        """Is the mixin ready to call external APIs?"""
+        if not bool(self.API_URL_SETTING):
+            raise ValueError("API_URL_SETTING must be defined")
+        if not bool(self.API_TOKEN_SETTING):
+            raise ValueError("API_TOKEN_SETTING must be defined")
+        return True
+
+    @property
+    def api_url(self):
+        return f'{self.API_METHOD}://{self.get_setting(self.API_URL_SETTING)}'
+
+    @property
+    def api_headers(self):
+        return {
+            self.API_TOKEN: self.get_setting(self.API_TOKEN_SETTING),
+            'Content-Type': 'application/json'
+        }
+
+    def api_build_url_args(self, arguments):
+        groups = []
+        for key, val in arguments.items():
+            groups.append(f'{key}={",".join([str(a) for a in val])}')
+        return f'?{"&".join(groups)}'
+
+    def api_call(self, endpoint, method: str = 'GET', url_args=None, data=None, headers=None, simple_response: bool = True):
+        if url_args:
+            endpoint += self.api_build_url_args(url_args)
+
+        if headers is None:
+            headers = self.api_headers
+
+        # build kwargs for call
+        kwargs = {
+            'url': f'{self.api_url}/{endpoint}',
+            'headers': headers,
+        }
+        if data:
+            kwargs['data'] = json.dumps(data)
+
+        # run command
+        response = requests.request(method, **kwargs)
+
+        # return
+        if simple_response:
+            return response.json()
+        return response

InvenTree/plugin/events.py

@@ -0,0 +1,177 @@
+"""
+Functions for triggering and responding to server side events
+"""
+
+# -*- coding: utf-8 -*-
+from __future__ import unicode_literals
+
+import logging
+
+from django.conf import settings
+from django.db import transaction
+from django.db.models.signals import post_save, post_delete
+from django.dispatch.dispatcher import receiver
+
+from common.models import InvenTreeSetting
+
+from InvenTree.ready import canAppAccessDatabase
+from InvenTree.tasks import offload_task
+
+from plugin.registry import plugin_registry
+
+
+logger = logging.getLogger('inventree')
+
+
+def trigger_event(event, *args, **kwargs):
+    """
+    Trigger an event with optional arguments.
+
+    This event will be stored in the database,
+    and the worker will respond to it later on.
+    """
+
+    if not canAppAccessDatabase():
+        logger.debug(f"Ignoring triggered event '{event}' - database not ready")
+        return
+
+    logger.debug(f"Event triggered: '{event}'")
+
+    offload_task(
+        'plugin.events.register_event',
+        event,
+        *args,
+        **kwargs
+    )
+
+
+def register_event(event, *args, **kwargs):
+    """
+    Register the event with any interested plugins.
+
+    Note: This function is processed by the background worker,
+    as it performs multiple database access operations.
+    """
+
+    logger.debug(f"Registering triggered event: '{event}'")
+
+    # Determine if there are any plugins which are interested in responding
+    if settings.PLUGIN_TESTING or InvenTreeSetting.get_setting('ENABLE_PLUGINS_EVENTS'):
+
+        with transaction.atomic():
+
+            for slug, plugin in plugin_registry.plugins.items():
+
+                if plugin.mixin_enabled('events'):
+
+                    config = plugin.plugin_config()
+
+                    if config and config.active:
+
+                        logger.debug(f"Registering callback for plugin '{slug}'")
+
+                        # Offload a separate task for each plugin
+                        offload_task(
+                            'plugin.events.process_event',
+                            slug,
+                            event,
+                            *args,
+                            **kwargs
+                        )
+
+
+def process_event(plugin_slug, event, *args, **kwargs):
+    """
+    Respond to a triggered event.
+
+    This function is run by the background worker process.
+
+    This function may queue multiple functions to be handled by the background worker.
+    """
+
+    logger.info(f"Plugin '{plugin_slug}' is processing triggered event '{event}'")
+
+    plugin = plugin_registry.plugins[plugin_slug]
+
+    plugin.process_event(event, *args, **kwargs)
+
+
+def allow_table_event(table_name):
+    """
+    Determine if an automatic event should be fired for a given table.
+    We *do not* want events to be fired for some tables!
+    """
+
+    table_name = table_name.lower().strip()
+
+    # Ignore any tables which start with these prefixes
+    ignore_prefixes = [
+        'account_',
+        'auth_',
+        'authtoken_',
+        'django_',
+        'error_',
+        'exchange_',
+        'otp_',
+        'plugin_',
+        'socialaccount_',
+        'user_',
+        'users_',
+    ]
+
+    if any([table_name.startswith(prefix) for prefix in ignore_prefixes]):
+        return False
+
+    ignore_tables = [
+        'common_notificationentry',
+    ]
+
+    if table_name in ignore_tables:
+        return False
+
+    return True
+
+
+@receiver(post_save)
+def after_save(sender, instance, created, **kwargs):
+    """
+    Trigger an event whenever a database entry is saved
+    """
+
+    table = sender.objects.model._meta.db_table
+
+    if not allow_table_event(table):
+        return
+
+    if created:
+        trigger_event(
+            'instance.created',
+            id=instance.id,
+            model=sender.__name__,
+            table=table,
+        )
+    else:
+        trigger_event(
+            'instance.saved',
+            id=instance.id,
+            model=sender.__name__,
+            table=table,
+        )
+
+
+@receiver(post_delete)
+def after_delete(sender, instance, **kwargs):
+    """
+    Trigger an event whenever a database entry is deleted
+    """
+
+    table = sender.objects.model._meta.db_table
+
+    if not allow_table_event(table):
+        return
+
+    trigger_event(
+        'instance.deleted',
+        model=sender.__name__,
+        table=table,
+    )

InvenTree/plugin/integration.py

@@ -176,6 +176,11 @@ class IntegrationPluginBase(MixinBase, plugin.InvenTreePlugin):
         """check if mixin is enabled and ready"""
         if self.mixin(key):
             fnc_name = self._mixins.get(key)
+
+            # Allow for simple case where the mixin is "always" ready
+            if fnc_name is True:
+                return True
+
             return getattr(self, fnc_name, True)
         return False
     # endregion

InvenTree/plugin/mixins/__init__.py

@@ -2,12 +2,14 @@
 Utility class to enable simpler imports
 """
 
-from ..builtin.integration.mixins import AppMixin, SettingsMixin, ScheduleMixin, UrlsMixin, NavigationMixin
+from ..builtin.integration.mixins import APICallMixin, AppMixin, SettingsMixin, EventMixin, ScheduleMixin, UrlsMixin, NavigationMixin
 from ..builtin.action.mixins import ActionMixin
 from ..builtin.barcode.mixins import BarcodeMixin
 
 __all__ = [
+    'APICallMixin',
     'AppMixin',
+    'EventMixin',
     'NavigationMixin',
     'ScheduleMixin',
     'SettingsMixin',

InvenTree/plugin/plugin.py

@@ -63,3 +63,15 @@ class InvenTreePlugin():
                 raise error
 
         return cfg
+
+    def is_active(self):
+        """
+        Return True if this plugin is currently active
+        """
+
+        cfg = self.plugin_config()
+
+        if cfg:
+            return cfg.active
+        else:
+            return False

InvenTree/plugin/registry.py

@@ -56,6 +56,7 @@ class PluginsRegistry:
 
         # integration specific
         self.installed_apps = []         # Holds all added plugin_paths
+
         # mixins
         self.mixins_settings = {}
 

InvenTree/plugin/samples/integration/api_caller.py

@@ -0,0 +1,32 @@
+"""
+Sample plugin for calling an external API
+"""
+from plugin import IntegrationPluginBase
+from plugin.mixins import APICallMixin, SettingsMixin
+
+
+class SampleApiCallerPlugin(APICallMixin, SettingsMixin, IntegrationPluginBase):
+    """
+    A small api call sample
+    """
+    PLUGIN_NAME = "Sample API Caller"
+
+    SETTINGS = {
+        'API_TOKEN': {
+            'name': 'API Token',
+            'protected': True,
+        },
+        'API_URL': {
+            'name': 'External URL',
+            'description': 'Where is your API located?',
+            'default': 'reqres.in',
+        },
+    }
+    API_URL_SETTING = 'API_URL'
+    API_TOKEN_SETTING = 'API_TOKEN'
+
+    def get_external_url(self):
+        """
+        returns data from the sample endpoint
+        """
+        return self.api_call('api/users/2')

InvenTree/plugin/samples/integration/event_sample.py

@@ -0,0 +1,23 @@
+"""
+Sample plugin which responds to events
+"""
+
+from plugin import IntegrationPluginBase
+from plugin.mixins import EventMixin
+
+
+class EventPluginSample(EventMixin, IntegrationPluginBase):
+    """
+    A sample plugin which provides supports for triggered events
+    """
+
+    PLUGIN_NAME = "EventPlugin"
+    PLUGIN_SLUG = "event"
+    PLUGIN_TITLE = "Triggered Events"
+
+    def process_event(self, event, *args, **kwargs):
+        """ Custom event processing """
+
+        print(f"Processing triggered event: '{event}'")
+        print("args:", str(args))
+        print("kwargs:", str(kwargs))

InvenTree/plugin/samples/integration/scheduled_task.py

@@ -15,10 +15,6 @@ def print_world():
     print("World")
 
 
-def fail_task():
-    raise ValueError("This task should fail!")
-
-
 class ScheduledTaskPlugin(ScheduleMixin, IntegrationPluginBase):
     """
     A sample plugin which provides support for scheduled tasks
@@ -32,14 +28,10 @@ class ScheduledTaskPlugin(ScheduleMixin, IntegrationPluginBase):
         'hello': {
             'func': 'plugin.samples.integration.scheduled_task.print_hello',
             'schedule': 'I',
-            'minutes': 5,
+            'minutes': 45,
         },
         'world': {
             'func': 'plugin.samples.integration.scheduled_task.print_hello',
             'schedule': 'H',
         },
-        'failure': {
-            'func': 'plugin.samples.integration.scheduled_task.fail_task',
-            'schedule': 'D',
-        },
     }

InvenTree/plugin/samples/integration/test_api_caller.py

@@ -0,0 +1,21 @@
+""" Unit tests for action caller sample"""
+
+from django.test import TestCase
+
+from plugin import plugin_registry
+
+
+class SampleApiCallerPluginTests(TestCase):
+    """ Tests for SampleApiCallerPluginTests """
+
+    def test_return(self):
+        """check if the external api call works"""
+        # The plugin should be defined
+        self.assertIn('sample-api-caller', plugin_registry.plugins)
+        plg = plugin_registry.plugins['sample-api-caller']
+        self.assertTrue(plg)
+
+        # do an api call
+        result = plg.get_external_url()
+        self.assertTrue(result)
+        self.assertIn('data', result,)

InvenTree/plugin/test_integration.py

@@ -8,16 +8,16 @@ from django.contrib.auth import get_user_model
 from datetime import datetime
 
 from plugin import IntegrationPluginBase
-from plugin.mixins import AppMixin, SettingsMixin, UrlsMixin, NavigationMixin
+from plugin.mixins import AppMixin, SettingsMixin, UrlsMixin, NavigationMixin, APICallMixin
 from plugin.urls import PLUGIN_BASE
 
 
 class BaseMixinDefinition:
     def test_mixin_name(self):
         # mixin name
-        self.assertEqual(self.mixin.registered_mixins[0]['key'], self.MIXIN_NAME)
+        self.assertIn(self.MIXIN_NAME, [item['key'] for item in self.mixin.registered_mixins])
         # human name
-        self.assertEqual(self.mixin.registered_mixins[0]['human_name'], self.MIXIN_HUMAN_NAME)
+        self.assertIn(self.MIXIN_HUMAN_NAME, [item['human_name'] for item in self.mixin.registered_mixins])
 
 
 class SettingsMixinTest(BaseMixinDefinition, TestCase):
@@ -142,6 +142,79 @@ class NavigationMixinTest(BaseMixinDefinition, TestCase):
         self.assertEqual(self.nothing_mixin.navigation_name, '')
 
 
+class APICallMixinTest(BaseMixinDefinition, TestCase):
+    MIXIN_HUMAN_NAME = 'API calls'
+    MIXIN_NAME = 'api_call'
+    MIXIN_ENABLE_CHECK = 'has_api_call'
+
+    def setUp(self):
+        class MixinCls(APICallMixin, SettingsMixin, IntegrationPluginBase):
+            PLUGIN_NAME = "Sample API Caller"
+
+            SETTINGS = {
+                'API_TOKEN': {
+                    'name': 'API Token',
+                    'protected': True,
+                },
+                'API_URL': {
+                    'name': 'External URL',
+                    'description': 'Where is your API located?',
+                    'default': 'reqres.in',
+                },
+            }
+            API_URL_SETTING = 'API_URL'
+            API_TOKEN_SETTING = 'API_TOKEN'
+
+            def get_external_url(self):
+                '''
+                returns data from the sample endpoint
+                '''
+                return self.api_call('api/users/2')
+        self.mixin = MixinCls()
+
+        class WrongCLS(APICallMixin, IntegrationPluginBase):
+            pass
+        self.mixin_wrong = WrongCLS()
+
+        class WrongCLS2(APICallMixin, IntegrationPluginBase):
+            API_URL_SETTING = 'test'
+        self.mixin_wrong2 = WrongCLS2()
+
+    def test_function(self):
+        # check init
+        self.assertTrue(self.mixin.has_api_call)
+        # api_url
+        self.assertEqual('https://reqres.in', self.mixin.api_url)
+
+        # api_headers
+        headers = self.mixin.api_headers
+        self.assertEqual(headers, {'Bearer': '', 'Content-Type': 'application/json'})
+
+        # api_build_url_args
+        # 1 arg
+        result = self.mixin.api_build_url_args({'a': 'b'})
+        self.assertEqual(result, '?a=b')
+        # more args
+        result = self.mixin.api_build_url_args({'a': 'b', 'c': 'd'})
+        self.assertEqual(result, '?a=b&c=d')
+        # list args
+        result = self.mixin.api_build_url_args({'a': 'b', 'c': ['d', 'e', 'f', ]})
+        self.assertEqual(result, '?a=b&c=d,e,f')
+
+        # api_call
+        result = self.mixin.get_external_url()
+        self.assertTrue(result)
+        self.assertIn('data', result,)
+
+        # wrongly defined plugins should not load
+        with self.assertRaises(ValueError):
+            self.mixin_wrong.has_api_call()
+
+        # cover wrong token setting
+        with self.assertRaises(ValueError):
+            self.mixin_wrong.has_api_call()
+
+
 class IntegrationPluginBaseTests(TestCase):
     """ Tests for IntegrationPluginBase """