refactor: enhance content retrieval methods and add matching utilities

mconflitti-pbc · mconflitti-pbc · commit 7330ff8268cc · 2025-07-21T11:52:47.000-04:00
diff --git a/src/posit/connect/content.py b/src/posit/connect/content.py
@@ -984,33 +984,28 @@ def find_one(self, **conditions) -> Optional[ContentItem]:
         items = self.find(**conditions)
         return next(iter(items), None)
 
-    def get(self, guid: str) -> ContentItem:
+    def get(self, guid: Optional[str] = None) -> ContentItem:
         """Get a content item.
 
+        If `guid` is None, attempts to get the content item for the current context using the
+        CONNECT_CONTENT_GUID environment variable, which is automatically set when running on Connect.
+
         Parameters
         ----------
-        guid : str
+        guid : str, optional
             The unique identifier of the content item.
 
         Returns
         -------
         ContentItem
         """
+        if guid is None:
+            guid = os.getenv("CONNECT_CONTENT_GUID")
+            if not guid:
+                raise RuntimeError("CONNECT_CONTENT_GUID environment variable is not set.")
+
         # Always request all available optional fields for the content item
         params = {"include": "owner,tags,vanity_url"}
 
         response = self._ctx.client.get(f"v1/content/{guid}", params=params)
         return ContentItem(self._ctx, **response.json())
-
-    @property
-    def current(self) -> ContentItem:
-        """Get the content item for the current context.
-
-        Returns
-        -------
-        ContentItem
-        """
-        guid = os.getenv("CONNECT_CONTENT_GUID")
-        if not guid:
-            raise RuntimeError("CONNECT_CONTENT_GUID environment variable is not set.")
-        return self.get(guid)
diff --git a/src/posit/connect/oauth/associations.py b/src/posit/connect/oauth/associations.py
@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-import re
+from functools import partial
 
 from typing_extensions import TYPE_CHECKING, List, Optional
 
 # from ..context import requires
-from ..resources import BaseResource, Resources
+from ..resources import BaseResource, Resources, _matches_exact, _matches_pattern
 
 if TYPE_CHECKING:
     from ..context import Context
