fix(sdk): list_documents review followups

- Forward recursive value instead of hardcoding True (#3)
- Raise limit cap from 100 to 10000 to match server (#4)
- Accept folder_id='root'/'' in local mode (#6)
- Fix wire test to assert presence not identity (#6, #9)
- Delete restating comments (#15)

Addresses PR #522 review findings 2-7.

pageindex/client.py

@@ -1796,7 +1796,7 @@ class PageIndexClient:
         List documents with pagination, newest first.
 
         Args:
-            limit (int): Maximum documents to return (1-100).
+            limit (int): Maximum documents to return (1-10000).
             offset (int): Number of documents to skip.
             folder_id (str, optional): Cloud-only folder filter.
             recursive (bool): Include documents in ``folder_id``'s

pageindex/cloud_api.py

@@ -453,7 +453,7 @@ class CloudAPI:
         List all documents for the authenticated user with pagination.
 
         Args:
-            limit (int, optional): Maximum number of documents to return (1-100). Defaults to 50.
+            limit (int, optional): Maximum number of documents to return (1-10000). Defaults to 50.
             offset (int, optional): Number of documents to skip. Defaults to 0.
             folder_id (str, optional): Filter by folder (workspace) ID. If provided, only documents
                 in the specified folder are returned. Defaults to None (all documents).
@@ -467,8 +467,8 @@ class CloudAPI:
                 - limit (int): Applied limit
                 - offset (int): Applied offset
         """
-        if limit < 1 or limit > 100:
-            raise ValueError("limit must be between 1 and 100")
+        if limit < 1 or limit > 10000:
+            raise ValueError("limit must be between 1 and 10000")
         if offset < 0:
             raise ValueError("offset must be non-negative")
 
@@ -478,7 +478,7 @@ class CloudAPI:
         if name is not None:
             params["name"] = name
         if recursive:
-            params["recursive"] = True
+            params["recursive"] = recursive
 
         response = requests.get(
             f"{self.BASE_URL}/docs/",

pageindex/local_api.py

@@ -344,13 +344,13 @@ class LocalAPI:
         offset: int = 0,
         folder_id: str | None = None,
         name: str | None = None,
-        recursive: bool = False,  # no folders here, nothing to descend into
+        recursive: bool = False,
     ) -> dict[str, Any]:
-        if limit < 1 or limit > 100:
-            raise ValueError("limit must be between 1 and 100")
+        if limit < 1 or limit > 10000:
+            raise ValueError("limit must be between 1 and 10000")
         if offset < 0:
             raise ValueError("offset must be non-negative")
-        if folder_id is not None:
+        if folder_id is not None and folder_id not in ("", "root"):
             raise PageIndexAPIError(
                 "Failed to list documents: folders are not supported in local mode."
             )

tests/test_client.py

@@ -958,7 +958,6 @@ def test_document_management(local_client, indexed_doc):
     assert listing["total"] == 1
     assert listing["limit"] == 50 and listing["offset"] == 0
     assert listing["documents"][0]["id"] == indexed_doc
-    # Same keys as a cloud listing; a local library has no folder to name.
     assert listing["documents"][0]["path"] is None
 
     assert local_client.is_retrieval_ready(indexed_doc) is True
@@ -1373,6 +1372,7 @@ def test_list_documents_validation(local_client):
     with pytest.raises(PageIndexAPIError, match="folders"):
         local_client.list_documents(folder_id="f1")
     assert local_client.list_documents(recursive=True)["total"] == 0
+    assert local_client.list_documents(folder_id="root")["total"] == 0
 
 
 def test_list_documents_recursive_wire(cloud):
@@ -1381,7 +1381,7 @@ def test_list_documents_recursive_wire(cloud):
     client.list_documents(folder_id="f1")
     assert "recursive" not in calls[-1]["params"]
     client.list_documents(folder_id="f1", recursive=True)
-    assert calls[-1]["params"]["recursive"] is True
+    assert "recursive" in calls[-1]["params"]
 
 
 def test_missing_document_errors(local_client):