feat(api): update via SDK Studio

plastic-labs · May 8, 2024 · c9fc257 · c9fc257
1 parent c4ebb87
commit c9fc257
Show file tree

Hide file tree

Showing 21 changed files with 224 additions and 136 deletions.
diff --git a/.stats.yml b/.stats.yml
@@ -1,2 +1,2 @@
 configured_endpoints: 38
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/plastic-labs%2Fhoncho-aa0ddbaa748c2a59a8279ade9ad015339507bfdb93556b0375af93caa87d5f91.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/plastic-labs%2Fhoncho-07e26700dbaad7ad4aa984bd22f3197f07b7d3dff9a68533c57d3f1244704218.yml
diff --git a/README.md b/README.md
@@ -86,6 +86,77 @@ Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typ
 
 Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
 
+## Pagination
+
+List methods in the Honcho API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```python
+import honcho
+
+client = Honcho()
+
+all_users = []
+# Automatically fetches more pages as needed.
+for user in client.apps.users.list(
+    "REPLACE_ME",
+):
+    # Do something with user here
+    all_users.append(user)
+print(all_users)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+import honcho
+
+client = AsyncHoncho()
+
+
+async def main() -> None:
+    all_users = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for user in client.apps.users.list(
+        "REPLACE_ME",
+    ):
+        all_users.append(user)
+    print(all_users)
+
+
+asyncio.run(main())
+```
+
+Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages:
+
+```python
+first_page = await client.apps.users.list(
+    "REPLACE_ME",
+)
+if first_page.has_next_page():
+    print(f"will fetch next page using these details: {first_page.next_page_info()}")
+    next_page = await first_page.get_next_page()
+    print(f"number of items we just fetched: {len(next_page.items)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await client.apps.users.list(
+    "REPLACE_ME",
+)
+
+print(f"page number: {first_page.page}")  # => "page number: 1"
+for user in first_page.items:
+    print(user.id)
+
+# Remove `await` for non-async usage.
+```
+
 ## Handling errors
 
 When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `honcho.APIConnectionError` is raised.

diff --git a/api.md b/api.md
@@ -26,7 +26,7 @@ Methods:
 
 - <code title="post /apps/{app_id}/users">client.apps.users.<a href="./src/honcho/resources/apps/users/users.py">create</a>(app_id, \*\*<a href="src/honcho/types/apps/user_create_params.py">params</a>) -> <a href="./src/honcho/types/apps/user.py">User</a></code>
 - <code title="put /apps/{app_id}/users/{user_id}">client.apps.users.<a href="./src/honcho/resources/apps/users/users.py">update</a>(user_id, \*, app_id, \*\*<a href="src/honcho/types/apps/user_update_params.py">params</a>) -> <a href="./src/honcho/types/apps/user.py">User</a></code>