@@ -99,33 +99,27 @@ def find_by(
         Association | None
             The first matching association, or None if no match is found.
         """
+        filters = []
+        if integration_type is not None:
+            filters.append(
+                partial(_matches_exact, key="oauth_integration_template", value=integration_type)
+            )
+        if auth_type is not None:
+            filters.append(
+                partial(_matches_exact, key="oauth_integration_auth_type", value=auth_type)
+            )
+        if name is not None:
+            filters.append(partial(_matches_pattern, key="oauth_integration_name", pattern=name))
+        if description is not None:
+            filters.append(
+                partial(_matches_pattern, key="oauth_integration_description", pattern=description)
+            )
+        if guid is not None:
+            filters.append(partial(_matches_exact, key="oauth_integration_guid", value=guid))
+
         for integration in self.find():
-            if (
-                integration_type is not None
-                and integration.get("oauth_integration_template") != integration_type
-            ):
-                continue
-
-            if (
-                auth_type is not None
-                and integration.get("oauth_integration_auth_type") != auth_type
-            ):
-                continue
-
-            if name is not None:
-                integration_name = integration.get("oauth_integration_name", "")
-                if not re.search(name, integration_name):
-                    continue
-
-            if description is not None:
-                integration_description = integration.get("oauth_integration_description", "")
-                if not re.search(description, integration_description):
-                    continue
-
-            if guid is not None and integration.get("oauth_integration_guid") != guid:
-                continue
-
-            return integration
+            if all(f(integration) for f in filters):
+                return integration
 
         return None
 
diff --git a/src/posit/connect/oauth/integrations.py b/src/posit/connect/oauth/integrations.py
@@ -2,11 +2,17 @@
 
 from __future__ import annotations
 
-import re
+from functools import partial
 
 from typing_extensions import TYPE_CHECKING, List, Optional, overload
 
-from ..resources import BaseResource, Resources
+from ..resources import (
+    BaseResource,
+    Resources,
+    _contains_dict_key_values,
+    _matches_exact,
+    _matches_pattern,
+)
 from .associations import IntegrationAssociations
 
 if TYPE_CHECKING:
@@ -161,32 +167,23 @@ def find_by(
         Integration | None
             The first matching integration, or None if no match is found.
         """
-        for integration in self.find():
-            if integration_type is not None and integration.get("template") != integration_type:
-                continue
-
-            if auth_type is not None and integration.get("auth_type") != auth_type:
-                continue
-
-            if name is not None:
-                integration_name = integration.get("name", "")
-                if not re.search(name, integration_name):
-                    continue
-
-            if description is not None:
-                integration_description = integration.get("description", "")
-                if not re.search(description, integration_description):
-                    continue
+        filters = []
+        if integration_type is not None:
+            filters.append(partial(_matches_exact, key="template", value=integration_type))
+        if auth_type is not None:
+            filters.append(partial(_matches_exact, key="auth_type", value=auth_type))
+        if name is not None:
+            filters.append(partial(_matches_pattern, key="name", pattern=name))
+        if description is not None:
+            filters.append(partial(_matches_pattern, key="description", pattern=description))
+        if guid is not None:
+            filters.append(partial(_matches_exact, key="guid", value=guid))
+        if config is not None:
+            filters.append(partial(_contains_dict_key_values, key="config", value=config))
 
-            if guid is not None and integration.get("guid") != guid:
-                continue
-
-            if config is not None:
-                integration_config = integration.get("config", {})
-                if not all(integration_config.get(k) == v for k, v in config.items()):
-                    continue
-
-            return integration
+        for integration in self.find():
+            if all(f(integration) for f in filters):
+                return integration
 
         return None
 
diff --git a/src/posit/connect/oauth/oauth.py b/src/posit/connect/oauth/oauth.py
@@ -56,17 +56,31 @@ def sessions(self):
 
     def get_credentials(
         self,
-        user_session_token: Optional[str] = None,
+        user_session_token: str,
         requested_token_type: Optional[str | types.OAuthTokenType] = None,
         audience: Optional[str] = None,
     ) -> Credentials:
-        """Perform an oauth credential exchange with a user-session-token."""
+        """Perform an oauth credential exchange with a user-session-token.
+
+        Parameters
+        ----------
+        user_session_token : str
+            The user session token to use for the exchange.
+        requested_token_type : str or OAuthTokenType, optional
+            The type of token being requested. This can be one of the predefined types in `OAuthTokenType` or a custom string.
+        audience : str, optional
+            The intended audience for the token. This must be a valid integration GUID.
+
+        Returns
+        -------
+        Credentials
+            The credentials obtained from the exchange.
+        """
         # craft a credential exchange request
         data = {}
         data["grant_type"] = types.GRANT_TYPE
         data["subject_token_type"] = types.OAuthTokenType.USER_SESSION_TOKEN
-        if user_session_token:
-            data["subject_token"] = user_session_token
+        data["subject_token"] = user_session_token
         if requested_token_type:
             data["requested_token_type"] = requested_token_type
         if audience:
@@ -81,7 +95,23 @@ def get_content_credentials(
         requested_token_type: Optional[str | types.OAuthTokenType] = None,
         audience: Optional[str] = None,
     ) -> Credentials:
-        """Perform an oauth credential exchange with a content-session-token."""
+        """Perform an oauth credential exchange with a content-session-token.
+
+        Parameters
+        ----------
+        content_session_token : str, optional
+            The content session token to use for the exchange. If not provided, the function will attempt to read the token from the environment variable 'CONNECT_CONTENT_SESSION_TOKEN'.
+        requested_token_type : str or OAuthTokenType, optional
+            The type of token being requested. This can be one of the predefined types in `OAuthTokenType` or a custom string.
+        audience : str, optional
+            The intended audience for the token. This must be a valid integration GUID.
+
+        Returns
+        -------
+        Credentials
+            The credentials obtained from the exchange.
+
+        """
         # craft a credential exchange request
         data = {}
         data["grant_type"] = types.GRANT_TYPE
diff --git a/src/posit/connect/resources.py b/src/posit/connect/resources.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import posixpath
+import re
 import warnings
 from abc import ABC
 
@@ -192,3 +193,24 @@ def fetch(self, **conditions):
                 resource = _Resource(self._ctx, path, **result)
                 resources.append(resource)
             yield from resources
+
+
+def _matches_exact(item: BaseResource, key: str, value: str):
+    item_value = item.get(key)
+    if item_value is None or not isinstance(item_value, str):
+        return False
+    return item_value == value
+
+
+def _matches_pattern(item: BaseResource, key: str, pattern: str):
+    item_value = item.get(key)
+    if item_value is None or not isinstance(item_value, str):
+        return False
+    return re.search(pattern, item_value) is not None
+
+
+def _contains_dict_key_values(item: BaseResource, key: str, value: dict):
+    item_value = item.get(key)
+    if item_value is None or not isinstance(item_value, dict):
+        return False
+    return all(item_value.get(k) == v for k, v in value.items())
diff --git a/tests/posit/connect/test_content.py b/tests/posit/connect/test_content.py
@@ -388,7 +388,7 @@ def test_with_env_var(self, monkeypatch):
             match=[matchers.query_param_matcher({"include": "owner,tags,vanity_url"})],
         )
         c = Client("https://connect.example", "12345")
