feat: adds query params to find and find_one (#130)

requirements-dev.txt

@@ -3,8 +3,9 @@ coverage
 mypy
 pandas
 pre-commit
+pyjson5
 pytest
 responses
 ruff
-setuptools-scm
 setuptools
+setuptools-scm

src/posit/connect/paginator.py

@@ -37,9 +37,10 @@ class Paginator:
         url (str): The URL of the paginated API endpoint.
     """
 
-    def __init__(self, session: requests.Session, url: str) -> None:
+    def __init__(self, session: requests.Session, url: str, params: dict = {}) -> None:
         self.session = session
         self.url = url
+        self.params = params
 
     def fetch_results(self) -> List[dict]:
         """
@@ -90,6 +91,10 @@ def fetch_page(self, page_number: int) -> Page:
             Page: The fetched page object.
 
         """
-        params = {"page_number": page_number, "page_size": _MAX_PAGE_SIZE}
+        params = {
+            **self.params,
+            "page_number": page_number,
+            "page_size": _MAX_PAGE_SIZE,
+        }
         response = self.session.get(self.url, params=params)
         return Page(**response.json())

src/posit/connect/users.py

@@ -152,8 +152,17 @@ def __init__(self, config: Config, session: requests.Session) -> None:
         self.config = config
         self.session = session
 
-    def find(self) -> List[User]:
-        paginator = Paginator(self.session, self.url)
+    @overload
+    def find(
+        self, prefix: str = ..., user_role: str = ..., account_status: str = ...
+    ) -> List[User]: ...
+
+    @overload
+    def find(self, *args, **kwargs) -> List[User]: ...
+
+    def find(self, *args, **kwargs):
+        params = dict(*args, **kwargs)
+        paginator = Paginator(self.session, self.url, params=params)
         results = paginator.fetch_results()
         return [
             User(
@@ -164,8 +173,17 @@ def find(self) -> List[User]:
             for user in results
         ]
 
-    def find_one(self) -> User | None:
-        paginator = Paginator(self.session, self.url)
+    @overload
+    def find_one(
+        self, prefix: str = ..., user_role: str = ..., account_status: str = ...
+    ) -> User | None: ...
+
+    @overload
+    def find_one(self, *args, **kwargs) -> User | None: ...
+
+    def find_one(self, *args, **kwargs) -> User | None:
+        params = dict(*args, **kwargs)
+        paginator = Paginator(self.session, self.url, params=params)
         pages = paginator.fetch_pages()
         results = (result for page in pages for result in page.results)
         users = (

tests/posit/connect/__api__/v1/users?page_number=1&page_size=500.json → tests/posit/connect/__api__/v1/users?page_number=1&page_size=500.jsonc

@@ -1,3 +1,7 @@
+// A single page response from the '/v1/users' endpoint.
+//
+// This file is typically used in conjunction with v1/users?page_number=2&page_size=500.jsonc
+
 {
     "results": [
         {
@@ -29,4 +33,4 @@
     ],
     "current_page": 1,
     "total": 3
-}
+}

tests/posit/connect/__api__/v1/users?page_number=2&page_size=500.json → tests/posit/connect/__api__/v1/users?page_number=2&page_size=500.jsonc

@@ -1,3 +1,7 @@
+// A subsequent single page response from the '/v1/users' endpoint.
+//
+// This file is typically used in conjunction with v1/users?page_number=1&page_size=500.jsonc
+
 {
     "results": [
         {
@@ -16,4 +20,4 @@
     ],
     "current_page": 2,
     "total": 3
-}
+}

tests/posit/connect/api.py

@@ -1,10 +1,31 @@
-import json
+import pyjson5 as json
 
 from pathlib import Path
 
 
 def load_mock(path: str) -> dict:
     """
-    Read a JSON object from `path`
+    Load mock data from a file.
+
+    Reads a JSON or JSONC (JSON with Comments) file and returns the parsed data.
+
+    It's primarily used for loading mock data for tests.
+
+    The file names for mock data should match the query path that they represent.
+
+    Parameters
+    ----------
+    path : str
+        The relative path to the JSONC file.
+
+    Returns
+    -------
+    dict
+        The parsed data from the JSONC file.
+
+    Examples
+    --------
+    >>> data = load_mock("v1/example.json")
+    >>> data = load_mock("v1/example.jsonc")
     """
     return json.loads((Path(__file__).parent / "__api__" / path).read_text())