feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 2
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/nanonets%2Fdocstrange-4a17ecf235fd346afe631381db80e46b26346368a323939de7b0741a5b60ce3d.yml
-openapi_spec_hash: c46bca368a4f85e1a684b309e4129ef5
-config_hash: 6f0ab1fd6c4433590ee82d88ab5298a7
+configured_endpoints: 9
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/nanonets%2Fdocstrange-61ca0326580cb90b4bc39c85c49cb2083d14ce9865ea272f2cb84cc7c639b0b2.yml
+openapi_spec_hash: 6940490040b26eeb3c38bb2d7d9f00ce
+config_hash: aed0d6cc8b4cffa1f02021baec0a6da3

README.md

@@ -115,6 +115,67 @@ 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 Docstrange API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```python
+from docstrange import Docstrange
+
+client = Docstrange()
+
+all_results = []
+# Automatically fetches more pages as needed.
+for result in client.extract.results.list():
+    # Do something with result here
+    all_results.append(result)
+print(all_results)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+from docstrange import AsyncDocstrange
+
+client = AsyncDocstrange()
+
+
+async def main() -> None:
+    all_results = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for result in client.extract.results.list():
+        all_results.append(result)
+    print(all_results)
+
+
+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.extract.results.list()
+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.results)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await client.extract.results.list()
+for result in first_page.results:
+    print(result)
+
+# Remove `await` for non-async usage.
+```
+
 ## File uploads
 
 Request parameters that correspond to file uploads can be passed as `bytes`, or a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance or a tuple of `(filename, contents, media type)`.

api.md

@@ -3,21 +3,62 @@
 Types:
 
 ```python
-from docstrange.types import ExtractResponse
+from docstrange.types import (
+    BatchExtractRequestBody,
+    BatchExtractResponse,
+    ExtractRequestBody,
+    ExtractResponse,
+    StreamExtractRequestBody,
+    ExtractStreamResponse,
+)
 ```
 
 Methods:
 
-- <code title="post /api/v1/extract/sync">client.extract.<a href="./src/docstrange/resources/extract.py">sync</a>(\*\*<a href="src/docstrange/types/extract_sync_params.py">params</a>) -> <a href="./src/docstrange/types/extract_response.py">ExtractResponse</a></code>
+- <code title="post /api/v1/extract/async">client.extract.<a href="./src/docstrange/resources/extract/extract.py">async\_</a>(\*\*<a href="src/docstrange/types/extract_async_params.py">params</a>) -> <a href="./src/docstrange/types/extract_response.py">ExtractResponse</a></code>
+- <code title="post /api/v1/extract/batch">client.extract.<a href="./src/docstrange/resources/extract/extract.py">batch</a>(\*\*<a href="src/docstrange/types/extract_batch_params.py">params</a>) -> <a href="./src/docstrange/types/batch_extract_response.py">BatchExtractResponse</a></code>
+- <code title="post /api/v1/extract/stream">client.extract.<a href="./src/docstrange/resources/extract/extract.py">stream</a>(\*\*<a href="src/docstrange/types/extract_stream_params.py">params</a>) -> str</code>
+- <code title="post /api/v1/extract/sync">client.extract.<a href="./src/docstrange/resources/extract/extract.py">sync</a>(\*\*<a href="src/docstrange/types/extract_sync_params.py">params</a>) -> <a href="./src/docstrange/types/extract_response.py">ExtractResponse</a></code>
+
+## Results
+
+Types:
+
+```python
+from docstrange.types.extract import ExtractionListResponse
+```
+
+Methods:
+
+- <code title="get /api/v1/extract/results/{record_id}">client.extract.results.<a href="./src/docstrange/resources/extract/results.py">retrieve</a>(record_id, \*\*<a href="src/docstrange/types/extract/result_retrieve_params.py">params</a>) -> <a href="./src/docstrange/types/extract_response.py">ExtractResponse</a></code>
+- <code title="get /api/v1/extract/results">client.extract.results.<a href="./src/docstrange/resources/extract/results.py">list</a>(\*\*<a href="src/docstrange/types/extract/result_list_params.py">params</a>) -> SyncPageNumberPagination[object]</code>
 
 # Classify
 
 Types:
 
 ```python
-from docstrange.types import ClassifyResponse
+from docstrange.types import (
+    BatchClassifyRequestBody,
+    BatchClassifyResponse,
+    ClassifyRequestBody,
+    ClassifyResponse,
+)
 ```
 
 Methods:
 
+- <code title="post /api/v1/classify/batch">client.classify.<a href="./src/docstrange/resources/classify.py">batch</a>(\*\*<a href="src/docstrange/types/classify_batch_params.py">params</a>) -> <a href="./src/docstrange/types/batch_classify_response.py">BatchClassifyResponse</a></code>
 - <code title="post /api/v1/classify/sync">client.classify.<a href="./src/docstrange/resources/classify.py">sync</a>(\*\*<a href="src/docstrange/types/classify_sync_params.py">params</a>) -> <a href="./src/docstrange/types/classify_response.py">ClassifyResponse</a></code>
+
+# Chat
+
+Types:
+
+```python
+from docstrange.types import ChatCompletionsRequest
+```
+
+Methods:
+
+- <code title="post /v1/chat/completions">client.chat.<a href="./src/docstrange/resources/chat.py">create_completion</a>(\*\*<a href="src/docstrange/types/chat_create_completion_params.py">params</a>) -> object</code>

src/docstrange/_client.py

@@ -31,9 +31,10 @@
 )
 
 if TYPE_CHECKING:
-    from .resources import extract, classify
-    from .resources.extract import ExtractResource, AsyncExtractResource
+    from .resources import chat, extract, classify
+    from .resources.chat import ChatResource, AsyncChatResource
     from .resources.classify import ClassifyResource, AsyncClassifyResource
