Deprecate PEWs.

Attach a deprecation warning to the PEW and PEW Execution collections
and their associated operations. The associated response objects
(PredictorEvaluationWorkflow and PredictorEvaluationExecution) are also
deprecated, but as they're only produced by the collections, their
docstring notes their deprecation rather than an emitted message, to
avoid inundating the user.

Author: anoto-moniz

src/citrine/informatics/executions/predictor_evaluation_execution.py

@@ -8,7 +8,7 @@
 
 
 class PredictorEvaluationExecution(Resource['PredictorEvaluationExecution'], Execution):
-    """The execution of a PredictorEvaluationWorkflow.
+    """[DEPRECATED] The execution of a PredictorEvaluationWorkflow.
 
     Possible statuses are INPROGRESS, SUCCEEDED, and FAILED.
     Predictor evaluation executions also have a ``status_description`` field with more information.

src/citrine/informatics/workflows/predictor_evaluation_workflow.py

@@ -12,7 +12,7 @@
 
 class PredictorEvaluationWorkflow(Resource['PredictorEvaluationWorkflow'],
                                   Workflow, AIResourceMetadata):
-    """A workflow that evaluations a predictor.
+    """[DEPRECATED] A workflow that evaluates a predictor.
 
     Parameters
     ----------

src/citrine/resources/predictor_evaluation_execution.py

@@ -1,4 +1,5 @@
 """Resources that represent both individual and collections of predictor evaluation executions."""
+from deprecation import deprecated
 from functools import partial
 from typing import Optional, Union, Iterator
 from uuid import UUID
