refactor: inject url path parts instead of endpoints (#315)

Refactors path building responsibilities to the creating action,
eliminating a ton of complexity along the way.

---------

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

Author: tdstein

src/posit/connect/content.py

@@ -37,7 +37,9 @@ class ContentItemOwner(Resource):
 class ContentItem(JobsMixin, VanityMixin, Resource):
     def __init__(self, /, params: ResourceParameters, **kwargs):
         ctx = Context(params.session, params.url)
-        super().__init__(ctx, **kwargs)
+        uid = kwargs["guid"]
+        path = f"v1/content/{uid}"
+        super().__init__(ctx, path, **kwargs)
 
     def __getitem__(self, key: Any) -> Any:
         v = super().__getitem__(key)

src/posit/connect/jobs.py

@@ -1,7 +1,9 @@
-from typing import Literal, Optional, TypedDict, overload
+import posixpath
+from typing import Any, Literal, Optional, TypedDict, overload
 
 from typing_extensions import NotRequired, Required, Unpack
 
+from .context import Context
 from .resources import Active, ActiveFinderMethods, ActiveSequence, Resource
 
 JobTag = Literal[
@@ -99,13 +101,8 @@ class _Job(TypedDict):
         tag: Required[JobTag]
         """A tag categorizing the job type. Options are build_jupyter, build_report, build_site, configure_report, git, packrat_restore, python_restore, render_shiny, run_api, run_app, run_bokeh_app, run_dash_app, run_fastapi_app, run_pyshiny_app, run_python_api, run_streamlit, run_tensorflow, run_voila_app, testing, unknown, val_py_ext_pkg, val_r_ext_pkg, and val_r_install."""
 
-    def __init__(self, ctx, parent: Active, **kwargs: Unpack[_Job]):
-        super().__init__(ctx, parent, **kwargs)
-        self._parent = parent
-
-    @property
-    def _endpoint(self) -> str:
-        return self._ctx.url + f"v1/content/{self._parent['guid']}/jobs/{self['key']}"
+    def __init__(self, ctx: Context, path: str, /, **attributes: Unpack[_Job]):
+        super().__init__(ctx, path, **attributes)
 
     def destroy(self) -> None:
         """Destroy the job.
@@ -120,40 +117,36 @@ def destroy(self) -> None:
         ----
         This action requires administrator, owner, or collaborator privileges.
         """
-        self._ctx.session.delete(self._endpoint)
+        endpoint = self._ctx.url + self._path
+        self._ctx.session.delete(endpoint)
 
 
-class Jobs(
-    ActiveFinderMethods[Job],
-    ActiveSequence[Job],
-):
-    def __init__(self, ctx, parent: Active, uid="key"):
+class Jobs(ActiveFinderMethods[Job], ActiveSequence[Job]):
+    def __init__(self, ctx: Context, path: str):
         """A collection of jobs.
 
         Parameters
         ----------
         ctx : Context
-            The context containing the HTTP session used to interact with the API.
-        parent : Active
-            Parent resource for maintaining hierarchical relationships
-        uid : str, optional
-            The default field name used to uniquely identify records, by default "key"
+            The context object containing the session and URL for API interactions
+        path : str
+            The HTTP path component for the jobs endpoint (e.g., 'v1/content/544509fc-e4f0-41de-acb4-1fe3a2c1d797/jobs')
         """
-        super().__init__(ctx, parent, uid)
-        self._parent = parent
+        super().__init__(ctx, path, "key")
 
-    @property
-    def _endpoint(self) -> str:
-        return self._ctx.url + f"v1/content/{self._parent['guid']}/jobs"
+    def _create_instance(self, path: str, /, **attributes: Any) -> Job:
+        """Creates a Job instance.
 
-    def _create_instance(self, **kwargs) -> Job:
-        """Creates a `Job` instance.
+        Parameters
+        ----------
+        path : str
+            The HTTP path component for the Job resource endpoint (e.g., 'v1/content/544509fc-e4f0-41de-acb4-1fe3a2c1d797/jobs/7add0bc0-0d89-4397-ab51-90ad4bc3f5c9')
 
         Returns
         -------
         Job
         """
-        return Job(self._ctx, self._parent, **kwargs)
+        return Job(self._ctx, path, **attributes)
 
     class _FindByRequest(TypedDict, total=False):
         # Identifiers
@@ -287,6 +280,19 @@ def find_by(self, **conditions) -> Optional[Job]:
 class JobsMixin(Active, Resource):
     """Mixin class to add a jobs attribute to a resource."""
 
-    def __init__(self, ctx, **kwargs):
-        super().__init__(ctx, **kwargs)
-        self.jobs = Jobs(ctx, self)
+    def __init__(self, ctx, path, /, **attributes):
+        """Mixin class which adds a `jobs` attribute to the Active Resource.
+
+        Parameters
+        ----------
+        ctx : Context
+            The context object containing the session and URL for API interactions
+        path : str
+            The HTTP path component for the resource endpoint
+        **attributes : dict
+            Resource attributes passed
+        """
+        super().__init__(ctx, path, **attributes)
+
+        path = posixpath.join(path, "jobs")
+        self.jobs = Jobs(ctx, path)

src/posit/connect/resources.py

@@ -1,3 +1,4 @@
+import posixpath
 import warnings
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
@@ -50,84 +51,105 @@ def __init__(self, params: ResourceParameters) -> None:
 
 
 class Active(ABC, Resource):
-    def __init__(self, ctx: Context, parent: Optional["Active"] = None, **kwargs):
-        """A base class representing an active resource.
+    def __init__(self, ctx: Context, path: str, /, **attributes):
+        """A dict abstraction for any HTTP endpoint that returns a singular resource.
 
         Extends the `Resource` class and provides additional functionality for via the session context and an optional parent resource.
 
         Parameters
         ----------
         ctx : Context
             The context object containing the session and URL for API interactions.
-        parent : Optional[Active], optional
-            An optional parent resource that establishes a hierarchical relationship, by default None.
-        **kwargs : dict
-            Additional keyword arguments passed to the parent `Resource` class.
+        path : str
+            The HTTP path component for the resource endpoint
+        **attributes : dict
+            Resource attributes passed
         """
         params = ResourceParameters(ctx.session, ctx.url)
-        super().__init__(params, **kwargs)
+        super().__init__(params, **attributes)
         self._ctx = ctx
-        self._parent = parent
+        self._path = path
 
 
 T = TypeVar("T", bound="Active")
 """A type variable that is bound to the `Active` class"""
 
 
 class ActiveSequence(ABC, Generic[T], Sequence[T]):
-    def __init__(self, ctx: Context, parent: Optional[Active] = None):
-        """A sequence abstraction for any HTTP GET endpoint that returns a collection.
+    """A sequence for any HTTP GET endpoint that returns a collection."""
+
+    _cache: Optional[List[T]]
 
-        It lazily fetches data on demand, caches the results, and allows for standard sequence operations like indexing and slicing.
+    def __init__(self, ctx: Context, path: str, uid: str = "guid"):
+        """A sequence abstraction for any HTTP GET endpoint that returns a collection.
 
         Parameters
         ----------
         ctx : Context
-            The context object that holds the HTTP session used for sending the GET request.
-        parent : Optional[Active], optional
-            An optional parent resource to establish a nested relationship, by default None.
+            The context object containing the session and URL for API interactions.
+        path : str
+            The HTTP path component for the collection endpoint
+        uid : str, optional
+            The field name of that uniquely identifiers an instance of T, by default "guid"
         """
         super().__init__()
         self._ctx = ctx
-        self._parent = parent
-        self._cache: Optional[List[T]] = None
+        self._path = path
+        self._uid = uid
+        self._cache = None
 
-    @property
     @abstractmethod
-    def _endpoint(self) -> str:
+    def _create_instance(self, path: str, /, **kwargs: Any) -> T:
+        """Create an instance of 'T'."""
+        raise NotImplementedError()
+
+    def reload(self) -> Self:
+        """Reloads the collection from Connect.
+
+        Returns
+        -------
+        Self
         """
-        Abstract property to define the endpoint URL for the GET request.
+        self._cache = None
+        return self
+
+    def _fetch(self) -> List[T]:
+        """Fetch the collection.
 
-        Subclasses must implement this property to return the API endpoint URL that will
-        be queried to fetch the data.
+        Fetches the collection directly from Connect. This operation does not effect the cache state.
 
         Returns
         -------
-        str
-            The API endpoint URL.
+        List[T]
         """
-        raise NotImplementedError()
+        endpoint = self._ctx.url + self._path
+        response = self._ctx.session.get(endpoint)
+        results = response.json()
+        return [self._to_instance(result) for result in results]
+
+    def _to_instance(self, result: dict) -> T:
+        """Converts a result into an instance of T."""
+        uid = result[self._uid]
+        path = posixpath.join(self._path, uid)
+        return self._create_instance(path, **result)
 
     @property
     def _data(self) -> List[T]:
-        """
-        Fetch and cache the data from the API.
+        """Get the collection.
 
-        This method sends a GET request to the `_endpoint` and parses the response as a list of JSON objects.
-        Each JSON object is used to instantiate an item of type `T` using the class specified by `_cls`.
-        The results are cached after the first request and reused for subsequent access unless reloaded.
+        Fetches the collection from Connect and caches the result. Subsequent invocations return the cached results unless the cache is explicitly reset.
 
         Returns
         -------
         List[T]
-            A list of items of type `T` representing the fetched data.
-        """
-        if self._cache:
-            return self._cache
 
-        response = self._ctx.session.get(self._endpoint)
-        results = response.json()
-        self._cache = [self._create_instance(**result) for result in results]
+        See Also
+        --------
+        cached
+        reload
+        """
+        if self._cache is None:
+            self._cache = self._fetch()
         return self._cache
 
     @overload
@@ -148,52 +170,18 @@ def __str__(self) -> str:
     def __repr__(self) -> str:
         return repr(self._data)
 
-    @abstractmethod
-    def _create_instance(self, **kwargs) -> T:
-        """Create an instance of 'T'.
 
-        Returns
-        -------
-        T
-        """
-        raise NotImplementedError()
+class ActiveFinderMethods(ActiveSequence[T], ABC):
+    """Finder methods.
 
-    def reload(self) -> Self:
-        """
-        Clear the cache and reload the data from the API on the next access.
-
-        Returns
-        -------
-        ActiveSequence
-            The current instance with cleared cache, ready to reload data on next access.
-        """
-        self._cache = None
-        return self
-
-
-class ActiveFinderMethods(ActiveSequence[T], ABC, Generic[T]):
-    def __init__(self, ctx: Context, parent: Optional[Active] = None, uid: str = "guid"):
-        """Finder methods.
-
-        Provides various finder methods for locating records in any endpoint supporting HTTP GET requests.
-
-        Parameters
-        ----------
-        ctx : Context
-            The context containing the HTTP session used to interact with the API.
-        parent : Optional[Active], optional
-            Optional parent resource for maintaining hierarchical relationships, by default None
-        uid : str, optional
-            The default field name used to uniquely identify records, by default "guid"
-        """
-        super().__init__(ctx, parent)
-        self._uid = uid
+    Provides various finder methods for locating records in any endpoint supporting HTTP GET requests.
+    """
 
     def find(self, uid) -> T:
         """
         Find a record by its unique identifier.
 
-        Fetches a record either by searching the cache or by making a GET request to the endpoint.
+        Fetches the record from Connect by it's identifier.
 
         Parameters
         ----------
@@ -203,26 +191,11 @@ def find(self, uid) -> T:
         Returns
         -------
         T
-
-        Raises
-        ------
-        ValueError
-            If no record is found.
         """
-        # todo - add some more comments about this
-        if self._cache:
-            conditions = {self._uid: uid}
-            result = self.find_by(**conditions)
-        else:
-            endpoint = self._endpoint + uid
-            response = self._ctx.session.get(endpoint)
-            result = response.json()
-            result = self._create_instance(**result)
-
-        if not result:
-            raise ValueError(f"Failed to find instance where {self._uid} is '{uid}'")
-
-        return result
+        endpoint = self._ctx.url + self._path + uid
+        response = self._ctx.session.get(endpoint)
+        result = response.json()
+        return self._to_instance(result)
 
     def find_by(self, **conditions: Any) -> Optional[T]:
         """