Merge ~lloydwaltersj/maas:deprecation-marker into maas:master

[Jack Lloyd-Walters]

Add deprecated decorator for use with MAAS Api

Api endpoints and methods that are deprecated have very freeform markings in docstrings and endpoint names.

This should standardise that, as well as expose a new "deprecated" attribute that can be used to programatically determine if an operation/endpoint is deprecated.

[MAAS Lander (maas-lander)]

UNIT TESTS
-b deprecation-marker lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/437/consoleText
COMMIT: 048b4f3cd370b5e52cdb7899d3629f205ded487a

review: Needs Fixing

ed7efec... by Jack Lloyd-Walters on 2022-08-31

Change how docstring is modified

6a8e4e9... by Jack Lloyd-Walters on 2022-08-31

formatting

c9655ff... by Jack Lloyd-Walters on 2022-08-31

remove leftover print

[MAAS Lander (maas-lander)]

UNIT TESTS
-b deprecation-marker lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: c9655ff1871ecb56eb8da345922792e0572af4d4

review: Approve

6454d9a... by Jack Lloyd-Walters on 2022-08-31

use func_name for function name

e1e319c... by Jack Lloyd-Walters on 2022-08-31

Change docstring ordering

80bed44... by Jack Lloyd-Walters on 2022-08-31

formatting

7c8b7bf... by Jack Lloyd-Walters on 2022-08-31

change if-elif-if to if-elif-elise

[MAAS Lander (maas-lander)]

UNIT TESTS
-b deprecation-marker lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 6454d9ad27a9bebd1267d3c9e7fb07a3d56a7b03

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b deprecation-marker lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 7c8b7bf7767392ae95a972275a915fab9035a507

review: Approve

9327ce1... by Jack Lloyd-Walters on 2022-08-31

apply suggestions

[Adam Collard (adam-collard)]

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b deprecation-marker lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 9327ce1ca96652affd8a0cf6a94793e2512baa9e

review: Approve

0f2e286... by Jack Lloyd-Walters on 2022-08-31

seperate methods to handle docstrings

[MAAS Lander (maas-lander)]

UNIT TESTS
-b deprecation-marker lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/452/consoleText
COMMIT: 0f2e286bcca3224239895c72bd54a58f16a4bda0

review: Needs Fixing

[Jack Lloyd-Walters (lloydwaltersj)]

jenkins: !test

4938600... by Jack Lloyd-Walters on 2022-08-31

bring branch up to parity

157ceee... by Jack Lloyd-Walters on 2022-08-31

Change order

[MAAS Lander (maas-lander)]

UNIT TESTS
-b deprecation-marker lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/453/consoleText
COMMIT: 0f2e286bcca3224239895c72bd54a58f16a4bda0

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b deprecation-marker lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 157ceeecc564aa0d9b116a014c861faa4f0e77a3

review: Approve

[Adam Collard (adam-collard)]

review: Approve

diff --git a/src/maasserver/api/commissioning_scripts.py b/src/maasserver/api/commissioning_scripts.py
index 11b2981..477b688 100644
--- a/src/maasserver/api/commissioning_scripts.py
+++ b/src/maasserver/api/commissioning_scripts.py
@@ -11,7 +11,8 @@ from django.shortcuts import get_object_or_404
 from django.urls import reverse
 from piston3.utils import rc
 
-from maasserver.api.support import OperationsHandler
+from maasserver.api.scripts import NodeScriptHandler, NodeScriptsHandler
+from maasserver.api.support import deprecated, OperationsHandler
 from maasserver.api.utils import get_mandatory_param
 from maasserver.audit import create_audit_event
 from maasserver.enum import ENDPOINT
@@ -29,16 +30,15 @@ def get_content_parameter(request):
     return content_file.read()
 
 
+@deprecated(use=NodeScriptsHandler)
 class CommissioningScriptsHandler(OperationsHandler):
     """
     Manage custom commissioning scripts.
 
     This functionality is only available to administrators.
-
-    This endpoint has been deprecated in favor of the node-scripts endpoint.
     """
 
-    api_doc_section_name = "Commissioning scripts (deprecated)"
+    api_doc_section_name = "Commissioning scripts"
 
     update = delete = None
 
@@ -109,16 +109,15 @@ class CommissioningScriptsHandler(OperationsHandler):
         return ("commissioning_scripts_handler", [])
 
 
+@deprecated(use=NodeScriptHandler)
 class CommissioningScriptHandler(OperationsHandler):
     """
     Manage a custom commissioning script.
 
     This functionality is only available to administrators.
-
-    This endpoint has been deprecated in favor of the node-script endpoint.
     """
 
-    api_doc_section_name = "Commissioning script (deprecated)"
+    api_doc_section_name = "Commissioning script"
 
     # Relies on Piston's built-in DELETE implementation.  There is no POST.
     create = None
