refactor: inject url path parts instead of endpoints

src/posit/connect/content.py

@@ -37,9 +37,9 @@ class ContentItemOwner(Resource):
 class ContentItem(JobsMixin, VanityMixin, Resource):
     def __init__(self, /, params: ResourceParameters, **kwargs):
         ctx = Context(params.session, params.url)
-        path = f"v1/content"
-        pathinfo = kwargs["guid"]
-        super().__init__(ctx, path, pathinfo, **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,3 +1,4 @@
+import posixpath
 from typing import Any, Literal, Optional, TypedDict, overload
 
 from typing_extensions import NotRequired, Required, Unpack
@@ -100,14 +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."""
 
-    @overload
-    def __init__(self, ctx: Context, path: str, pathinfo: str, /, **attributes: Unpack[_Job]): ...
-
-    @overload
-    def __init__(self, ctx: Context, path: str, pathinfo: str, /, **attributes: Any): ...
-
-    def __init__(self, ctx: Context, path: str, pathinfo: str, /, **attributes: Any):
-        super().__init__(ctx, path, pathinfo, **attributes)
+    def __init__(self, ctx: Context, path: str, /, **attributes: Unpack[_Job]):
+        super().__init__(ctx, path, **attributes)
 
     def destroy(self) -> None:
         """Destroy the job.
@@ -127,37 +122,31 @@ def destroy(self) -> None:
 
 
 class Jobs(ActiveFinderMethods[Job], ActiveSequence[Job]):
-    def __init__(self, ctx: Context, path: str, pathinfo: str = "jobs", uid: str = "key"):
+    def __init__(self, ctx: Context, path: str):
         """A collection of jobs.
 
         Parameters
         ----------
         ctx : Context
             The context object containing the session and URL for API interactions
         path : str
-            The HTTP path component for the collection endpoint
-        pathinfo : str
-            The HTTP part of the path directed at a specific resource, by default "jobs"
-        uid : str, optional
-            The field name used to uniquely identify records, by default "guid"
+            The HTTP path component for the jobs endpoint (e.g., 'v1/content/544509fc-e4f0-41de-acb4-1fe3a2c1d797/jobs')
         """
-        super().__init__(ctx, path, pathinfo, uid)
+        super().__init__(ctx, path, "key")
 
-    def _create_instance(self, path: str, pathinfo: str, /, **kwargs: Any) -> Job:
+    def _create_instance(self, path: str, /, **attributes: Any) -> Job:
         """Creates a Job instance.
 
         Parameters
         ----------
         path : str
-            The HTTP path component for the collection endpoint
-        pathinfo : str
-            The HTTP part of the path directed at a specific resource
+            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, path, pathinfo, **kwargs)
+        return Job(self._ctx, path, **attributes)
 
     class _FindByRequest(TypedDict, total=False):
         # Identifiers
@@ -291,19 +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, path, pathinfo="", /, **kwargs):
+    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.
+            The context object containing the session and URL for API interactions
         path : str
-            The HTTP path component for the collection endpoint
-        pathinfo : str
-            The HTTP part of the path directed at a specific resource
+            The HTTP path component for the resource endpoint
         **attributes : dict
             Resource attributes passed
         """
-        super().__init__(ctx, path, pathinfo, **kwargs)
-        self.jobs = Jobs(ctx, self._path)
+        super().__init__(ctx, path, **attributes)
+
+        path = posixpath.join(path, "jobs")
+        self.jobs = Jobs(ctx, path)

src/posit/connect/resources.py

@@ -51,7 +51,7 @@ def __init__(self, params: ResourceParameters) -> None:
 
 
 class Active(ABC, Resource):
-    def __init__(self, ctx: Context, path: str, pathinfo: str = "", /, **attributes):
+    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.
@@ -61,77 +61,108 @@ def __init__(self, ctx: Context, path: str, pathinfo: str = "", /, **attributes)
         ctx : Context
             The context object containing the session and URL for API interactions.
         path : str
-            The HTTP path component for the collection endpoint
-        pathinfo : str
-            The HTTP part of the path directed at a specific resource
+            The HTTP path component for the resource endpoint
         **attributes : dict
             Resource attributes passed
-
-        Attributes
-        ----------
-        _ctx : Context
-            The context object containing the session and URL for API interactions
-        _path : str
-            The HTTP path for the collection endpoint.
         """
         params = ResourceParameters(ctx.session, ctx.url)
         super().__init__(params, **attributes)
         self._ctx = ctx
-        self._path = posixpath.join(path, pathinfo)
+        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, path: str, pathinfo: str = "", uid: str = "guid"):
-        """A sequence abstraction for any HTTP GET endpoint that returns a collection.
+    """A sequence for any HTTP GET endpoint that returns a collection."""
 
-        It lazily fetches data on demand, caches the results, and allows for standard sequence operations like indexing and slicing.
+    _cache: Optional[List[T]]
 
-        Attributes
+    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 containing the session and URL for API interactions
-        _path : str
-            The HTTP path for the collection endpoint.
-        _uid : str
-            The field name used to uniquely identify records.
-        _cache: Optional[List[T]]
+        ctx : Context
+            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._path = posixpath.join(path, pathinfo)
+        self._path = path
         self._uid = uid
-        self._cache: Optional[List[T]] = None
+        self._cache = None
+
+    @abstractmethod
+    def _create_instance(self, path: str, /, **kwargs: Any) -> T:
+        """Create an instance of 'T'."""
+        raise NotImplementedError()
+
+    def cached(self) -> bool:
+        """Returns True if the collection is cached.
 
-    def _get_or_fetch(self) -> List[T]:
+        Returns
+        -------
+        bool
+
+        See Also
+        --------
+        reload
         """
-        Fetch and cache the data from the API.
+        return self._cache is not None
 
-        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.
+    def reload(self) -> Self:
+        """Reloads the collection from Connect.
 
         Returns
         -------
-        List[T]
-            A list of items of type `T` representing the fetched data.
+        Self
         """
-        if self._cache is not None:
-            return self._cache
+        self._cache = None
+        return self
+
+    def _fetch(self) -> List[T]:
+        """Fetch the collection.
+
+        Fetches the collection directly from Connect. This operation does not effect the cache state.
 
+        Returns
+        -------
+        List[T]
+        """
         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]:
+        """Get the collection.
+
+        Fetches the collection from Connect and caches the result. Subsequent invocations return the cached results unless the cache is explicitly reset.
 
-        self._cache = []
-        for result in results:
-            uid = result[self._uid]
-            instance = self._create_instance(self._path, uid, **result)
-            self._cache.append(instance)
+        Returns
+        -------
+        List[T]
 
+        See Also
+        --------
+        cached
+        reload
+        """
+        if self._cache is None:
+            self._cache = self._fetch()
         return self._cache
 
     @overload
@@ -141,42 +172,16 @@ def __getitem__(self, index: int) -> T: ...
     def __getitem__(self, index: slice) -> Sequence[T]: ...
 
     def __getitem__(self, index):
-        data = self._get_or_fetch()
-        return data[index]
+        return self._data[index]
 
     def __len__(self) -> int:
-        data = self._get_or_fetch()
-        return len(data)
+        return len(self._data)
 
     def __str__(self) -> str:
-        data = self._get_or_fetch()
-        return str(data)
+        return str(self._data)
 
     def __repr__(self) -> str:
-        data = self._get_or_fetch()
-        return repr(data)
-
-    @abstractmethod
-    def _create_instance(self, path: str, pathinfo: str, /, **kwargs: Any) -> T:
-        """Create an instance of 'T'.
-
-        Returns
-        -------
-        T
-        """
-        raise NotImplementedError()
-
-    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
+        return repr(self._data)
 
 
 class ActiveFinderMethods(ActiveSequence[T], ABC):
@@ -200,9 +205,7 @@ def find(self, uid) -> T:
         -------
         T
         """
-        if self._cache:
-            # Check if the record already exists in the cache.
-            # It is assumed that local cache scan is faster than an additional HTTP request.
+        if self.cached():
             conditions = {self._uid: uid}
             result = self.find_by(**conditions)
             if result:
@@ -211,13 +214,7 @@ def find(self, uid) -> T:
         endpoint = self._ctx.url + self._path + uid
         response = self._ctx.session.get(endpoint)
         result = response.json()
-        result = self._create_instance(self._path, uid, **result)
-
-        # Invalidate the cache.
-        # It is assumed that the cache is stale since a record exists on the server and not in the cache.
-        self._cache = None
-
-        return result
+        return self._to_instance(result)
 
     def find_by(self, **conditions: Any) -> Optional[T]:
         """
@@ -234,5 +231,4 @@ def find_by(self, **conditions: Any) -> Optional[T]:
         Optional[T]
             The first record matching the conditions, or `None` if no match is found.
         """
-        data = self._get_or_fetch()
-        return next((v for v in data if v.items() >= conditions.items()), None)
+        return next((v for v in self._data if v.items() >= conditions.items()), None)