-        content_item = c.content.current
+        content_item = c.content.get()
         assert content_item["guid"] == guid
 
     def test_without_env_var(self, monkeypatch):
@@ -397,7 +397,7 @@ def test_without_env_var(self, monkeypatch):
         with pytest.raises(
             RuntimeError, match="CONNECT_CONTENT_GUID environment variable is not set."
         ):
-            _ = c.content.current
+            _ = c.content.get()
 
 
 class TestContentsCount:
diff --git a/tests/posit/connect/test_resources.py b/tests/posit/connect/test_resources.py
@@ -4,7 +4,12 @@
 
 from typing_extensions import Optional
 
-from posit.connect.resources import BaseResource
+from posit.connect.resources import (
+    BaseResource,
+    _contains_dict_key_values,
+    _matches_exact,
+    _matches_pattern,
+)
 
 config = Mock()
 session = Mock()
@@ -62,3 +67,74 @@ def test_foo(self):
         d = {k: v}
         r = FakeResource(mock.Mock(), **d)
         assert r.foo == v
+
+
+class TestContainsDictKeyValues:
+    def test_empty_value_dict(self):
+        r = FakeResource(mock.Mock(), foo={"a": 1, "b": 2})
+        assert _contains_dict_key_values(r, "foo", {}) is True
+
+    def test_matching_single_key_value(self):
+        r = FakeResource(mock.Mock(), foo={"a": 1, "b": 2})
+        assert _contains_dict_key_values(r, "foo", {"a": 1}) is True
+
+    def test_matching_multiple_key_values(self):
+        r = FakeResource(mock.Mock(), foo={"a": 1, "b": 2, "c": 3})
+        assert _contains_dict_key_values(r, "foo", {"a": 1, "b": 2}) is True
+
+    def test_non_matching_key_value(self):
+        r = FakeResource(mock.Mock(), foo={"a": 1, "b": 2})
+        assert _contains_dict_key_values(r, "foo", {"a": 2}) is False
+
+    def test_missing_key_in_item(self):
+        r = FakeResource(mock.Mock(), foo={"a": 1})
+        assert _contains_dict_key_values(r, "foo", {"b": 2}) is False
+
+    def test_missing_field_in_resource(self):
+        r = FakeResource(mock.Mock())
+        assert _contains_dict_key_values(r, "nonexistent", {"a": 1}) is False
+
+    def test_non_dict_field_value(self):
+        r = FakeResource(mock.Mock(), foo="not_a_dict")
+        assert _contains_dict_key_values(r, "foo", {"a": 1}) is False
+
+    def test_nested_dict_values(self):
+        r = FakeResource(mock.Mock(), foo={"nested": {"x": 10}, "simple": "value"})
+        assert _contains_dict_key_values(r, "foo", {"nested": {"x": 10}}) is True
+        assert _contains_dict_key_values(r, "foo", {"nested": {"x": 20}}) is False
+
+
+class TestMatchesPattern:
+    def test_pattern_matches(self):
+        r = FakeResource(mock.Mock(), name="test-app-123")
+        assert _matches_pattern(r, "name", r"test-.*-\d+") is True
+
+    def test_pattern_does_not_match(self):
+        r = FakeResource(mock.Mock(), name="production-app")
+        assert _matches_pattern(r, "name", r"test-.*-\d+") is False
+
+    def test_missing_field_returns_false(self):
+        r = FakeResource(mock.Mock())
+        assert _matches_pattern(r, "nonexistent", ".*") is False
+
+    def test_empty_pattern_matches_any_string(self):
+        r = FakeResource(mock.Mock(), description="any text here")
+        assert _matches_pattern(r, "description", "") is True
+
+    def test_partial_match_returns_true(self):
+        r = FakeResource(mock.Mock(), title="My Great App")
+        assert _matches_pattern(r, "title", "Great") is True
+
+
+class TestMatchesExact:
+    def test_exact_match_returns_true(self):
+        r = FakeResource(mock.Mock(), name="test-app")
+        assert _matches_exact(r, "name", "test-app") is True
+
+    def test_no_match_returns_false(self):
+        r = FakeResource(mock.Mock(), name="test-app")
+        assert _matches_exact(r, "name", "other-app") is False
+
+    def test_missing_field_returns_false(self):
+        r = FakeResource(mock.Mock())
+        assert _matches_exact(r, "nonexistent", "value") is False
