[PNE-241] Data Manager support.

Datasets and all related objects now belong to teams, so new endpoints
have been introduced into the platform to support this. As such, all
such calls need to be updated. The result is a bunch of
`ProjectCollection` methods are being deprecated in favor of their
`TeamCollection` equivalents, and many methods which accepted a project
or project_id must be moved to a team/team_id.

The vast majority of behaviors will remain unchanged when using the
deprecated methods, until we bump the major version of the SDK and drop
the old endpoints. The major exception is that creating a dataset on a
project endpoint will register it to a team, so it will be omitted when
you list your datasets by project.

Author: Lenore Kubie

src/citrine/__version__.py

@@ -1 +1 @@
-__version__ = "3.3.0"
+__version__ = "3.4.0"

src/citrine/_utils/functions.py

@@ -319,3 +319,26 @@ def resource_path(*,
     new_url = base._replace(path='/'.join(path), query=query).geturl()
 
     return format_escaped_url(new_url, *action, **kwargs, uid=uid)
+
+
+def _data_manager_deprecation_checks(session, project_id: UUID, team_id: UUID, obj_type: str):
+    if project_id is None and team_id is None:
+        raise TypeError("Missing one required argument: team_id.")
+    elif project_id is not None:
+        warn(
+            f"{obj_type} now belong to Teams. Access through projects has been deprecated since "
+            "v3.4.0, and will be removed in v4.0. Please go through your Team or Dataset.",
+            DeprecationWarning)
+        if team_id is None:
+            # avoiding a circular import
+            from citrine.resources.project import Project
+            team_id = Project.get_team_id_from_project_id(session=session, project_id=project_id)
+    return team_id
+
+
+def _pad_positional_args(args, n):
+    if len(args) > 0:
+        warn("Positional arguments are deprecated and will be removed in v4.0. Please use keyword "
+             "arguments instead.",
+             DeprecationWarning)
+    return args + (None, ) * (n - len(args))

src/citrine/jobs/job.py

@@ -1,6 +1,6 @@
 from logging import getLogger
 from time import time, sleep
-from typing import Union
+from typing import Union, Optional
 from uuid import UUID
 
 from citrine._serialization.properties import Set as PropertySet, String, Object
@@ -59,9 +59,10 @@ class JobStatusResponse(Resource['JobStatusResponse']):
 
 
 def _poll_for_job_completion(session: Session,
-                             project_id: Union[UUID, str],
                              job: Union[JobSubmissionResponse, UUID, str],
                              *,
+                             team_id: Optional[Union[UUID, str]] = None,
+                             project_id: Optional[Union[UUID, str]] = None,
                              timeout: float = 2 * 60,
                              polling_delay: float = 2.0,
                              raise_errors: bool = True,
@@ -96,7 +97,12 @@ def _poll_for_job_completion(session: Session,
         job_id = job.job_id
     else:
         job_id = job  # pragma: no cover
-    path = format_escaped_url('projects/{}/execution/job-status', project_id)
+    if project_id is None and team_id is None:
+        raise TypeError('Either a project_id or team_id must be provided to poll a job.')
+    if team_id is not None:
+        path = format_escaped_url('teams/{}/execution/job-status', team_id)
+    else:
+        path = format_escaped_url('projects/{}/execution/job-status', project_id)
     params = {'job_id': job_id}
     start_time = time()
     while True:

src/citrine/resources/condition_template.py

@@ -58,8 +58,6 @@ def __str__(self):
 class ConditionTemplateCollection(AttributeTemplateCollection[ConditionTemplate]):
     """A collection of condition templates."""
 
-    _path_template = 'projects/{project_id}/datasets/{dataset_id}/condition-templates'
-    _dataset_agnostic_path_template = 'projects/{project_id}/condition-templates'
     _individual_key = 'condition_template'
     _collection_key = 'condition_templates'
     _resource = ConditionTemplate

src/citrine/resources/data_concepts.py

@@ -1,6 +1,6 @@
 """Top-level class for all data concepts objects and collections thereof."""
-from abc import abstractmethod, ABC
 import re
+from abc import abstractmethod, ABC
 from typing import TypeVar, Type, List, Union, Optional, Iterator, Iterable
 from uuid import UUID, uuid4
 
@@ -18,8 +18,8 @@
 from citrine._serialization.properties import UUID as PropertyUUID
 from citrine._serialization.serializable import Serializable
 from citrine._session import Session
-from citrine._utils.functions import scrub_none, replace_objects_with_links, \
-    format_escaped_url
+from citrine._utils.functions import _data_manager_deprecation_checks, format_escaped_url, \
+    _pad_positional_args, replace_objects_with_links, scrub_none
 from citrine.exceptions import BadRequest
 from citrine.resources.audit_info import AuditInfo
 from citrine.jobs.job import _poll_for_job_completion
@@ -202,28 +202,56 @@ class DataConceptsCollection(Collection[ResourceType], ABC):
 
     Parameters
     ----------
-    project_id: UUID
-        The uid of the project that this collection belongs to.
+    team_id: UUID
+        The uid of the team that this collection belongs to.
     dataset_id: UUID
         The uid of the dataset that this collection belongs to. If None then the collection
-        ranges over all datasets in the project. Note that this is only allowed for certain
+        ranges over all datasets in the team. Note that this is only allowed for certain
         actions. For example, you can use :func:`list_by_tag` to search over all datasets,
         but when using :func:`register` to upload or update an object, a dataset must be specified.
     session: Session
         The Citrine session used to connect to the database.
 
     """
 
-    def __init__(self, project_id: UUID, dataset_id: UUID, session: Session):
-        self.project_id = project_id
-        self.dataset_id = dataset_id
-        self.session = session
+    def __init__(self,
+                 *args,
+                 session: Session = None,
+                 dataset_id: Optional[UUID] = None,
+                 team_id: Optional[UUID] = None,
+                 project_id: Optional[UUID] = None):
+        # Handle positional arguments for backward compatibility
+        args = _pad_positional_args(args, 3)
+        self.project_id = project_id or args[0]
+        self.dataset_id = dataset_id or args[1]
+        self.session = session or args[2]
+        if self.session is None:
+            raise TypeError("Missing one required argument: session.")
+
+        self.team_id = _data_manager_deprecation_checks(
+            session=self.session,
+            project_id=self.project_id,
+            team_id=team_id,
+            obj_type="GEMD Objects")
 
     @classmethod
     @abstractmethod
     def get_type(cls) -> Type[Serializable]:
         """Return the resource type in the collection."""
 
+    @property
+    def _path_template(self):
+        collection_key = self._collection_key.replace("_", "-")
+        return f'teams/{self.team_id}/datasets/{self.dataset_id}/{collection_key}'
+
+    # After Data Manager deprecation, both can use the `teams/...` path.
+    @property
+    def _dataset_agnostic_path_template(self):
+        if self.project_id is None:
+            return f'teams/{self.team_id}/{self._collection_key.replace("_","-")}'
+        else:
+            return f'projects/{self.project_id}/{self._collection_key.replace("_","-")}'
+
     def build(self, data: dict) -> ResourceType:
         """
         Build an object of type ResourceType from a serialized dictionary.
@@ -390,7 +418,9 @@ def register_all(self,
 
         """
         from citrine.resources.gemd_resource import GEMDResourceCollection
-        gemd_collection = GEMDResourceCollection(self.project_id, self.dataset_id, self.session)
+        gemd_collection = GEMDResourceCollection(team_id=self.team_id,
+                                                 dataset_id=self.dataset_id,
+                                                 session=self.session)
         return gemd_collection.register_all(
             models,
             dry_run=dry_run,
@@ -482,7 +512,7 @@ def async_update(self, model: ResourceType, *,
         job_id = response_json["job_id"]
 
         if wait_for_response:
-            self.poll_async_update_job(job_id, timeout=timeout,
+            self.poll_async_update_job(job_id=job_id, timeout=timeout,
                                        polling_delay=polling_delay)
 
             # That worked, return nothing or return the object
@@ -525,8 +555,12 @@ def poll_async_update_job(self, job_id: UUID, *, timeout: float = 2 * 60,
 
         """
         # Poll for job completion - this will raise an error if the job failed
-        _poll_for_job_completion(self.session, self.project_id, job_id, timeout=timeout,
-                                 polling_delay=polling_delay)
+        _poll_for_job_completion(
+            session=self.session,
+            team_id=self.team_id,
+            project_id=self.project_id,
+            job=job_id, timeout=timeout,
+            polling_delay=polling_delay)
 
         # That worked, nothing returned in this case
         return None
@@ -675,8 +709,8 @@ def _get_relation(self, relation: str, uid: Union[UUID, str, LinkByUID, BaseEnti
         link = _make_link_by_uid(uid)
         raw_objects = self.session.cursor_paged_resource(
             self.session.get_resource,
-            format_escaped_url('projects/{}/{}/{}/{}/{}',
-                               self.project_id,
+            format_escaped_url('teams/{}/{}/{}/{}/{}',
+                               self.team_id,
                                relation,
                                link.scope,
                                link.id,