renames init arguments to path and pathinfo

Author: tdstein

src/posit/connect/content.py

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

src/posit/connect/jobs.py

@@ -101,34 +101,13 @@ class _Job(TypedDict):
         """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, base: str, uid: str, /, **attributes: Unpack[_Job]):
-        ...
+    def __init__(self, ctx: Context, path: str, pathinfo: str, /, **attributes: Unpack[_Job]): ...
 
     @overload
-    def __init__(self, ctx: Context, base: str, uid: str, /, **attributes: Any): ...
-
-    def __init__(self, ctx: Context, base: str, uid: str, /, **attributes: Any):
-        """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 containing the session and URL for API interactions.
-        base : str
-            The base HTTP path for the Job endpoint (e.g., '/jobs')
-        uid : str
-            The unique identifier
-        **attributes
-            Object items passed to the base resource dictionary.
+    def __init__(self, ctx: Context, path: str, pathinfo: str, /, **attributes: Any): ...
 
-        Notes
-        -----
-        A Job is a reference to a server process on Connect, it is not the process itself. Jobs are executed asynchronously.
-        """
-        super().__init__(ctx, **attributes)
-        self._endpoint = ctx.url + base + uid
+    def __init__(self, ctx: Context, path: str, pathinfo: str, /, **attributes: Any):
+        super().__init__(ctx, path, pathinfo, **attributes)
 
     def destroy(self) -> None:
         """Destroy the job.
@@ -143,11 +122,12 @@ 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: Context, base: str, path: str = "jobs", uid="key"):
+    def __init__(self, ctx: Context, path: str, pathinfo: str = "jobs", uid: str = "key"):
         """A collection of jobs.
 
         Parameters
@@ -161,9 +141,9 @@ def __init__(self, ctx: Context, base: str, path: str = "jobs", uid="key"):
         uid : str, optional
             The field name used to uniquely identify records, by default "key"
         """
-        super().__init__(ctx, base, path, uid)
+        super().__init__(ctx, path, pathinfo, uid)
 
-    def _create_instance(self, base: str, uid: str, **kwargs: Any) -> Job:
+    def _create_instance(self, path: str, pathinfo: str, **kwargs: Any) -> Job:
         """Creates a Job instance.
 
         Parameters
@@ -177,7 +157,7 @@ def _create_instance(self, base: str, uid: str, **kwargs: Any) -> Job:
         -------
         Job
         """
-        return Job(self._ctx, base, uid, **kwargs)
+        return Job(self._ctx, path, pathinfo, **kwargs)
 
     class _FindByRequest(TypedDict, total=False):
         # Identifiers
@@ -311,7 +291,7 @@ 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: Context, base: str, /, **kwargs):
+    def __init__(self, ctx, path, pathinfo="", /, **kwargs):
         """Mixin class which adds a `jobs` attribute to the Active Resource.
 
         Parameters
@@ -321,5 +301,5 @@ def __init__(self, ctx: Context, base: str, /, **kwargs):
         base : str
             The base path associated with the instance.
         """
-        super().__init__(ctx, **kwargs)
-        self.jobs = Jobs(ctx, base)
+        super().__init__(ctx, path, pathinfo, **kwargs)
+        self.jobs = Jobs(ctx, self._path)

src/posit/connect/resources.py

@@ -51,29 +51,41 @@ def __init__(self, params: ResourceParameters) -> None:
 
 
 class Active(ABC, Resource):
-    def __init__(self, ctx: Context, **kwargs):
-        """A base class representing an active resource.
+    def __init__(self, ctx: Context, path: str, pathinfo: 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.
-        **kwargs : dict
-            Additional keyword arguments passed to the parent `Resource` class.
+        path : str
+            The HTTP path component for the collection endpoint
+        pathinfo : str
+            The HTTP part of the path directed at a specific resource
+        **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, **kwargs)
+        super().__init__(params, **attributes)
         self._ctx = ctx
+        self._path = posixpath.join(path, pathinfo)
 
 
 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, base: str, name: str, uid="guid"):
+    def __init__(self, ctx: Context, path: str, pathinfo: str = "", uid: str = "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.
@@ -82,10 +94,10 @@ def __init__(self, ctx: Context, base: str, name: str, uid="guid"):
         ----------
         ctx : Context
             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
+        path : str
+            The HTTP path component for the collection endpoint
+        pathinfo : str
+            The HTTP part of the path directed at a specific resource
         uid : str, optional
             The field name used to uniquely identify records, by default "guid"
 
@@ -95,17 +107,14 @@ def __init__(self, ctx: Context, base: str, name: str, uid="guid"):
             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.
+            The field name used to uniquely identify records.
         _cache: Optional[List[T]]
         """
         super().__init__()
         self._ctx = ctx
-        self._path: str = posixpath.join(base, name)
-        self._endpoint: Url = ctx.url + self._path
-        self._uid: str = uid
+        self._path = posixpath.join(path, pathinfo)
+        self._uid = uid
         self._cache: Optional[List[T]] = None
 
     @property
@@ -125,7 +134,8 @@ def _data(self) -> List[T]:
         if self._cache:
             return self._cache
 
-        response = self._ctx.session.get(self._endpoint)
+        endpoint = self._ctx.url + self._path
+        response = self._ctx.session.get(endpoint)
         results = response.json()
 
         self._cache = []
@@ -155,7 +165,7 @@ def __repr__(self) -> str:
         return repr(self._data)
 
     @abstractmethod
-    def _create_instance(self, base: str, uid: str, /, **kwargs: Any) -> T:
+    def _create_instance(self, path: str, pathinfo: str, /, **kwargs: Any) -> T:
         """Create an instance of 'T'.
 
         Returns
@@ -201,7 +211,7 @@ def find(self, uid) -> T:
             if result:
                 return result
 
-        endpoint = self._endpoint + uid
+        endpoint = self._ctx.url + self._path + uid
         response = self._ctx.session.get(endpoint)
         result = response.json()
         result = self._create_instance(self._path, uid, **result)