Merge pull request #769 from CitrineInformatics/feature/PLA-9753-expose-cross-team-resource-listing-endpoints

Feature/pla 9753 expose cross team resource listing endpoints

Author: crleblanc

docs/source/getting_started/teams.rst

@@ -125,3 +125,32 @@ A user's actions in a team can be updated. The method
 
     # Make the user a member with read and write access
     team.update_user_actions(user_uid=user_id, actions=[READ, WRITE])
+
+
+Listing Publish Resources in a Team
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Teams can list the published IDs for datasets, modules, tables and table
+definitions available in a team.  Using the `list_readable`,
+`list_writeable`, or `list_shareable` methods to list IDs with these
+permissions.  Note: these calls return a list of string uids, not the
+complete resource objects.
+
+:func:`~citrine.resources.team.Team.dataset_ids`,
+:func:`~citrine.resources.team.Team.module_ids`,
+:func:`~citrine.resources.team.Team.table_ids`,
+:func:`~citrine.resources.team.Team.table_definition_ids`.
+
+
+.. code-block:: python
+
+    team = citrine.teams.get("baaa467e-1758-43a8-97c7-76e569d0dcab")
+    project1 = team.projects.get("8ad2f784-5c49-45ad-b525-6af859651acf")
+
+    dataset_ids = team.dataset_ids.list_readable()
+
+    # Use one of the IDs to get a handle to the resource from it's origin project:
+    dataset = project1.datasets.get(dataset_ids[0])
+
+    # Pull this published resource into another project:
+    project2 = team.projects.get("9ecb5610-6f69-4175-a1f8-bbfd7d711826")
+    project2.pull_in_resource(resource=dataset)

src/citrine/__version__.py

@@ -1 +1 @@
-__version__ = '1.35.1'
+__version__ = '1.36.0'

src/citrine/resources/team.py

@@ -33,6 +33,79 @@ def __str__(self):
             .format(self.user.screen_name, self.actions, self.team.name)
 
 
+class TeamResourceIDs:
+    """
+    A Citrine Team Resource IDs class.
+
+    This class is used to list the unique IDs for specific resource
+    types published in a single team and therefore available to be pulled
+    in by all projects.
+
+    Parameters
+    ----------
+    team_id: str or uuid
+        ID of the team.
+    resource_type: str
+        The resource type to list, one of DATASET/MODULE/TABLE/TABLE_DEFINITION
+
+    """
+
+    _api_version = "v3"
+
+    def __init__(self,
+                 session: Session,
+                 team_id: Union[str, UUID],
+                 resource_type: str) -> None:
+        self.session = session
+        self.team_id = team_id
+        self.resource_type = resource_type
+
+    def _path(self) -> str:
+        return format_escaped_url(f'/teams/{self.team_id}')
+
+    def _list_ids(self, action: str) -> List[str]:
+        query_params = {"domain": self._path(), "action": action}
+        return self.session.get_resource(f"/{self.resource_type}/authorized-ids",
+                                         params=query_params,
+                                         version=self._api_version)['ids']
+
+    def list_readable(self):
+        """
+        List IDs of the published resources with READ access.
+
+        Returns
+        -------
+        List[str]
+            Returns a list of string UUIDs for each resource
+
+        """
+        return self._list_ids(action=READ)
+
+    def list_writeable(self):
+        """
+        List IDs of the published resources with WRITE access.
+
+        Returns
+        -------
+        List[str]
+            Returns a list of string UUIDs for each resource
+
+        """
+        return self._list_ids(action=WRITE)
+
+    def list_shareable(self):
+        """
+        List IDs of the published resources with SHARE access.
+
+        Returns
+        -------
+        List[str]
+            Returns a list of string UUIDs for each resource
+
+        """
+        return self._list_ids(action=SHARE)
+
+
 class Team(Resource['Team']):
     """
     A Citrine Team.
@@ -292,6 +365,34 @@ def projects(self) -> ProjectCollection:
         """Return a resource representing all visible projects in this team."""
         return ProjectCollection(self.session, team_id=self.uid)
 
+    @property
+    def dataset_ids(self) -> TeamResourceIDs:
+        """Return a TeamResourceIDs instance for listing published dataset IDs."""
+        return TeamResourceIDs(session=self.session,
+                               team_id=self.uid,
+                               resource_type=ResourceTypeEnum.DATASET.value)
+
+    @property
+    def module_ids(self) -> TeamResourceIDs:
+        """Return a TeamResourceIDs instance for listing published module IDs."""
+        return TeamResourceIDs(session=self.session,
+                               team_id=self.uid,
+                               resource_type=ResourceTypeEnum.MODULE.value)
+
+    @property
+    def table_ids(self) -> TeamResourceIDs:
+        """Return a TeamResourceIDs instance for listing published table IDs."""
+        return TeamResourceIDs(session=self.session,
+                               team_id=self.uid,
+                               resource_type=ResourceTypeEnum.TABLE.value)
+
+    @property
+    def table_definition_ids(self) -> TeamResourceIDs:
+        """Return a TeamResourceIDs instance for listing published table definition IDs."""
+        return TeamResourceIDs(session=self.session,
+                               team_id=self.uid,
+                               resource_type=ResourceTypeEnum.TABLE_DEFINITION.value)
+
 
 class TeamCollection(Collection[Team]):
     """

tests/resources/test_team.py

@@ -303,3 +303,45 @@ def test_un_share(team, other_team, session):
     )
     assert expect_call == session.last_call
     assert share_response is True
+
+
+@pytest.mark.parametrize("resource_type,method",
+    [
+        (ResourceTypeEnum.DATASET, "dataset_ids"),
+        (ResourceTypeEnum.MODULE, "module_ids"),
+        (ResourceTypeEnum.TABLE, "table_ids"),
+        (ResourceTypeEnum.TABLE_DEFINITION, "table_definition_ids")
+    ])
+def test_list_resource_ids(team, session, resource_type, method):
+    # Given
+    read_response = {'ids': [uuid.uuid4(), uuid.uuid4()]}
+    write_response = {'ids': [uuid.uuid4(), uuid.uuid4()]}
+    share_response = {'ids': [uuid.uuid4(), uuid.uuid4()]}
+
+    # When
+    # This is equivalent to team.dataset_ids, team.module_ids, etc.
+    resource_listing = getattr(team, method)
+    session.set_response(read_response)
+    readable_ids = resource_listing.list_readable()
+    session.set_response(write_response)
+    writeable_ids = resource_listing.list_writeable()
+    session.set_response(share_response)
+    shareable_ids = resource_listing.list_shareable()
+
+    with pytest.raises(AttributeError):
+        setattr(team, method, [])
+
+    # Then
+    assert session.num_calls == 3
+    assert session.calls[0] == FakeCall(method='GET',
+                                        path=f'/{resource_type.value}/authorized-ids',
+                                        params={"domain": f"/teams/{team.uid}", "action": READ})
+    assert session.calls[1] == FakeCall(method='GET',
+                                        path=f'/{resource_type.value}/authorized-ids',
+                                        params={"domain": f"/teams/{team.uid}", "action": WRITE})
+    assert session.calls[2] == FakeCall(method='GET',
+                                        path=f'/{resource_type.value}/authorized-ids',
+                                        params={"domain": f"/teams/{team.uid}", "action": SHARE})
+    assert readable_ids == read_response['ids']
+    assert writeable_ids == write_response['ids']
+    assert shareable_ids == share_response['ids']