-- <code title="get /apps/{app_id}/users">client.apps.users.<a href="./src/honcho/resources/apps/users/users.py">list</a>(app_id, \*\*<a href="src/honcho/types/apps/user_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/page_user.py">PageUser</a></code>
+- <code title="get /apps/{app_id}/users">client.apps.users.<a href="./src/honcho/resources/apps/users/users.py">list</a>(app_id, \*\*<a href="src/honcho/types/apps/user_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/user.py">SyncPage[User]</a></code>
 - <code title="get /apps/{app_id}/users/{user_id}">client.apps.users.<a href="./src/honcho/resources/apps/users/users.py">get</a>(user_id, \*, app_id) -> <a href="./src/honcho/types/apps/user.py">User</a></code>
 - <code title="get /apps/{app_id}/users/name/{name}">client.apps.users.<a href="./src/honcho/resources/apps/users/users.py">get_by_name</a>(name, \*, app_id) -> <a href="./src/honcho/types/apps/user.py">User</a></code>
 - <code title="get /apps/{app_id}/users/get_or_create/{name}">client.apps.users.<a href="./src/honcho/resources/apps/users/users.py">get_or_create</a>(name, \*, app_id) -> <a href="./src/honcho/types/apps/user.py">User</a></code>
@@ -49,7 +49,7 @@ Methods:
 
 - <code title="post /apps/{app_id}/users/{user_id}/sessions">client.apps.users.sessions.<a href="./src/honcho/resources/apps/users/sessions/sessions.py">create</a>(user_id, \*, app_id, \*\*<a href="src/honcho/types/apps/users/session_create_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/session.py">Session</a></code>
 - <code title="put /apps/{app_id}/users/{user_id}/sessions/{session_id}">client.apps.users.sessions.<a href="./src/honcho/resources/apps/users/sessions/sessions.py">update</a>(session_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/session_update_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/session.py">Session</a></code>
-- <code title="get /apps/{app_id}/users/{user_id}/sessions">client.apps.users.sessions.<a href="./src/honcho/resources/apps/users/sessions/sessions.py">list</a>(user_id, \*, app_id, \*\*<a href="src/honcho/types/apps/users/session_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/page_session.py">PageSession</a></code>
+- <code title="get /apps/{app_id}/users/{user_id}/sessions">client.apps.users.sessions.<a href="./src/honcho/resources/apps/users/sessions/sessions.py">list</a>(user_id, \*, app_id, \*\*<a href="src/honcho/types/apps/users/session_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/session.py">SyncPage[Session]</a></code>
 - <code title="delete /apps/{app_id}/users/{user_id}/sessions/{session_id}">client.apps.users.sessions.<a href="./src/honcho/resources/apps/users/sessions/sessions.py">delete</a>(session_id, \*, app_id, user_id) -> <a href="./src/honcho/types/apps/users/session_delete_response.py">object</a></code>
 - <code title="get /apps/{app_id}/users/{user_id}/sessions/{session_id}/chat">client.apps.users.sessions.<a href="./src/honcho/resources/apps/users/sessions/sessions.py">chat</a>(session_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/session_chat_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/agent_chat.py">AgentChat</a></code>
 - <code title="get /apps/{app_id}/users/{user_id}/sessions/{session_id}">client.apps.users.sessions.<a href="./src/honcho/resources/apps/users/sessions/sessions.py">get</a>(session_id, \*, app_id, user_id) -> <a href="./src/honcho/types/apps/users/session.py">Session</a></code>
@@ -67,7 +67,7 @@ Methods:
 
 - <code title="post /apps/{app_id}/users/{user_id}/sessions/{session_id}/messages">client.apps.users.sessions.messages.<a href="./src/honcho/resources/apps/users/sessions/messages.py">create</a>(session_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/sessions/message_create_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/message.py">Message</a></code>
 - <code title="put /apps/{app_id}/users/{user_id}/sessions/{session_id}/messages/{message_id}">client.apps.users.sessions.messages.<a href="./src/honcho/resources/apps/users/sessions/messages.py">update</a>(message_id, \*, app_id, user_id, session_id, \*\*<a href="src/honcho/types/apps/users/sessions/message_update_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/message.py">Message</a></code>
-- <code title="get /apps/{app_id}/users/{user_id}/sessions/{session_id}/messages">client.apps.users.sessions.messages.<a href="./src/honcho/resources/apps/users/sessions/messages.py">list</a>(session_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/sessions/message_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/page_message.py">PageMessage</a></code>
+- <code title="get /apps/{app_id}/users/{user_id}/sessions/{session_id}/messages">client.apps.users.sessions.messages.<a href="./src/honcho/resources/apps/users/sessions/messages.py">list</a>(session_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/sessions/message_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/message.py">SyncPage[Message]</a></code>
 - <code title="get /apps/{app_id}/users/{user_id}/sessions/{session_id}/messages/{message_id}">client.apps.users.sessions.messages.<a href="./src/honcho/resources/apps/users/sessions/messages.py">get</a>(message_id, \*, app_id, user_id, session_id) -> <a href="./src/honcho/types/apps/users/sessions/message.py">Message</a></code>
 
 #### Metamessages
@@ -82,7 +82,7 @@ Methods:
 
 - <code title="post /apps/{app_id}/users/{user_id}/sessions/{session_id}/metamessages">client.apps.users.sessions.metamessages.<a href="./src/honcho/resources/apps/users/sessions/metamessages.py">create</a>(session_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/sessions/metamessage_create_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/metamessage.py">Metamessage</a></code>
 - <code title="put /apps/{app_id}/users/{user_id}/sessions/{session_id}/metamessages/{metamessage_id}">client.apps.users.sessions.metamessages.<a href="./src/honcho/resources/apps/users/sessions/metamessages.py">update</a>(metamessage_id, \*, app_id, user_id, session_id, \*\*<a href="src/honcho/types/apps/users/sessions/metamessage_update_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/metamessage.py">Metamessage</a></code>
-- <code title="get /apps/{app_id}/users/{user_id}/sessions/{session_id}/metamessages">client.apps.users.sessions.metamessages.<a href="./src/honcho/resources/apps/users/sessions/metamessages.py">list</a>(session_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/sessions/metamessage_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/page_metamessage.py">PageMetamessage</a></code>
+- <code title="get /apps/{app_id}/users/{user_id}/sessions/{session_id}/metamessages">client.apps.users.sessions.metamessages.<a href="./src/honcho/resources/apps/users/sessions/metamessages.py">list</a>(session_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/sessions/metamessage_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/metamessage.py">SyncPage[Metamessage]</a></code>
 - <code title="get /apps/{app_id}/users/{user_id}/sessions/{session_id}/metamessages/{metamessage_id}">client.apps.users.sessions.metamessages.<a href="./src/honcho/resources/apps/users/sessions/metamessages.py">get</a>(metamessage_id, \*, app_id, user_id, session_id, \*\*<a href="src/honcho/types/apps/users/sessions/metamessage_get_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/sessions/metamessage.py">Metamessage</a></code>
 
 ### Collections
@@ -102,7 +102,7 @@ Methods:
 
 - <code title="post /apps/{app_id}/users/{user_id}/collections">client.apps.users.collections.<a href="./src/honcho/resources/apps/users/collections/collections.py">create</a>(user_id, \*, app_id, \*\*<a href="src/honcho/types/apps/users/collection_create_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/collection.py">Collection</a></code>
 - <code title="put /apps/{app_id}/users/{user_id}/collections/{collection_id}">client.apps.users.collections.<a href="./src/honcho/resources/apps/users/collections/collections.py">update</a>(collection_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/collection_update_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/collection.py">Collection</a></code>
-- <code title="get /apps/{app_id}/users/{user_id}/collections">client.apps.users.collections.<a href="./src/honcho/resources/apps/users/collections/collections.py">list</a>(user_id, \*, app_id, \*\*<a href="src/honcho/types/apps/users/collection_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/page_collection.py">PageCollection</a></code>
+- <code title="get /apps/{app_id}/users/{user_id}/collections">client.apps.users.collections.<a href="./src/honcho/resources/apps/users/collections/collections.py">list</a>(user_id, \*, app_id, \*\*<a href="src/honcho/types/apps/users/collection_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/collection.py">SyncPage[Collection]</a></code>
 - <code title="delete /apps/{app_id}/users/{user_id}/collections/{collection_id}">client.apps.users.collections.<a href="./src/honcho/resources/apps/users/collections/collections.py">delete</a>(collection_id, \*, app_id, user_id) -> <a href="./src/honcho/types/apps/users/collection_delete_response.py">object</a></code>
 - <code title="get /apps/{app_id}/users/{user_id}/collections/{collection_id}">client.apps.users.collections.<a href="./src/honcho/resources/apps/users/collections/collections.py">get</a>(collection_id, \*, app_id, user_id) -> <a href="./src/honcho/types/apps/users/collection.py">Collection</a></code>
 - <code title="get /apps/{app_id}/users/{user_id}/collections/name/{name}">client.apps.users.collections.<a href="./src/honcho/resources/apps/users/collections/collections.py">get_by_name</a>(name, \*, app_id, user_id) -> <a href="./src/honcho/types/apps/users/collection.py">Collection</a></code>
@@ -120,6 +120,6 @@ Methods:
 
 - <code title="post /apps/{app_id}/users/{user_id}/collections/{collection_id}/documents">client.apps.users.collections.documents.<a href="./src/honcho/resources/apps/users/collections/documents.py">create</a>(collection_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/collections/document_create_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/collections/document.py">Document</a></code>
 - <code title="put /apps/{app_id}/users/{user_id}/collections/{collection_id}/documents/{document_id}">client.apps.users.collections.documents.<a href="./src/honcho/resources/apps/users/collections/documents.py">update</a>(document_id, \*, app_id, user_id, collection_id, \*\*<a href="src/honcho/types/apps/users/collections/document_update_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/collections/document.py">Document</a></code>
-- <code title="get /apps/{app_id}/users/{user_id}/collections/{collection_id}/documents">client.apps.users.collections.documents.<a href="./src/honcho/resources/apps/users/collections/documents.py">list</a>(collection_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/collections/document_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/collections/page_document.py">PageDocument</a></code>
+- <code title="get /apps/{app_id}/users/{user_id}/collections/{collection_id}/documents">client.apps.users.collections.documents.<a href="./src/honcho/resources/apps/users/collections/documents.py">list</a>(collection_id, \*, app_id, user_id, \*\*<a href="src/honcho/types/apps/users/collections/document_list_params.py">params</a>) -> <a href="./src/honcho/types/apps/users/collections/document.py">SyncPage[Document]</a></code>
 - <code title="delete /apps/{app_id}/users/{user_id}/collections/{collection_id}/documents/{document_id}">client.apps.users.collections.documents.<a href="./src/honcho/resources/apps/users/collections/documents.py">delete</a>(document_id, \*, app_id, user_id, collection_id) -> <a href="./src/honcho/types/apps/users/collections/document_delete_response.py">object</a></code>
 - <code title="get /apps/{app_id}/users/{user_id}/collections/{collection_id}/documents/{document_id}">client.apps.users.collections.documents.<a href="./src/honcho/resources/apps/users/collections/documents.py">get</a>(document_id, \*, app_id, user_id, collection_id) -> <a href="./src/honcho/types/apps/users/collections/document.py">Document</a></code>
diff --git a/src/honcho/resources/apps/users/collections/collections.py b/src/honcho/resources/apps/users/collections/collections.py
@@ -27,7 +27,9 @@
     async_to_raw_response_wrapper,
     async_to_streamed_response_wrapper,
 )
+from .....pagination import SyncPage, AsyncPage
 from ....._base_client import (
+    AsyncPaginator,
     make_request_options,
 )
 from .....types.apps.users import (
@@ -37,7 +39,6 @@
     collection_update_params,
 )
 from .....types.apps.users.collection import Collection
-from .....types.apps.users.page_collection import PageCollection
 from .....types.apps.users.collection_query_response import CollectionQueryResponse
 
 __all__ = ["CollectionsResource", "AsyncCollectionsResource"]
@@ -164,7 +165,7 @@ def list(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    ) -> PageCollection:
+    ) -> SyncPage[Collection]:
         """
         Get All Collections for a User
 
@@ -191,8 +192,9 @@ def list(
             raise ValueError(f"Expected a non-empty value for `app_id` but received {app_id!r}")
         if not user_id:
             raise ValueError(f"Expected a non-empty value for `user_id` but received {user_id!r}")
-        return self._get(
+        return self._get_api_list(
             f"/apps/{app_id}/users/{user_id}/collections",
+            page=SyncPage[Collection],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -208,7 +210,7 @@ def list(
                     collection_list_params.CollectionListParams,
                 ),
             ),
-            cast_to=PageCollection,
+            model=Collection,
         )
 
     def delete(
@@ -488,7 +490,7 @@ async def update(
             cast_to=Collection,
         )
 
-    async def list(
+    def list(
         self,
         user_id: str,
         *,
@@ -503,7 +505,7 @@ async def list(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    ) -> PageCollection:
+    ) -> AsyncPaginator[Collection, AsyncPage[Collection]]:
         """
         Get All Collections for a User
 
@@ -530,14 +532,15 @@ async def list(
             raise ValueError(f"Expected a non-empty value for `app_id` but received {app_id!r}")
         if not user_id:
             raise ValueError(f"Expected a non-empty value for `user_id` but received {user_id!r}")
-        return await self._get(
+        return self._get_api_list(
             f"/apps/{app_id}/users/{user_id}/collections",
+            page=AsyncPage[Collection],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
                 extra_body=extra_body,
                 timeout=timeout,
-                query=await async_maybe_transform(
+                query=maybe_transform(
                     {
                         "filter": filter,
                         "page": page,
@@ -547,7 +550,7 @@ async def list(
                     collection_list_params.CollectionListParams,
                 ),
             ),
-            cast_to=PageCollection,
+            model=Collection,
         )
 
     async def delete(