Make it easy to retrieve admin and OpenCatalog URL for a share (#94)

* rename method to returns a detailed share
* minor change in docstring
* add model methods to easily retrieve admin and opencatalog urls
* typo

isogeo_pysdk/api/routes_share.py

@@ -109,11 +109,11 @@ def listing(self, workgroup_id: str = None, caching: bool = 1) -> list:
         return shares
 
     @ApiDecorators._check_bearer_validity
-    def share(self, share_id: str, include: list = ["_abilities", "groups"]) -> Share:
-        """Get details about a specific share.
+    def get(self, share_id: str, include: tuple = ("_abilities", "groups")) -> Share:
+        """Returns details about a specific share.
 
         :param str share_id: share UUID
-        :param list include: additionnal subresource to include in the response
+        :param tuple inlude: additionnal subresource to include in the response
         """
         # check share UUID
         if not checker.check_is_uuid(share_id):
@@ -153,7 +153,7 @@ def create(
 
         :param str workgroup_id: identifier of the owner workgroup
         :param Share share: Share model object to create
-        :param int check_exists: check if a share already exists inot the workgroup:
+        :param int check_exists: check if a share already exists into the workgroup:
 
         - 0 = no check
         - 1 = compare name [DEFAULT]

isogeo_pysdk/models/share.py

@@ -12,13 +12,19 @@
 # ##################################
 
 # standard library
+import logging
 import pprint
 
 # other model
 from isogeo_pysdk.models.application import Application
 from isogeo_pysdk.models.catalog import Catalog
 from isogeo_pysdk.models.workgroup import Workgroup
 
+# #############################################################################
+# ########## Globals ###############
+# ##################################
+
+logger = logging.getLogger(__name__)
 
 # #############################################################################
 # ########## Classes ###############
@@ -357,6 +363,43 @@ def urlToken(self) -> str:
         return self._urlToken
 
     # -- METHODS -----------------------------------------------------------------------
+    def admin_url(self, url_base: str = "https://app.isogeo.com") -> str:
+        """Returns the administration URL (https://app.isogeo.com) for this share.
+
+        :param str url_base: base URL of admin site. Defaults to: https://app.isogeo.com
+
+        :rtype: str
+        """
+        creator_id = self._creator.get("_tag")[6:]
+        return "{}/groups/{}/admin/shares/{}".format(url_base, creator_id, self._id)
+
+    def opencatalog_url(
+        self, url_base: str = "https://open.isogeo.com"
+    ) -> str or bool or None:
+        """Returns the OpenCatalog URL for this share or None if OpenCatalog is not enabled.
+
+        :param str url_base: base URL of OpenCatalog. Defaults to: https://open.isogeo.com
+
+        :returns:
+
+            - False if the share type is not 'application'
+            - None if OpenCatalog is not enabled in the share
+            - URL of the OpenCatalog when everything is fine
+
+        """
+        # opencatalog URL is valid only for share's of type 'application'
+        if self.type != "application":
+            logger.warning(
+                "Only shares of type 'application' can have an OpenCatalog URL, "
+                "not '{}'.".format(self.type)
+            )
+            return False
+        # check if the urlToken exists which means that OpenCatalog URL is not allowed
+        if self.urlToken is None:
+            return None
+
+        return "{}/s/{}/{}".format(url_base, self._id, self.urlToken)
+
     def to_dict(self) -> dict:
         """Returns the model properties as a dict"""
         result = {}

isogeo_pysdk/utils.py

@@ -780,8 +780,8 @@ def _duplicate_mng(
         return tags_as_dicts, query_as_dicts
 
     # -- SHARES MANAGEMENT ----------------------------------------------------
-    def share_extender(self, share: dict, results_filtered: dict):
-        """Extend share model with additional informations.
+    def share_extender(self, share: dict, results_filtered: dict) -> dict:
+        """Extends a share model with additional informations.
 
         :param dict share: share returned by API
         :param dict results_filtered: filtered search result

tests/test_shares.py

@@ -32,13 +32,14 @@
 
 
 # module target
-from isogeo_pysdk import Isogeo, Share
+from isogeo_pysdk import Isogeo, Share, IsogeoUtils
 
 
 # #############################################################################
 # ######## Globals #################
 # ##################################
 
+utils = IsogeoUtils()
 
 if Path("dev.env").exists():
     load_dotenv("dev.env", override=True)
@@ -101,6 +102,8 @@ def setUpClass(cls):
             password=environ.get("ISOGEO_USER_PASSWORD"),
         )
 
+        utils.set_base_url(environ.get("ISOGEO_PLATFORM", "qa"))
+
     def setUp(self):
         """Executed before each test."""
         # tests stuff
@@ -287,6 +290,45 @@ def test_shares_get_workgroup(self):
             self.assertEqual(share.type, i.get("type"))
             self.assertEqual(share.urlToken, i.get("urlToken"))
 
+    def test_shares_get_detailed_basic(self):
+        """GET :groups/{workgroup_uuid}/shares}"""
+        # retrieve workgroup shares
+        wg_shares = self.isogeo.share.listing(workgroup_id=WORKGROUP_TEST_FIXTURE_UUID)
+
+        # pick a random share
+        share_id_app = sample(
+            [i for i in wg_shares if i.get("type") == "application"], 1
+        )[0].get("_id")
+        share_id_group = sample([i for i in wg_shares if i.get("type") == "group"], 1)[
+            0
+        ].get("_id")
+
+        # get the detailed shares
+        share_appli = self.isogeo.share.get(share_id=share_id_app)
+        share_group = self.isogeo.share.get(share_id=share_id_group)
+
+        # checks
+        for share in (share_appli, share_group):
+            self.assertIsInstance(share, Share)
+            # tests attributes structure
+            self.assertTrue(hasattr(share, "_created"))
+            self.assertTrue(hasattr(share, "_creator"))
+            self.assertTrue(hasattr(share, "_id"))
+            self.assertTrue(hasattr(share, "_modified"))
+            self.assertTrue(hasattr(share, "applications"))
+            self.assertTrue(hasattr(share, "catalogs"))
+            self.assertTrue(hasattr(share, "groups"))
+            self.assertTrue(hasattr(share, "name"))
+            self.assertTrue(hasattr(share, "rights"))
+            self.assertTrue(hasattr(share, "type"))
+            self.assertTrue(hasattr(share, "urlToken"))
+        # test methods
+        self.assertIn("app", share_appli.admin_url(utils.app_url))
+        self.assertIsInstance(share_appli.opencatalog_url(utils.oc_url), (str, None))
+
+        self.assertIn("app", share_group.admin_url(utils.app_url))
+        self.assertFalse(share_group.opencatalog_url(utils.oc_url))
+
     # -- PUT/PATCH --
     # def test_shares_update(self):
     #     """PUT :groups/{workgroup_uuid}/shares/{share_uuid}}"""