+    from .resources.extract.extract import ExtractResource, AsyncExtractResource
 
 __all__ = [
     "Timeout",
@@ -114,6 +115,12 @@ def classify(self) -> ClassifyResource:
 
         return ClassifyResource(self)
 
+    @cached_property
+    def chat(self) -> ChatResource:
+        from .resources.chat import ChatResource
+
+        return ChatResource(self)
+
     @cached_property
     def with_raw_response(self) -> DocstrangeWithRawResponse:
         return DocstrangeWithRawResponse(self)
@@ -294,6 +301,12 @@ def classify(self) -> AsyncClassifyResource:
 
         return AsyncClassifyResource(self)
 
+    @cached_property
+    def chat(self) -> AsyncChatResource:
+        from .resources.chat import AsyncChatResource
+
+        return AsyncChatResource(self)
+
     @cached_property
     def with_raw_response(self) -> AsyncDocstrangeWithRawResponse:
         return AsyncDocstrangeWithRawResponse(self)
@@ -425,6 +438,12 @@ def classify(self) -> classify.ClassifyResourceWithRawResponse:
 
         return ClassifyResourceWithRawResponse(self._client.classify)
 
+    @cached_property
+    def chat(self) -> chat.ChatResourceWithRawResponse:
+        from .resources.chat import ChatResourceWithRawResponse
+
+        return ChatResourceWithRawResponse(self._client.chat)
+
 
 class AsyncDocstrangeWithRawResponse:
     _client: AsyncDocstrange
@@ -444,6 +463,12 @@ def classify(self) -> classify.AsyncClassifyResourceWithRawResponse:
 
         return AsyncClassifyResourceWithRawResponse(self._client.classify)
 
+    @cached_property
+    def chat(self) -> chat.AsyncChatResourceWithRawResponse:
+        from .resources.chat import AsyncChatResourceWithRawResponse
+
+        return AsyncChatResourceWithRawResponse(self._client.chat)
+
 
 class DocstrangeWithStreamedResponse:
     _client: Docstrange
@@ -463,6 +488,12 @@ def classify(self) -> classify.ClassifyResourceWithStreamingResponse:
 
         return ClassifyResourceWithStreamingResponse(self._client.classify)
 
+    @cached_property
+    def chat(self) -> chat.ChatResourceWithStreamingResponse:
+        from .resources.chat import ChatResourceWithStreamingResponse
+
+        return ChatResourceWithStreamingResponse(self._client.chat)
+
 
 class AsyncDocstrangeWithStreamedResponse:
     _client: AsyncDocstrange
@@ -482,6 +513,12 @@ def classify(self) -> classify.AsyncClassifyResourceWithStreamingResponse:
 
         return AsyncClassifyResourceWithStreamingResponse(self._client.classify)
 
+    @cached_property
+    def chat(self) -> chat.AsyncChatResourceWithStreamingResponse:
+        from .resources.chat import AsyncChatResourceWithStreamingResponse
+
+        return AsyncChatResourceWithStreamingResponse(self._client.chat)
+
 
 Client = Docstrange
 

src/docstrange/pagination.py

@@ -0,0 +1,67 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Generic, TypeVar, Optional, cast
+from typing_extensions import override
+
+from ._models import BaseModel
+from ._base_client import BasePage, PageInfo, BaseSyncPage, BaseAsyncPage
+
+__all__ = ["PageNumberPaginationPagination", "SyncPageNumberPagination", "AsyncPageNumberPagination"]
+
+_T = TypeVar("_T")
+
+
+class PageNumberPaginationPagination(BaseModel):
+    has_next: Optional[bool] = None
+
+    total_count: Optional[int] = None
+
+
+class SyncPageNumberPagination(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    results: List[_T]
+    pagination: Optional[PageNumberPaginationPagination] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        results = self.results
+        if not results:
+            return []
+        return results
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        last_page = cast("int | None", self._options.params.get("page")) or 1
+
+        total_pages = None
+        if self.pagination is not None:
+            if self.pagination.total_count is not None:
+                total_pages = self.pagination.total_count
+        if total_pages is not None and last_page >= total_pages:
+            return None
+
+        return PageInfo(params={"page": last_page + 1})
+
+
+class AsyncPageNumberPagination(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
+    results: List[_T]
+    pagination: Optional[PageNumberPaginationPagination] = None
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        results = self.results
+        if not results:
+            return []
+        return results
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        last_page = cast("int | None", self._options.params.get("page")) or 1
+
+        total_pages = None
+        if self.pagination is not None:
+            if self.pagination.total_count is not None:
+                total_pages = self.pagination.total_count
+        if total_pages is not None and last_page >= total_pages:
+            return None
+
+        return PageInfo(params={"page": last_page + 1})

src/docstrange/resources/__init__.py

@@ -1,5 +1,13 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+from .chat import (
+    ChatResource,
+    AsyncChatResource,
+    ChatResourceWithRawResponse,
+    AsyncChatResourceWithRawResponse,
+    ChatResourceWithStreamingResponse,
+    AsyncChatResourceWithStreamingResponse,
+)
 from .extract import (
     ExtractResource,
     AsyncExtractResource,
@@ -30,4 +38,10 @@
     "AsyncClassifyResourceWithRawResponse",
     "ClassifyResourceWithStreamingResponse",
     "AsyncClassifyResourceWithStreamingResponse",
+    "ChatResource",
+    "AsyncChatResource",
+    "ChatResourceWithRawResponse",
+    "AsyncChatResourceWithRawResponse",
+    "ChatResourceWithStreamingResponse",
+    "AsyncChatResourceWithStreamingResponse",
 ]