refactor: inject url path parts instead of endpoints

Author: tdstein

src/posit/connect/content.py

@@ -37,7 +37,8 @@ class ContentItemOwner(Resource):
 class ContentItem(JobsMixin, VanityMixin, Resource):
     def __init__(self, /, params: ResourceParameters, **kwargs):
         ctx = Context(params.session, params.url)
-        super().__init__(ctx, **kwargs)
+        base = f"v1/content/{kwargs['guid']}"
+        super().__init__(ctx, base, **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
+from typing import Any, Literal, Optional, TypedDict, overload
 
 from typing_extensions import NotRequired, Required, Unpack
 
+from posit.connect.context import Context
+
 from .resources import Active, ActiveFinderMethods, ActiveSequence, Resource
 
 JobTag = Literal[
@@ -99,13 +101,31 @@ 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
+    @overload
+    def __init__(self, ctx: Context, base: str, uid: str, /, **kwargs: Unpack[_Job]):
+        """A Job.
+
+        A Job represents single execution instance of Content on Connect. Whenever Content runs, whether it's a scheduled report, a script execution, or server processes related to an application, a Job is created to manage and encapsulate that execution.
+
+        Parameters
+        ----------
+        ctx : Context
+            The context object that holds the HTTP session used for sending the GET request.
+        parent : ContentItem
+            The Content related to this Job.
+
+        Notes
+        -----
+        A Job is a reference to a server process on Connect, it is not the process itself. Jobs are executed asynchronously
+        """
+        ...
+
+    @overload
+    def __init__(self, ctx: Context, base: str, uid: str, /, **kwargs: Any): ...
 
-    @property
-    def _endpoint(self) -> str:
-        return self._ctx.url + f"v1/content/{self._parent['guid']}/jobs/{self['key']}"
+    def __init__(self, ctx: Context, base: str, uid: str, /, **kwargs: Any):
+        super().__init__(ctx, **kwargs)
+        self._endpoint = ctx.url + base + uid
 
     def destroy(self) -> None:
         """Destroy the job.
@@ -123,37 +143,38 @@ def destroy(self) -> None:
         self._ctx.session.delete(self._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, base: str, path: str = "jobs", uid="key"):
         """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
+            The context object containing the session and URL for API interactions
+        base : str
+            The base HTTP path for the collection endpoint
+        name : str
+            The collection name, by default "jobs"
         uid : str, optional
-            The default field name used to uniquely identify records, by default "key"
+            The field name used to uniquely identify records, by default "key"
         """
-        super().__init__(ctx, parent, uid)
-        self._parent = parent
+        super().__init__(ctx, base, path, uid)
 
-    @property
-    def _endpoint(self) -> str:
-        return self._ctx.url + f"v1/content/{self._parent['guid']}/jobs"
+    def _create_instance(self, base: str, uid: str, **kwargs: Any) -> Job:
+        """Creates a Job instance.
 
-    def _create_instance(self, **kwargs) -> Job:
-        """Creates a `Job` instance.
+        Parameters
+        ----------
+        base : str
+            The base HTTP path for the instance endpoint
+        uid : str
+            The unique identifier for the instance.
 
         Returns
         -------
         Job
         """
-        return Job(self._ctx, self._parent, **kwargs)
+        return Job(self._ctx, base, uid, **kwargs)
 
     class _FindByRequest(TypedDict, total=False):
         # Identifiers
@@ -287,6 +308,15 @@ 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):
+    def __init__(self, ctx: Context, base: str, /, **kwargs):
+        """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
+        base : str
+            The base path associated with the instance.
+        """
         super().__init__(ctx, **kwargs)
-        self.jobs = Jobs(ctx, self)
+        self.jobs = Jobs(ctx, base)

src/posit/connect/resources.py

@@ -1,3 +1,4 @@
+import posixpath
 import warnings
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
@@ -50,7 +51,7 @@ def __init__(self, params: ResourceParameters) -> None:
 
 
 class Active(ABC, Resource):
-    def __init__(self, ctx: Context, parent: Optional["Active"] = None, **kwargs):
+    def __init__(self, ctx: Context, **kwargs):
         """A base class representing an active resource.
 
         Extends the `Resource` class and provides additional functionality for via the session context and an optional parent resource.
@@ -59,55 +60,54 @@ def __init__(self, ctx: Context, parent: Optional["Active"] = None, **kwargs):
         ----------
         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.
         """
         params = ResourceParameters(ctx.session, ctx.url)
         super().__init__(params, **kwargs)
         self._ctx = ctx
-        self._parent = parent
 
 
 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):
+    def __init__(self, ctx: Context, base: str, name: str, uid="guid"):
         """A sequence abstraction 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.
 
         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
+        base : str
+            The base HTTP path for the collection endpoint
+        name : str
+            The collection name
+        uid : str, optional
+            The field name used to uniquely identify records, by default "guid"
+
+        Attributes
+        ----------
+        _ctx : Context
+            The context object containing the session and URL for API interactions
+        _path : str
+            The HTTP path for the collection endpoint.
+        _endpoint : Url
+            The HTTP URL for the collection endpoint.
+        _uid : str
+            The default field name used to uniquely identify records.
+        _cache: Optional[List[T]]
         """
         super().__init__()
         self._ctx = ctx
