Merge pull request #347 from ianbakst/master

Added project lookup by_name() method, as well as appropriate tests.

CHANGELOG.md

@@ -32,7 +32,7 @@
       - `tc.URL` type
     - `tc.response` module
       - functions: `successful`, `ndjson`
-
+  - [#35](https://github.com/Datatamer/tamr-client/issues/35) projects.by_name() functionality added. Can now fetch a project by its name.
   **BUG FIXES**
   - Links from our docs to the `requests` docs were outdated. Links have been updated to point to the new `requests` docs URL.
   - [#323](https://github.com/Datatamer/tamr-client/issues/323) Documentation for setting `dtype=str` before calling `client.datasets.create_from_dataframe`

docs/user-guide/quickstart.md

@@ -51,6 +51,15 @@ E.g. To fetch the project with ID `'1'`:
 ```python
 project = tamr.projects.by_resource_id('1')
 ```
+Similarly, if you know the name of a specific resource, you can ask for it directly via the `by_name` methods exposed by collections.
+
+E.g. To fetch the project with name `'Number 1'`:
+```python
+project = tamr.projects.by_name('Number 1')
+```
+``` note::
+    If working with projects across Tamr instances for migrations or promotions, use external IDs (via ``by_external_id``) instead of name (via ``by_name``).
+```
 
 ## Resource relationships
 Related resources (like a project and its unified dataset) can be accessed through specific methods.

tamr_unify_client/project/collection.py

@@ -62,6 +62,21 @@ def stream(self):
         """
         return super().stream(Project)
 
+    def by_name(self, project_name: str) -> Project:
+        """Get project by name
+
+        Fetches a specific project in this collection by exact-match on name.
+
+        Args:
+            project_name: Name of the desired project.
+        Raises:
+            KeyError: If no project with specified name was found.
+        """
+        for project in self:
+            if project.name == project_name:
+                return project
+        raise KeyError(f"No project found with name: {project_name}")
+
     def create(self, creation_spec):
         """
         Create a Project in Tamr

tests/unit/test_project.py

@@ -66,6 +66,22 @@ def test_project_by_external_id_succeeds(self):
         actual_project = self.tamr.projects.by_external_id(self.project_external_id)
         self.assertEqual(self.project_json[0], actual_project._data)
 
+    @responses.activate
+    def test_project_by_name__raises_when_not_found(self):
+        responses.add(responses.GET, self.project_list_url, json=[])
+        auth = UsernamePasswordAuth("username", "password")
+        tamr = Client(auth)
+        with self.assertRaises(KeyError):
+            tamr.projects.by_name(self.project_name)
+
+    @responses.activate
+    def test_project_by_name(self):
+        responses.add(responses.GET, self.project_list_url, json=self.project_json)
+        auth = UsernamePasswordAuth("username", "password")
+        tamr = Client(auth)
+        actual_project = tamr.projects.by_name(self.project_name)
+        assert actual_project._data == self.project_json[0]
+
     @responses.activate
     def test_project_attributes_get(self):
         responses.add(responses.GET, self.projects_url, json=self.project_json)
@@ -216,8 +232,10 @@ def create_callback(request, snoop):
             "relativeId": "projects/1",
         }
     ]
+    project_name = "project 1 name"
     project_external_id = "project 1 external ID"
     projects_url = f"http://localhost:9100/api/versioned/v1/projects?filter=externalId=={project_external_id}"
+    project_list_url = "http://localhost:9100/api/versioned/v1/projects"
     post_input_datasets_json = []
     input_datasets_url = (
         f"http://localhost:9100/api/versioned/v1/projects/1/inputDatasets"