diff --git a/src/maasserver/api/networks.py b/src/maasserver/api/networks.py
index 0810bd0..bbe0eb8 100644
--- a/src/maasserver/api/networks.py
+++ b/src/maasserver/api/networks.py
@@ -7,7 +7,13 @@
 from django.urls import reverse
 from piston3.utils import rc
 
-from maasserver.api.support import admin_method, operation, OperationsHandler
+from maasserver.api.subnets import SubnetHandler, SubnetsHandler
+from maasserver.api.support import (
+    admin_method,
+    deprecated,
+    operation,
+    OperationsHandler,
+)
 from maasserver.exceptions import MAASAPIValidationError
 from maasserver.forms import NetworksListingForm
 from maasserver.models import Interface, Node, Subnet
@@ -39,14 +45,13 @@ def render_networks_json(subnets):
     return [render_network_json(subnet) for subnet in subnets]
 
 
+@deprecated(use=SubnetHandler)
 class NetworkHandler(OperationsHandler):
     """
     Manage a network.
-
-    This endpoint is deprecated. Use the new 'subnet' endpoint instead.
     """
 
-    api_doc_section_name = "Network (deprecated)"
+    api_doc_section_name = "Network"
     create = None
 
     def read(self, request, name):
@@ -150,11 +155,10 @@ class NetworkHandler(OperationsHandler):
         return ("network_handler", (name,))
 
 
+@deprecated(use=SubnetsHandler)
 class NetworksHandler(OperationsHandler):
     """
     Manage the networks.
-
-    This endpoint is deprecated. Use the new 'subnets' endpoint instead.
     """
 
     api_doc_section_name = "Networks"
diff --git a/src/maasserver/api/nodes.py b/src/maasserver/api/nodes.py
index 3ff069c..04c2457 100644
--- a/src/maasserver/api/nodes.py
+++ b/src/maasserver/api/nodes.py
@@ -20,6 +20,7 @@ from piston3.utils import rc
 from maasserver.api.support import (
     admin_method,
     AnonymousOperationsHandler,
+    deprecated,
     operation,
     OperationsHandler,
 )
@@ -914,6 +915,7 @@ class WorkloadAnnotationsMixin:
         return node
 
     @operation(idempotent=False)
+    @deprecated(use=set_workload_annotations)
     def set_owner_data(self, request, system_id):
         """@description-title Deprecated, use set-workload-annotations.
         @description Deprecated, use set-workload-annotations instead."""
diff --git a/src/maasserver/api/pods.py b/src/maasserver/api/pods.py
index 8af6775..58c8910 100644
--- a/src/maasserver/api/pods.py
+++ b/src/maasserver/api/pods.py
@@ -9,7 +9,12 @@ from django.urls import reverse
 from formencode.validators import String
 from piston3.utils import rc
 
-from maasserver.api.support import admin_method, operation, OperationsHandler
+from maasserver.api.support import (
+    admin_method,
+    deprecated,
+    operation,
+    OperationsHandler,
+)
 from maasserver.api.utils import get_mandatory_param
 from maasserver.exceptions import MAASAPIValidationError, PodProblem
 from maasserver.forms.pods import ComposeMachineForm, DeletePodForm, PodForm
@@ -423,12 +428,10 @@ class VmHostHandler(OperationsHandler):
 
 # Pods are being renamed to VM hosts. Keep the old name on the API as well for
 # backwards-compatibility.
+@deprecated(use=VmHostHandler)
 class PodHandler(VmHostHandler):
     """
     Manage an individual Pod.
-
-    The /pod/ API endpoint is deprecated. Please use the /vm-host/ one instead.
-
     """
 
     api_doc_section_name = "Pod"
@@ -531,13 +534,10 @@ class VmHostsHandler(OperationsHandler):
 
 # Pods are being renamed to VM hosts. Keep the old name on the API as well for
 # backwards-compatibility.
+@deprecated(use=VmHostsHandler)
 class PodsHandler(VmHostsHandler):
     """
     Manage the collection of all the pods in the MAAS.
-
-    The /pods/ API endpoint is deprecated. Please use the /vm-hosts/ one
-    instead.
-
     """
 
     api_doc_section_name = "Pods"
