From 2ef5f2213cdc561bbe762d4d4a6d22ecd57bce9e Mon Sep 17 00:00:00 2001
From: Grant Orndorff <grant.orndorff@canonical.com>
Date: Thu, 20 Jun 2024 15:44:29 -0400
Subject: [PATCH] docs: add api docs to magic revoke

---
 uaclient/api/exceptions.py                   |  4 ++
 uaclient/api/u/pro/attach/magic/revoke/v1.py | 59 +++++++++++++++++++-
 2 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/uaclient/api/exceptions.py b/uaclient/api/exceptions.py
index 586572a37e..a41286b73f 100644
--- a/uaclient/api/exceptions.py
+++ b/uaclient/api/exceptions.py
@@ -11,6 +11,8 @@
     IncompatibleServiceStopsEnable,
     InvalidProImage,
     LockHeldError,
+    MagicAttachTokenAlreadyActivated,
+    MagicAttachTokenError,
     MagicAttachUnavailable,
     NonAutoAttachImageError,
     NonRootUserError,
@@ -28,6 +30,8 @@
     "EntitlementNotFoundError",
     "InvalidProImage",
     "LockHeldError",
+    "MagicAttachTokenAlreadyActivated",
+    "MagicAttachTokenError",
     "MagicAttachUnavailable",
     "NonAutoAttachImageError",
     "NonRootUserError",
diff --git a/uaclient/api/u/pro/attach/magic/revoke/v1.py b/uaclient/api/u/pro/attach/magic/revoke/v1.py
index 23541f9524..7aaeff814e 100644
--- a/uaclient/api/u/pro/attach/magic/revoke/v1.py
+++ b/uaclient/api/u/pro/attach/magic/revoke/v1.py
@@ -1,3 +1,4 @@
+from uaclient.api import exceptions
 from uaclient.api.api import APIEndpoint
 from uaclient.api.data_types import AdditionalInfo
 from uaclient.config import UAConfig
@@ -7,7 +8,11 @@
 
 class MagicAttachRevokeOptions(DataObject):
     fields = [
-        Field("magic_token", StringDataValue),
+        Field(
+            "magic_token",
+            StringDataValue,
+            doc="The Token provided by the initiate endpoint.",
+        ),
     ]
 
     def __init__(self, magic_token):
@@ -25,6 +30,9 @@ def revoke(options: MagicAttachRevokeOptions) -> MagicAttachRevokeResult:
 def _revoke(
     options: MagicAttachRevokeOptions, cfg: UAConfig
 ) -> MagicAttachRevokeResult:
+    """
+    This endpoint revokes a Magic Attach Token.
+    """
     contract = UAContractClient(cfg)
     contract.revoke_magic_attach_token(options.magic_token)
 
@@ -37,3 +45,52 @@ def _revoke(
     fn=_revoke,
     options_cls=MagicAttachRevokeOptions,
 )
+
+_doc = {
+    "introduced_in": "27.11",
+    "example_python": """
+from uaclient.api.u.pro.attach.magic.revoke.v1 import MagicAttachRevokeOptions, revoke
+
+options = MagicAttachWaitOptions(magic_token="<magic_token>")
+result = revoke(options)
+""",  # noqa: E501
+    "result_cls": MagicAttachRevokeResult,
+    "exceptions": [
+        (
+            exceptions.ConnectivityError,
+            (
+                "Raised if it is not possible to connect to the contracts"
+                " service."
+            ),
+        ),
+        (
+            exceptions.ContractAPIError,
+            (
+                "Raised if there is an unexpected error in the contracts"
+                " service interaction."
+            ),
+        ),
+        (
+            exceptions.MagicAttachTokenAlreadyActivated,
+            (
+                "Raised when trying to revoke a Token which was already"
+                " activated through the UI."
+            ),
+        ),
+        (
+            exceptions.MagicAttachTokenError,
+            "Raised when an invalid/expired Token is sent.",
+        ),
+        (
+            exceptions.MagicAttachUnavailable,
+            (
+                "Raised if the Magic Attach service is busy or unavailable at"
+                " the moment."
+            ),
+        ),
+    ],
+    "example_cli": "pro api u.pro.attach.magic.revoke.v1 --args magic_token=<token>",  # noqa: E501
+    "example_json": """
+{}
+""",
+}