feat: add factory support to resource sequences

Author: tdstein

src/posit/connect/content.py

@@ -19,8 +19,6 @@
     overload,
 )
 
-from posit.connect.jobs import _Jobs, Job
-
 from . import tasks
 from ._api import ApiDictEndpoint, JsonifiableDict
 from .bundles import Bundles
@@ -516,7 +514,7 @@ def tags(self) -> ContentItemTags:
     @property
     def jobs(self) -> Jobs:
         path = posixpath.join(self._path, "jobs")
-        return _Jobs(self._ctx, path, uid="key")
+        return _ResourceSequence(self._ctx, path, uid="key")
 
     @property
     @requires(version="2024.11.0")

src/posit/connect/jobs.py

@@ -1,15 +1,13 @@
 from __future__ import annotations
 
-from typing import Any, List
-
 from typing_extensions import (
     Iterable,
     Literal,
     Protocol,
     runtime_checkable,
 )
 
-from .resources import Resource, ResourceSequence, _Resource, _ResourceSequence
+from .resources import Resource, ResourceSequence
 
 JobTag = Literal[
     "unknown",
@@ -56,11 +54,6 @@ def destroy(self) -> None:
         """
 
 
-class _Job(_Resource):
-    def wait_for(self) -> None:
-        pass
-
-
 @runtime_checkable
 class Jobs(ResourceSequence[Job], Protocol):
     def fetch(self) -> Iterable[Job]:
@@ -173,9 +166,3 @@ def find_by(
         This action requires administrator, owner, or collaborator privileges.
         """
         ...
-
-
-class _Jobs(_ResourceSequence[Job]):
-    def fetch(self, **conditions) -> Iterable[Any]:
-        resources = super().fetch(**conditions)
-        return [_Job(**resource) for resource in resources]

src/posit/connect/resources.py

@@ -3,6 +3,7 @@
 import posixpath
 import warnings
 from abc import ABC
+from typing import ItemsView, cast
 
 from typing_extensions import (
     TYPE_CHECKING,
@@ -73,6 +74,8 @@ def __init__(self, ctx: Context, path: str, /, **attributes):
 class Resource(Protocol):
     def __getitem__(self, key: Hashable) -> Any: ...
 
+    def items(self) -> ItemsView: ...
+
 
 class _Resource(dict, Resource):
     def __init__(self, ctx: Context, path: str, **attributes):
@@ -92,6 +95,10 @@ def update(self, **attributes):  # type: ignore[reportIncompatibleMethodOverride
 T = TypeVar("T", bound=Resource)
 
 
+class ResourceFactory(Protocol):
+    def __call__(self, ctx: Context, path: str, **attributes) -> Resource: ...
+
+
 class ResourceSequence(Protocol[T]):
     @overload
     def __getitem__(self, index: SupportsIndex, /) -> T: ...
@@ -109,10 +116,17 @@ def __repr__(self) -> str: ...
 
 
 class _ResourceSequence(Sequence[T], ResourceSequence[T]):
-    def __init__(self, ctx: Context, path: str, *, uid: str = "guid"):
+    def __init__(
+        self,
+        ctx: Context,
+        path: str,
+        factory: ResourceFactory = _Resource,
+        uid: str = "guid",
+    ):
         self._ctx = ctx
         self._path = path
         self._uid = uid
+        self._factory = factory
 
     def __getitem__(self, index):
         return list(self.fetch())[index]
@@ -129,32 +143,32 @@ def __str__(self) -> str:
     def __repr__(self) -> str:
         return repr(self.fetch())
 
-    def create(self, **attributes: Any) -> Any:
+    def create(self, **attributes: Any) -> T:
         response = self._ctx.client.post(self._path, json=attributes)
         result = response.json()
         uid = result[self._uid]
         path = posixpath.join(self._path, uid)
-        return _Resource(self._ctx, path, **result)
+        return cast(T, self._factory(self._ctx, path, **result))
 
-    def fetch(self, **conditions) -> Iterable[Any]:
+    def fetch(self, **conditions) -> Iterable[T]:
         response = self._ctx.client.get(self._path, params=conditions)
         results = response.json()
-        resources = []
+        resources: List[T] = []
         for result in results:
             uid = result[self._uid]
             path = posixpath.join(self._path, uid)
-            resource = _Resource(self._ctx, path, **result)
+            resource = cast(T, self._factory(self._ctx, path, **result))
             resources.append(resource)
 
         return resources
 
-    def find(self, *args: str) -> Any:
+    def find(self, *args: str) -> T:
         path = posixpath.join(self._path, *args)
         response = self._ctx.client.get(path)
         result = response.json()
-        return _Resource(self._ctx, path, **result)
+        return cast(T, self._factory(self._ctx, path, **result))
 
-    def find_by(self, **conditions) -> Any | None:
+    def find_by(self, **conditions) -> T | None:
         """
         Find the first record matching the specified conditions.
 
@@ -169,19 +183,19 @@ def find_by(self, **conditions) -> Any | None:
         Optional[T]
             The first record matching the conditions, or `None` if no match is found.
         """
-        collection = self.fetch(**conditions)
+        collection: Iterable[T] = self.fetch(**conditions)
         return next((v for v in collection if v.items() >= conditions.items()), None)
 
 
-class _PaginatedResourceSequence(_ResourceSequence):
-    def fetch(self, **conditions):
+class _PaginatedResourceSequence(_ResourceSequence[T]):
+    def fetch(self, **conditions) -> Iterator[T]:
         paginator = Paginator(self._ctx, self._path, dict(**conditions))
         for page in paginator.fetch_pages():
             resources = []
             results = page.results
             for result in results:
                 uid = result[self._uid]
                 path = posixpath.join(self._path, uid)
-                resource = _Resource(self._ctx, path, **result)
+                resource = cast(T, self._factory(self._ctx, path, **result))
                 resources.append(resource)
             yield from resources