fix: add fetch to packages protocol (#359)

Author: tdstein

src/posit/connect/client.py

@@ -23,7 +23,7 @@
 
 if TYPE_CHECKING:
     from .environments import Environments
-    from .packages import _Packages
+    from .packages import Packages
 
 
 class Client(ContextManager):
@@ -299,7 +299,7 @@ def oauth(self) -> OAuth:
 
     @property
     @requires(version="2024.11.0")
-    def packages(self) -> _Packages:
+    def packages(self) -> Packages:
         return _PaginatedResourceSequence(self._ctx, "v1/packages", uid="name")
 
     @property

src/posit/connect/content.py

@@ -33,7 +33,7 @@
 if TYPE_CHECKING:
     from .context import Context
     from .jobs import Jobs
-    from .packages import _ContentPackages
+    from .packages import ContentPackages
     from .tasks import Task
 
 
@@ -519,7 +519,7 @@ def jobs(self) -> Jobs:
 
     @property
     @requires(version="2024.11.0")
-    def packages(self) -> _ContentPackages:
+    def packages(self) -> ContentPackages:
         path = posixpath.join(self._path, "packages")
         return _ResourceSequence(self._ctx, path, uid="name")
 

src/posit/connect/packages.py

@@ -1,19 +1,56 @@
 from __future__ import annotations
 
-from collections.abc import Mapping, Sized
-from typing import Any, Literal, Protocol, SupportsIndex, overload
-
-
-class _ContentPackage(Mapping[str, Any]):
+from typing_extensions import (
+    Any,
+    Iterable,
+    Literal,
+    Mapping,
+    Protocol,
+    Sized,
+    SupportsIndex,
+    overload,
+)
+
+
+class ContentPackage(Mapping[str, Any]):
     pass
 
 
-class _ContentPackages(Sized, Protocol):
+class ContentPackages(Sized, Protocol):
     @overload
-    def __getitem__(self, index: SupportsIndex) -> _ContentPackage: ...
+    def __getitem__(self, index: SupportsIndex) -> ContentPackage: ...
 
     @overload
-    def __getitem__(self, index: slice) -> _ContentPackage: ...
+    def __getitem__(self, index: slice) -> ContentPackage: ...
+
+    def fetch(
+        self,
+        *,
+        language: Literal["python", "r"] = ...,
+        name: str = ...,
+        version: str = ...,
+        hash: str | None = ...,  # noqa: A002
+    ) -> Iterable[ContentPackage]:
+        """
+        Fetch all records matching the specified conditions.
+
+        Parameters
+        ----------
+        language : {"python", "r"}, not required
+            Programming language ecosystem, options are 'python' and 'r'
+        name : str, not required
+            The package name
+        version : str, not required
+            The package version
+        hash : str or None, optional, not required
+            Package description hash for R packages.
+
+        Returns
+        -------
+        List[ContentPackage]
+            The first record matching the specified conditions, or `None` if no such record exists.
+        """
+        ...
 
     def find_by(
         self,
@@ -22,7 +59,7 @@ def find_by(
         name: str = ...,
         version: str = ...,
         hash: str | None = ...,  # noqa: A002
-    ) -> _ContentPackage | None:
+    ) -> ContentPackage | None:
         """
         Find the first record matching the specified conditions.
 
@@ -41,22 +78,60 @@ def find_by(
 
         Returns
         -------
-        _ContentPackage | None
+        ContentPackage | None
             The first record matching the specified conditions, or `None` if no such record exists.
         """
         ...
 
 
-class _Package(Mapping[str, Any]):
+class Package(Mapping[str, Any]):
     pass
 
 
-class _Packages(Sized, Protocol):
+class Packages(Sized, Protocol):
     @overload
-    def __getitem__(self, index: SupportsIndex) -> _ContentPackage: ...
+    def __getitem__(self, index: SupportsIndex) -> ContentPackage: ...
 
     @overload
-    def __getitem__(self, index: slice) -> _ContentPackage: ...
+    def __getitem__(self, index: slice) -> ContentPackage: ...
+
+    def fetch(
+        self,
+        *,
+        language: Literal["python", "r"] = ...,
+        name: str = ...,
+        version: str = ...,
+        hash: str | None = ...,  # noqa: A002,
+        bundle_id: str = ...,
+        app_id: str = ...,
+        app_guid: str = ...,
+    ) -> Iterable[Package]:
+        """
+        Fetch all records matching the specified conditions.
+
+        Parameters
+        ----------
+        language : {"python", "r"}, not required
+            Programming language ecosystem, options are 'python' and 'r'
+        name : str, not required
+            The package name
+        version : str, not required
+            The package version
+        hash : str or None, optional, not required
+            Package description hash for R packages.
+        bundle_id: str, not required
+            The unique identifier of the bundle this package is associated with.
+        app_id: str, not required
+            The numerical identifier of the application this package is associated with.
+        app_guid: str, not required
+            The unique identifier of the application this package is associated with.
+
+        Returns
+        -------
+        List[Package]
+            The first record matching the specified conditions, or `None` if no such record exists.
+        """
+        ...
 
     def find_by(
         self,
@@ -68,7 +143,7 @@ def find_by(
         bundle_id: str = ...,
         app_id: str = ...,
         app_guid: str = ...,
-    ) -> _ContentPackage | None:
+    ) -> Package | None:
         """
         Find the first record matching the specified conditions.
 
@@ -93,7 +168,7 @@ def find_by(
 
         Returns
         -------
-        _Package | None
+        Package | None
             The first record matching the specified conditions, or `None` if no such record exists.
         """
         ...