diff --git a/src/maasserver/api/support.py b/src/maasserver/api/support.py
index d86502f..db8b222 100644
--- a/src/maasserver/api/support.py
+++ b/src/maasserver/api/support.py
@@ -14,6 +14,7 @@ __all__ = [
 
 from abc import ABCMeta, abstractproperty
 from functools import wraps
+import inspect
 import re
 
 from django.core.exceptions import PermissionDenied
@@ -26,7 +27,11 @@ from piston3.resource import Resource
 from piston3.utils import HttpStatusCode, rc
 
 from maasserver.api.doc import get_api_description
-from maasserver.exceptions import MAASAPIBadRequest, MAASAPIValidationError
+from maasserver.exceptions import (
+    MAASAPIBadRequest,
+    MAASAPIValidationError,
+    MAASBadDeprecation,
+)
 from maasserver.utils.orm import get_one
 from provisioningserver.logger import LegacyLogger
 
@@ -142,6 +147,56 @@ def operation(idempotent, exported_as=None):
     return _decorator
 
 
+def deprecated(use):
+    """Decorator to note a method or class is deprecated on the API.
+
+    :param use: Name of the method or class that should be used in place of this method"""
+
+    # TODO: Determine any other behaviours we might want from this decorator in future
+
+    def update_method_docstring(func):
+        doc = func.__doc__ if func.__doc__ else ""
+        depr = f"This operation has been deprecated in favour of '{func_name(use)} {func_name(func.deprecated)}'"
+        if "@description" in doc:
+            description = doc.split("@description ")[1].split(".")[0]
+            func.__doc = doc.replace(description, f"{description}. {depr}")
+        else:
+            func.__doc__ = f"{doc}\n{depr}."
+
+    def update_class_docstring(cls):
+        cls.__doc__ = f"{cls.__doc__}\nThe '{func_name(cls)}' endpoint has been deprecated in favour of '{func_name(use)}'."
+        if "(deprecated)" not in cls.api_doc_section_name:
+            cls.api_doc_section_name += " (deprecated)"
+
+    def func_name(func):
+        return re.sub(
+            "[_ ]", "-", getattr(func, "api_doc_section_name", func.__name__)
+        )
+
+    def _decorator(func):
+        if type(func) is not type(use):
+            raise MAASBadDeprecation(
+                f"{func_name(func)} is deprecated in favour of {func_name(use)}, but {type(use)} is not a valid replacement for {type(func)}"
+            )
+        func.deprecated = use
+        # if an endpoint (class) was passed to the decorator, apply the decorator to all of it's methods too
+        if isinstance(func, type):
+            apply_to_methods(func)
+            update_class_docstring(func)
+        else:
+            update_method_docstring(func)
+        return func
+
+    def apply_to_methods(cls):
+        for name, method in inspect.getmembers(cls, inspect.isfunction):
+            new_method = getattr(use, name, None)
+            if new_method:
+                method.deprecated = new_method
+                update_method_docstring(method)
+
+    return _decorator
+
+
 METHOD_RESERVED_ADMIN = "This method is reserved for admin users."
 
 
diff --git a/src/maasserver/api/tests/test_support.py b/src/maasserver/api/tests/test_support.py
index 62fd55e..bbc04c9 100644
--- a/src/maasserver/api/tests/test_support.py
+++ b/src/maasserver/api/tests/test_support.py
@@ -15,6 +15,7 @@ from maasserver.api.doc import get_api_description
 from maasserver.api.support import (
     admin_method,
     AdminRestrictedResource,
+    deprecated,
     Emitter,
     OperationsHandlerMixin,
     OperationsResource,
@@ -180,6 +181,28 @@ class TestAdminMethodDecorator(MAASServerTestCase):
         self.assertEqual((return_value, [call()]), (response, mock.mock_calls))
 
 
+class TestDeprecatedMethodDecorator(MAASServerTestCase):
+    def test_function_marked_as_deprecated(self):
+        def api_replacement_method(self, request):
+            pass
+
+        @deprecated(use=api_replacement_method)
+        def api_method(self, request):
+            pass
+
+        self.assertEqual(api_method.deprecated, api_replacement_method)
+
+    def test_class_marked_as_deprecated(self):
+        class api_replacement_endpoint:
+            api_doc_section_name = "Replacement"
+
+        @deprecated(use=api_replacement_endpoint)
+        class api_endpoint:
+            api_doc_section_name = "Deprecated"
+
+        self.assertEqual(api_endpoint.deprecated, api_replacement_endpoint)
+
+
 class TestOperationsHandlerMixin(MAASTestCase):
     """Tests for :py:class:`maasserver.api.support.OperationsHandlerMixin`."""
 
diff --git a/src/maasserver/exceptions.py b/src/maasserver/exceptions.py
index b811206..4ebae20 100644
--- a/src/maasserver/exceptions.py
+++ b/src/maasserver/exceptions.py
@@ -245,3 +245,7 @@ class StorageClearProblem(MAASAPIException):
 
 class NetworkingResetProblem(MAASException):
     """Raised when an issue occurs that prevents resetting networking configuration."""
+
+
+class MAASBadDeprecation(MAASException):
+    """Raised when an API endpoint or operation has it's deprecation incorrectly assigned."""