refactor: add resource protocols (#364)

Adds protocols `Resource` and `ResourceSequence`, which define the base interface for any resource type (e.g., `Job`, `Jobs`, `Package`, `Packages`.)

Co-authored-by: Barret Schloerke <[email protected]>

Author: tdstein

src/posit/connect/bundles.py

@@ -11,11 +11,11 @@
     from .context import Context
 
 
-class BundleMetadata(resources.Resource):
+class BundleMetadata(resources.BaseResource):
     pass
 
 
-class Bundle(resources.Resource):
+class Bundle(resources.BaseResource):
     @property
     def metadata(self) -> BundleMetadata:
         return BundleMetadata(self._ctx, **self.get("metadata", {}))

src/posit/connect/content.py

@@ -24,7 +24,7 @@
 from .errors import ClientError
 from .oauth.associations import ContentItemAssociations
 from .permissions import Permissions
-from .resources import Active, Resource, Resources, _ResourceSequence
+from .resources import Active, BaseResource, Resources, _ResourceSequence
 from .tags import ContentItemTags
 from .vanities import VanityMixin
 from .variants import Variants
@@ -160,7 +160,7 @@ def update(
         )
 
 
-class ContentItemOAuth(Resource):
+class ContentItemOAuth(BaseResource):
     def __init__(self, ctx: Context, content_guid: str) -> None:
         super().__init__(ctx)
         self["content_guid"] = content_guid
@@ -170,11 +170,11 @@ def associations(self) -> ContentItemAssociations:
         return ContentItemAssociations(self._ctx, content_guid=self["content_guid"])
 
 
-class ContentItemOwner(Resource):
+class ContentItemOwner(BaseResource):
     pass
 
 
-class ContentItem(Active, VanityMixin, Resource):
+class ContentItem(Active, VanityMixin, BaseResource):
     class _AttrsBase(TypedDict, total=False):
         # # `name` will be set by other _Attrs classes
         # name: str
@@ -376,7 +376,7 @@ def restart(self) -> None:
                 f"Restart not supported for this application mode: {self['app_mode']}. Did you need to use the 'render()' method instead? Note that some application modes do not support 'render()' or 'restart()'.",
             )
 
-    def update(
+    def update(  # type: ignore[reportIncompatibleMethodOverride]
         self,
         **attrs: Unpack[ContentItem._Attrs],
     ) -> None:

src/posit/connect/environments.py

@@ -1,19 +1,17 @@
 from __future__ import annotations
 
 from abc import abstractmethod
-from collections.abc import Mapping, Sized
+from typing import Protocol
 
 from typing_extensions import (
-    Any,
     List,
     Literal,
-    Protocol,
-    SupportsIndex,
     TypedDict,
-    overload,
     runtime_checkable,
 )
 
+from .resources import Resource, ResourceSequence
+
 MatchingType = Literal["any", "exact", "none"]
 """Directions for how environments are considered for selection.
 
@@ -40,7 +38,7 @@ class Installations(TypedDict):
     """Interpreter installations in an execution environment."""
 
 
-class Environment(Mapping[str, Any]):
+class Environment(Resource):
     @abstractmethod
     def destroy(self) -> None:
         """Destroy the environment.
@@ -95,13 +93,7 @@ def update(
 
 
 @runtime_checkable
-class Environments(Sized, Protocol):
-    @overload
-    def __getitem__(self, index: SupportsIndex) -> Environment: ...
-
-    @overload
-    def __getitem__(self, index: slice) -> List[Environment]: ...
-
+class Environments(ResourceSequence[Environment], Protocol):
     def create(
         self,
         *,
@@ -217,4 +209,3 @@ def find_by(
         ----
         This action requires administrator or publisher privileges.
         """
-        ...

src/posit/connect/groups.py

@@ -5,7 +5,7 @@
 from typing import TYPE_CHECKING, List, Optional, overload
 
 from .paginator import Paginator
-from .resources import Resource, Resources
+from .resources import BaseResource, Resources
 
 if TYPE_CHECKING:
     import requests
@@ -14,7 +14,7 @@
     from .users import User
 
 
-class Group(Resource):
+class Group(BaseResource):
     def __init__(self, ctx: Context, **kwargs) -> None:
         super().__init__(ctx, **kwargs)
         self._ctx: Context = ctx

src/posit/connect/jobs.py

@@ -1,18 +1,14 @@
 from __future__ import annotations
 
-from abc import abstractmethod
-from collections.abc import Mapping, Sized
 from typing import (
-    Any,
     Iterable,
-    List,
     Literal,
     Protocol,
-    SupportsIndex,
-    overload,
     runtime_checkable,
 )
 
+from .resources import Resource, ResourceSequence
+
 JobTag = Literal[
     "unknown",
     "build_report",
@@ -43,8 +39,7 @@
 StatusCode = Literal[0, 1, 2]
 
 
-class Job(Mapping[str, Any]):
-    @abstractmethod
+class Job(Resource, Protocol):
     def destroy(self) -> None:
         """Destroy the job.
 
@@ -59,13 +54,7 @@ def destroy(self) -> None:
 
 
 @runtime_checkable
-class Jobs(Sized, Protocol):
-    @overload
-    def __getitem__(self, index: SupportsIndex) -> Job: ...
-
-    @overload
-    def __getitem__(self, index: slice) -> List[Job]: ...
-
+class Jobs(ResourceSequence[Job], Protocol):
     def fetch(self) -> Iterable[Job]:
         """Fetch all jobs.
 

src/posit/connect/metrics/shiny_usage.py

@@ -3,10 +3,10 @@
 from typing import List, overload
 
 from ..cursors import CursorPaginator
-from ..resources import Resource, Resources
+from ..resources import BaseResource, Resources
 
 
-class ShinyUsageEvent(Resource):
+class ShinyUsageEvent(BaseResource):
     @property
     def content_guid(self) -> str:
         """The associated unique content identifier.

src/posit/connect/metrics/usage.py

@@ -10,7 +10,7 @@
 from . import shiny_usage, visits
 
 
-class UsageEvent(resources.Resource):
+class UsageEvent(resources.BaseResource):
     @staticmethod
     def from_event(
         event: visits.VisitEvent | shiny_usage.ShinyUsageEvent,

src/posit/connect/metrics/visits.py

@@ -3,10 +3,10 @@
 from typing import List, overload
 
 from ..cursors import CursorPaginator
-from ..resources import Resource, Resources
+from ..resources import BaseResource, Resources
 
 
-class VisitEvent(Resource):
+class VisitEvent(BaseResource):
     @property
     def content_guid(self) -> str:
         """The associated unique content identifier.

src/posit/connect/oauth/associations.py

@@ -3,10 +3,10 @@
 from typing import List
 
 from ..context import Context
-from ..resources import Resource, Resources
+from ..resources import BaseResource, Resources
 
 
-class Association(Resource):
+class Association(BaseResource):
     pass
 
 

src/posit/connect/oauth/integrations.py

@@ -2,11 +2,11 @@
 
 from typing import List, Optional, overload
 
-from ..resources import Resource, Resources
+from ..resources import BaseResource, Resources
 from .associations import IntegrationAssociations
 
 
-class Integration(Resource):
+class Integration(BaseResource):
     """OAuth integration resource."""
 
     @property