-        self._parent = parent
+        self._path: str = posixpath.join(base, name)
+        self._endpoint: Url = ctx.url + self._path
+        self._uid: str = uid
         self._cache: Optional[List[T]] = None
 
-    @property
-    @abstractmethod
-    def _endpoint(self) -> str:
-        """
-        Abstract property to define the endpoint URL for the GET request.
-
-        Subclasses must implement this property to return the API endpoint URL that will
-        be queried to fetch the data.
-
-        Returns
-        -------
-        str
-            The API endpoint URL.
-        """
-        raise NotImplementedError()
-
     @property
     def _data(self) -> List[T]:
         """
@@ -127,7 +127,13 @@ def _data(self) -> List[T]:
 
         response = self._ctx.session.get(self._endpoint)
         results = response.json()
-        self._cache = [self._create_instance(**result) for result in results]
+
+        self._cache = []
+        for result in results:
+            uid = result[self._uid]
+            instance = self._create_instance(self._path, uid, **result)
+            self._cache.append(instance)
+
         return self._cache
 
     @overload
@@ -149,7 +155,7 @@ def __repr__(self) -> str:
         return repr(self._data)
 
     @abstractmethod
-    def _create_instance(self, **kwargs) -> T:
+    def _create_instance(self, base: str, uid: str, /, **kwargs: Any) -> T:
         """Create an instance of 'T'.
 
         Returns
@@ -171,29 +177,12 @@ def reload(self) -> Self:
         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
-
+class ActiveFinderMethods(ActiveSequence[T], ABC):
     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.
+        If the cache is already populated, it is checked first for matching record. If not, a conventional GET request is made to the Connect server.
 
         Parameters
         ----------
@@ -203,24 +192,23 @@ def find(self, uid) -> T:
         Returns
         -------
         T
-
-        Raises
-        ------
-        ValueError
-            If no record is found.
         """
-        # todo - add some more comments about this
         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.
             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}'")
+            if result:
+                return result
+
+        endpoint = self._endpoint + 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
 

src/posit/connect/vanities.py

@@ -70,10 +70,7 @@ def __init__(
         super().__init__(params, **kwargs)
         self._after_destroy = after_destroy
         self._content_guid = kwargs["content_guid"]
-
-    @property
-    def _endpoint(self):
-        return self.params.url + f"v1/content/{self._content_guid}/vanity"
+        self.__endpoint = self.params.url + f"v1/content/{self._content_guid}/vanity"
 
     def destroy(self) -> None:
         """Destroy the vanity.
@@ -91,7 +88,7 @@ def destroy(self) -> None:
         ----
         This action requires administrator privileges.
         """
-        self.params.session.delete(self._endpoint)
+        self.params.session.delete(self.__endpoint)
 
         if self._after_destroy:
             self._after_destroy()
@@ -128,12 +125,9 @@ class HasGuid(TypedDict):
     def __init__(self, params: ResourceParameters, **kwargs: Unpack[HasGuid]):
         super().__init__(params, **kwargs)
         self._content_guid = kwargs["guid"]
+        self.__endpoint = self.params.url + f"v1/content/{self._content_guid}/vanity"
         self._vanity: Optional[Vanity] = None
 
-    @property
-    def _endpoint(self):
-        return self.params.url + f"v1/content/{self._content_guid}/vanity"
-
     @property
     def vanity(self) -> Optional[str]:
         """Get the vanity."""
@@ -220,7 +214,8 @@ def create_vanity(self, **kwargs: Unpack[CreateVanityRequest]) -> Vanity:
         --------
         If setting force=True, the destroy operation performed on the other vanity is irreversible.
         """
-        response = self.params.session.put(self._endpoint, json=kwargs)
+        print(self.__endpoint)
+        response = self.params.session.put(self.__endpoint, json=kwargs)
         result = response.json()
         return Vanity(self.params, **result)
 
@@ -231,6 +226,7 @@ def find_vanity(self) -> Vanity:
         -------
         Vanity
         """
-        response = self.params.session.get(self._endpoint)
+        print(self.__endpoint)
+        response = self.params.session.get(self.__endpoint)
         result = response.json()
         return Vanity(self.params, **result)

tests/posit/connect/test_jobs.py

@@ -73,15 +73,14 @@ def test_miss(self):
         )
 
         responses.get(
-            "https://connect.example/__api__/v1/content/f2f37341-e21d-3d80-c698-a935ad614066/jobs",
-            json=load_mock("v1/content/f2f37341-e21d-3d80-c698-a935ad614066/jobs.json"),
+            "https://connect.example/__api__/v1/content/f2f37341-e21d-3d80-c698-a935ad614066/jobs/not-found",
+            status=404,
         )
 
         c = Client("https://connect.example", "12345")
         content = c.content.get("f2f37341-e21d-3d80-c698-a935ad614066")
 
-        assert content.jobs
-        with pytest.raises(ValueError):
+        with pytest.raises(Exception):
             content.jobs.find("not-found")