feat: add pluggable_override decorator (#64)

[BB-933] 

* Add `pluggable_override`

This adds a new extension point - a `pluggable_override` decorator that allows overriding any function or method by pointing to its alternative implementation in settings.

* Address review comments

* Fix import

Author: Agrendalath

edx_django_utils/plugins/__init__.py

@@ -5,6 +5,7 @@
 """
 
 from .constants import PluginContexts, PluginSettings, PluginSignals, PluginURLs
+from .pluggable_override import pluggable_override
 from .plugin_apps import get_plugin_apps
 from .plugin_contexts import get_plugins_view_context
 from .plugin_manager import PluginError, PluginManager

edx_django_utils/plugins/pluggable_override.py

@@ -0,0 +1,79 @@
+"""
+Allows overriding existing functions and methods with alternative implementations.
+"""
+
+import functools
+from importlib import import_module
+
+from django.conf import settings
+
+
+def pluggable_override(override):
+    """
+    This decorator allows overriding any function or method by pointing to an alternative implementation
+    with `override` param.
+    :param override: path to the alternative function
+
+    Example usage:
+
+    1. Add this decorator to an existing function `OVERRIDE_TRANSFORM` is the variable name in settings that can be
+       used for overriding this function. Remember to add the `OVERRIDE_` prefix to the name to have the consistent
+       namespace for the overrides.
+        >>> @pluggable_override('OVERRIDE_TRANSFORM')
+        ... def transform(value):
+        ...     return value + 10
+
+    2. Prepare an alternative implementation. It will have the same set of arguments as the original function, with the
+       `prev_fn` added at the beginning.
+        >>> def decrement(prev_fn, value):
+        ...     if value >= 10:
+        ...         return value - 1  # Return the decremented value.
+        ...     else:
+        ...         return prev_fn(value) - 1  # Call the original `transform` method before decrementing and returning.
+
+    3. Specify the path in settings (e.g. in `envs/private.py`):
+        >>> OVERRIDE_TRANSFORM = 'transform_plugin.decrement'
+
+        You can also chain overrides:
+        >>> OVERRIDE_TRANSFORM = [
+        ...     'transform_plugin.decrement',
+        ...     'transform_plugin.increment',
+        ... ]
+
+    Another example:
+
+    1. We want to limit access to a Django view (e.g. `common.djangoapps.student.views.dashboard.student_dashboard`)
+       to allow only logged in users. To do this add `OVERRIDE_DASHBOARD` to the original function:
+       >>> @pluggable_override('OVERRIDE_DASHBOARD')
+       ... def student_dashboard(request):
+       ...     ...  # The rest of the implementation is not relevant in this case.
+
+   2. Prepare an alternative implementation (e.g. in `envs/private.py` to make this example simpler):
+      >>> from django.contrib.auth.decorators import login_required
+      ...
+      ... def dashboard(prev_fn, request):
+      ...     return login_required(prev_fn)(request)
+      ...
+      ... OVERRIDE_DASHBOARD = 'lms.envs.private.dashboard'
+    """
+    def decorator(f):
+        @functools.wraps(f)
+        def wrapper(*args, **kwargs):
+            prev_fn = f
+
+            override_functions = getattr(settings, override, ())
+
+            if isinstance(override_functions, str):
+                override_functions = [override_functions]
+
+            for impl in override_functions:
+                module, function = impl.rsplit('.', 1)
+                mod = import_module(module)
+                func = getattr(mod, function)
+
+                prev_fn = functools.partial(func, prev_fn)
+            # Call the last specified function. It can call the previous one, which can call the previous one, etc.
+            # (until it reaches the base implementation). It can also return without calling `prev_fn`.
+            return prev_fn(*args, **kwargs)
+        return wrapper
+    return decorator

edx_django_utils/tests/test_pluggable_override.py

@@ -0,0 +1,61 @@
+"""
+Tests for utilities.
+"""
+
+from django.test import override_settings
+
+from edx_django_utils.plugins import pluggable_override
+
+
+@pluggable_override('OVERRIDE_TRANSFORM')
+def transform(x):
+    return x + 10
+
+
+def decrement(prev_fn, x):
+    if x >= 10:
+        return x - 1
+    else:
+        return prev_fn(x) - 1
+
+
+def double(prev_fn, x):
+    if x >= 11:
+        return x * 2
+    else:
+        return prev_fn(x) * 2
+
+
+def test_no_override():
+    """Test that the original function is called when an override is not specified."""
+    assert transform(10) == 20
+
+
+@override_settings(OVERRIDE_TRANSFORM="{}.decrement".format(__name__))
+def test_override():
+    """Test that the overriding function is called."""
+    assert transform(10) == 9
+
+
+@override_settings(OVERRIDE_TRANSFORM="{}.decrement".format(__name__))
+def test_call_original_function():
+    """Test that the overriding function calls the base one."""
+    assert transform(9) == 18
+
+
+@override_settings(OVERRIDE_TRANSFORM="{0}.decrement,{0}.double".format(__name__).split(','))
+def test_multiple_overrides_call_last_function():
+    """Test that the newest (last) overriding function is called when multiple overrides are specified."""
+    assert transform(11) == 22
+
+
+@override_settings(OVERRIDE_TRANSFORM="{0}.decrement,{0}.double".format(__name__).split(','))
+def test_multiple_overrides_fallback_to_previous_function():
+    """Test that the last overriding function can call the previous one from the chain."""
+    assert transform(10) == 18
+
+
+@override_settings(OVERRIDE_TRANSFORM="{0}.decrement,{0}.double".format(__name__).split(','))
+def test_multiple_overrides_fallback_to_base_function():
+    """Test that the overriding functions can eventually call the base one."""
+    assert transform(9) == 36