Do not remove Permission.destroy(), instead deprecate it (usage in existing cookbook)

Author: schloerke

src/posit/connect/_deprecated.py

@@ -0,0 +1,23 @@
+import warnings
+
+
+# From https://github.com/posit-dev/py-shiny/blob/f6b92d8cf49a90f3b3dbb636cd6d7fdeee244cfd/shiny/_deprecated.py#L15C1-L28C1
+# Create our own warning class instead of using built-in DeprecationWarning, because we
+# want to be able to control display of these messages without interfering with the
+# user's control of DeprecationWarning.
+# 2024-11: Change base class to DeprecationWarning
+class PositConnectDeprecationWarning(DeprecationWarning):
+    pass
+
+
+# By default DeprecationWarnings aren't shown; we want to always show them.
+warnings.simplefilter("always", PositConnectDeprecationWarning)
+
+
+def warn_deprecated(message: str, stacklevel: int = 3):
+    warnings.warn(message, PositConnectDeprecationWarning, stacklevel=stacklevel)
+
+
+def warn_deprecated_and_removed_in_future(message: str, stacklevel: int = 3):
+    message += " This method will be removed in a future release."
+    warnings.warn(message, PositConnectDeprecationWarning, stacklevel=stacklevel)

src/posit/connect/permissions.py

@@ -6,6 +6,7 @@
 
 from requests.sessions import Session as Session
 
+from ._deprecated import warn_deprecated_and_removed_in_future
 from .resources import Resource, ResourceParameters, Resources
 
 if TYPE_CHECKING:
@@ -14,8 +15,14 @@
 
 
 class Permission(Resource):
+    def delete(self) -> None:
+        """[Deprecated] Delete the permission."""
+        warn_deprecated_and_removed_in_future("Please use .destroy() instead of .delete().")
+
+        self.destroy()
+
     def destroy(self) -> None:
-        """Delete the permission."""
+        """Destroy the permission."""
         path = f"v1/content/{self['content_guid']}/permissions/{self['id']}"
         url = self.params.url + path
         self.params.session.delete(url)

tests/posit/connect/test_permissions.py

@@ -6,6 +6,7 @@
 import responses
 from responses import matchers
 
+from posit.connect._deprecated import PositConnectDeprecationWarning
 from posit.connect.groups import Group
 from posit.connect.permissions import Permission, Permissions
 from posit.connect.resources import ResourceParameters
@@ -15,7 +16,7 @@
 from .api import load_mock, load_mock_dict, load_mock_list
 
 
-class TestPermissionDelete:
+class TestPermissionDestroy:
     @responses.activate
     def test(self):
         # data
@@ -38,6 +39,29 @@ def test(self):
         # assert
         assert mock_delete.call_count == 1
 
+    @responses.activate
+    def test_destroy_deprecated(self):
+        # data
+        uid = "94"
+        content_guid = "f2f37341-e21d-3d80-c698-a935ad614066"
+
+        # behavior
+        mock_delete = responses.delete(
+            f"https://connect.example/__api__/v1/content/{content_guid}/permissions/{uid}",
+        )
+
+        # setup
+        params = ResourceParameters(requests.Session(), Url("https://connect.example/__api__"))
+        fake_permission = load_mock_dict(f"v1/content/{content_guid}/permissions/{uid}.json")
+        permission = Permission(params, **fake_permission)
+
+        # invoke
+        with pytest.warns(PositConnectDeprecationWarning, match="destroy"):
+            permission.delete()
+
+        # assert
+        assert mock_delete.call_count == 1
+
 
 class TestPermissionUpdate:
     @responses.activate