@@ -19,6 +20,9 @@ class PredictorEvaluationExecutionCollection(Collection["PredictorEvaluationExec
     _collection_key = 'response'
     _resource = predictor_evaluation_execution.PredictorEvaluationExecution
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Predictor evaluation workflows are being eliminated in favor of directly"
+                        "evaluating predictors. Please use Project.predictor_evaluations instead.")
     def __init__(self,
                  project_id: UUID,
                  session: Session,
@@ -34,6 +38,8 @@ def build(self, data: dict) -> predictor_evaluation_execution.PredictorEvaluatio
         execution.project_id = self.project_id
         return execution
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluationCollection.trigger instead.")
     def trigger(self,
                 predictor_id: UUID,
                 *,
@@ -71,18 +77,22 @@ def trigger(self,
 
         return self.build(data)
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0")
     def register(self,
                  model: predictor_evaluation_execution.PredictorEvaluationExecution
                  ) -> predictor_evaluation_execution.PredictorEvaluationExecution:
         """Cannot register an execution."""
         raise NotImplementedError("Cannot register a PredictorEvaluationExecution.")
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0")
     def update(self,
                model: predictor_evaluation_execution.PredictorEvaluationExecution
                ) -> predictor_evaluation_execution.PredictorEvaluationExecution:
         """Cannot update an execution."""
         raise NotImplementedError("Cannot update a PredictorEvaluationExecution.")
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluation.archive")
     def archive(self, uid: Union[UUID, str]):
         """Archive a predictor evaluation execution.
 
@@ -94,6 +104,8 @@ def archive(self, uid: Union[UUID, str]):
         """
         self._put_resource_ref('archive', uid)
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluation.restore")
     def restore(self, uid: Union[UUID, str]):
         """Restore an archived predictor evaluation execution.
 
@@ -105,6 +117,8 @@ def restore(self, uid: Union[UUID, str]):
         """
         self._put_resource_ref('restore', uid)
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluation.list")
     def list(self,
              *,
              per_page: int = 100,
@@ -144,7 +158,15 @@ def list(self,
                                         collection_builder=self._build_collection_elements,
                                         per_page=per_page)
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0")
     def delete(self, uid: Union[UUID, str]) -> Response:
         """Predictor Evaluation Executions cannot be deleted; they can be archived instead."""
         raise NotImplementedError(
             "Predictor Evaluation Executions cannot be deleted; they can be archived instead.")
+
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluation.get")
+    def get(self,
+            uid: Union[UUID, str]) -> predictor_evaluation_execution.PredictorEvaluationExecution:
+        """Get a particular element of the collection."""
+        return super().get(uid)

src/citrine/resources/predictor_evaluation_workflow.py

@@ -1,5 +1,6 @@
 """Resources that represent both individual and collections of workflow executions."""
-from typing import Optional, Union
+from deprecation import deprecated
+from typing import Iterator, Optional, Union
 from uuid import UUID
 
 from citrine._rest.collection import Collection
@@ -16,6 +17,9 @@ class PredictorEvaluationWorkflowCollection(Collection[PredictorEvaluationWorkfl
     _collection_key = 'response'
     _resource = PredictorEvaluationWorkflow
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Predictor evaluation workflows are being eliminated in favor of directly"
+                        "evaluating predictors. Please use Project.predictor_evaluations instead.")
     def __init__(self, project_id: UUID, session: Session):
         self.project_id: UUID = project_id
         self.session: Session = session
@@ -27,6 +31,8 @@ def build(self, data: dict) -> PredictorEvaluationWorkflow:
         workflow.project_id = self.project_id
         return workflow
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluations instead, which doesn't store workflows.")
     def archive(self, uid: Union[UUID, str]):
         """Archive a predictor evaluation workflow.
 
@@ -38,6 +44,8 @@ def archive(self, uid: Union[UUID, str]):
         """
         return self._put_resource_ref('archive', uid)
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluations instead, which doesn't store workflows.")
     def restore(self, uid: Union[UUID, str] = None):
         """Restore an archived predictor evaluation workflow.
 
@@ -49,11 +57,15 @@ def restore(self, uid: Union[UUID, str] = None):
         """
         return self._put_resource_ref('restore', uid)
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0")
     def delete(self, uid: Union[UUID, str]) -> Response:
         """Predictor Evaluation Workflows cannot be deleted; they can be archived instead."""
         raise NotImplementedError(
             "Predictor Evaluation Workflows cannot be deleted; they can be archived instead.")
 
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluations.trigger_default instead. It doesn't store"
+                        " a workflow, but it triggers an evaluation with the default evaluators.")
     def create_default(self,
                        *,
                        predictor_id: UUID,
@@ -95,3 +107,27 @@ def create_default(self,
             payload['predictor_version'] = predictor_version
         data = self.session.post_resource(url, payload)
         return self.build(data)
+
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluations instead, which doesn't store workflows.")
+    def register(self, model: PredictorEvaluationWorkflow) -> PredictorEvaluationWorkflow:
+        """Create a new element of the collection by registering an existing resource."""
+        return super().register(model)
+
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluations instead, which doesn't store workflows.")
+    def list(self, *, per_page: int = 100) -> Iterator[PredictorEvaluationWorkflow]:
+        """Paginate over the elements of the collection."""
+        return super().list(per_page=per_page)
+
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluations instead, which doesn't store workflows.")
+    def update(self, model: PredictorEvaluationWorkflow) -> PredictorEvaluationWorkflow:
+        """Update a particular element of the collection."""
+        return super().update(model)
+
+    @deprecated(deprecated_in="3.23.0", removed_in="4.0.0",
+                details="Please use PredictorEvaluations instead, which doesn't store workflows.")
+    def get(self, uid: Union[UUID, str]) -> PredictorEvaluationWorkflow:
+        """Get a particular element of the collection."""
+        return super().get(uid)

tests/informatics/workflows/test_predictor_evaluation_workflow.py

@@ -36,4 +36,5 @@ def test_execution_error(pew):
         pew.executions
 
     pew.project_id = "foo"
-    assert pew.executions.project_id == "foo"
+    with pytest.deprecated_call():
+        assert pew.executions.project_id == "foo"

tests/resources/test_predictor_evaluation_executions.py

@@ -17,11 +17,12 @@ def session() -> FakeSession:
 
 @pytest.fixture
 def collection(session) -> PredictorEvaluationExecutionCollection:
-    return PredictorEvaluationExecutionCollection(
-        project_id=uuid.uuid4(),
-        workflow_id=uuid.uuid4(),
-        session=session,
-    )
+    with pytest.deprecated_call():
+        return PredictorEvaluationExecutionCollection(
+            project_id=uuid.uuid4(),
+            workflow_id=uuid.uuid4(),
+            session=session,
+        )
 
 
 @pytest.fixture
@@ -37,11 +38,13 @@ def test_basic_methods(workflow_execution, collection):
 
     assert "Example evaluator" in list(iter(workflow_execution))
 
-    with pytest.raises(NotImplementedError):
-        collection.register(workflow_execution)
+    with pytest.deprecated_call():
+        with pytest.raises(NotImplementedError):
+            collection.register(workflow_execution)
 
-    with pytest.raises(NotImplementedError):
-        collection.update(workflow_execution)
+    with pytest.deprecated_call():
+        with pytest.raises(NotImplementedError):
+            collection.update(workflow_execution)
 
 
 def test_build_new_execution(collection, predictor_evaluation_execution_dict):
@@ -87,7 +90,8 @@ def test_trigger_workflow_execution(collection: PredictorEvaluationExecutionColl
     session.set_response(predictor_evaluation_execution_dict)
 
     # When
-    actual_execution = collection.trigger(predictor_id, random_state=random_state)
+    with pytest.deprecated_call():
+        actual_execution = collection.trigger(predictor_id, random_state=random_state)
 
     # Then
     assert str(actual_execution.uid) == predictor_evaluation_execution_dict["id"]
@@ -110,7 +114,8 @@ def test_trigger_workflow_execution_with_version(collection: PredictorEvaluation
     session.set_response(predictor_evaluation_execution_dict)
 
     # When
-    actual_execution = collection.trigger(predictor_id, predictor_version=predictor_version)
+    with pytest.deprecated_call():
+        actual_execution = collection.trigger(predictor_id, predictor_version=predictor_version)
 
     # Then
     assert str(actual_execution.uid) == predictor_evaluation_execution_dict["id"]
@@ -129,7 +134,8 @@ def test_trigger_workflow_execution_with_version(collection: PredictorEvaluation
 def test_list(collection: PredictorEvaluationExecutionCollection, session, predictor_version):
     session.set_response({"page": 1, "per_page": 4, "next": "", "response": []})
     predictor_id = uuid.uuid4()
-    lst = list(collection.list(per_page=4, predictor_id=predictor_id, predictor_version=predictor_version))
+    with pytest.deprecated_call():
+        lst = list(collection.list(per_page=4, predictor_id=predictor_id, predictor_version=predictor_version))
     assert not lst
 
     expected_path = '/projects/{}/predictor-evaluation-executions'.format(collection.project_id)
@@ -140,17 +146,29 @@ def test_list(collection: PredictorEvaluationExecutionCollection, session, predi
 
 
 def test_archive(workflow_execution, collection):
-    collection.archive(workflow_execution.uid)
+    with pytest.deprecated_call():
+        collection.archive(workflow_execution.uid)
     expected_path = '/projects/{}/predictor-evaluation-executions/archive'.format(collection.project_id)
     assert collection.session.last_call == FakeCall(method='PUT', path=expected_path, json={"module_uid": str(workflow_execution.uid)})
 
 
 def test_restore(workflow_execution, collection):
-    collection.restore(workflow_execution.uid)
+    with pytest.deprecated_call():
+        collection.restore(workflow_execution.uid)
     expected_path = '/projects/{}/predictor-evaluation-executions/restore'.format(collection.project_id)
     assert collection.session.last_call == FakeCall(method='PUT', path=expected_path, json={"module_uid": str(workflow_execution.uid)})
 
 
 def test_delete(collection):
-    with pytest.raises(NotImplementedError):
-        collection.delete(uuid.uuid4())
+    with pytest.deprecated_call():
+        with pytest.raises(NotImplementedError):
+            collection.delete(uuid.uuid4())
+
+def test_get(predictor_evaluation_execution_dict, workflow_execution, collection):
+    collection.session.set_response(predictor_evaluation_execution_dict)
+    
+    with pytest.deprecated_call():
+        execution = collection.get(workflow_execution.uid)
+    
+    expected_path = f'/projects/{collection.project_id}/predictor-evaluation-executions/{workflow_execution.uid}'
+    assert collection.session.last_call == FakeCall(method='GET', path=expected_path)

tests/resources/test_predictor_evaluation_workflows.py

@@ -15,10 +15,11 @@ def session() -> FakeSession:
 
 @pytest.fixture
 def collection(session) -> PredictorEvaluationWorkflowCollection:
-    return PredictorEvaluationWorkflowCollection(
-        project_id=uuid.uuid4(),
-        session=session,
-    )
+    with pytest.deprecated_call():
+        return PredictorEvaluationWorkflowCollection(
+            project_id=uuid.uuid4(),
+            session=session,
+        )
 
 
 @pytest.fixture
@@ -33,22 +34,25 @@ def test_basic_methods(workflow, collection):
 
 
 def test_archive(workflow, collection):
-    collection.archive(workflow.uid)
+    with pytest.deprecated_call():
+        collection.archive(workflow.uid)
     expected_path = '/projects/{}/predictor-evaluation-workflows/archive'.format(collection.project_id)
     assert collection.session.last_call == FakeCall(method='PUT', path=expected_path,
                                                     json={"module_uid": str(workflow.uid)})
 
 
 def test_restore(workflow, collection):
-    collection.restore(workflow.uid)
+    with pytest.deprecated_call():
+        collection.restore(workflow.uid)
     expected_path = '/projects/{}/predictor-evaluation-workflows/restore'.format(collection.project_id)
     assert collection.session.last_call == FakeCall(method='PUT', path=expected_path,
                                                     json={"module_uid": str(workflow.uid)})
 
 
 def test_delete(collection):
-    with pytest.raises(NotImplementedError):
-        collection.delete(uuid.uuid4())
+    with pytest.deprecated_call():
+        with pytest.raises(NotImplementedError):
+            collection.delete(uuid.uuid4())
 
 
 @pytest.mark.parametrize("predictor_version", (2, "1", "latest", None))
@@ -60,11 +64,13 @@ def test_create_default(predictor_evaluation_workflow_dict: dict,
 
     session = FakeSession()
     session.set_response(predictor_evaluation_workflow_dict)
-    collection = PredictorEvaluationWorkflowCollection(
-        project_id=project_id,
-        session=session
-    )
-    default_workflow = collection.create_default(predictor_id=predictor_id, predictor_version=predictor_version)
+    with pytest.deprecated_call():
+        collection = PredictorEvaluationWorkflowCollection(
+            project_id=project_id,
+            session=session
+        )
+    with pytest.deprecated_call():
+        default_workflow = collection.create_default(predictor_id=predictor_id, predictor_version=predictor_version)
 
     url = f'/projects/{collection.project_id}/predictor-evaluation-workflows/default'
 
@@ -73,3 +79,39 @@ def test_create_default(predictor_evaluation_workflow_dict: dict,
         expected_payload["predictor_version"] = predictor_version
     assert session.calls == [FakeCall(method="POST", path=url, json=expected_payload)]
     assert default_workflow.dump() == workflow.dump()
+    
+def test_register(predictor_evaluation_workflow_dict, workflow, collection):
+    collection.session.set_response(predictor_evaluation_workflow_dict)
+    
+    with pytest.deprecated_call():
+        collection.register(workflow)
+
+    expected_path = f'/projects/{collection.project_id}/predictor-evaluation-workflows'
+    assert collection.session.last_call == FakeCall(method='POST', path=expected_path, json=workflow.dump())
+    
+def test_list(predictor_evaluation_workflow_dict, workflow, collection):
+    collection.session.set_response({"page": 1, "per_page": 4, "next": "", "response": [predictor_evaluation_workflow_dict]})
+    
+    with pytest.deprecated_call():
+        list(collection.list(per_page=20))
+
+    expected_path = f'/projects/{collection.project_id}/predictor-evaluation-workflows'
+    assert collection.session.last_call == FakeCall(method='GET', path=expected_path, params={"per_page": 20, "page": 1})
+
+def test_update(predictor_evaluation_workflow_dict, workflow, collection):
+    collection.session.set_response(predictor_evaluation_workflow_dict)
+    
+    with pytest.deprecated_call():
+        collection.update(workflow)
+
+    expected_path = f'/projects/{collection.project_id}/predictor-evaluation-workflows/{workflow.uid}'
+    assert collection.session.last_call == FakeCall(method='PUT', path=expected_path, json=workflow.dump())
+
+def test_get(predictor_evaluation_workflow_dict, workflow, collection):
+    collection.session.set_response(predictor_evaluation_workflow_dict)
+    
+    with pytest.deprecated_call():
+        collection.get(workflow.uid)
+
+    expected_path = f'/projects/{collection.project_id}/predictor-evaluation-workflows/{workflow.uid}'
+    assert collection.session.last_call == FakeCall(method='GET', path=expected_path)