feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 30
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-a73d280435ed6084d8ac9d9d7feb235de6141d866d40725ed26a27b87b0cf364.yml
-openapi_spec_hash: 91eabc37804d07ce801b1d4ea1778d1c
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-7d29d0843a52840291678a3c6d136f496ae1f956853abaa5003c1284ca2c94aa.yml
+openapi_spec_hash: 010597ad0ec6376fbf2f01ec062787ad
 config_hash: bd8505e17db740d82e578d0edaa9bfe0

README.md

@@ -200,6 +200,23 @@ query_result = client.memories.search(
 print(query_result.options)
 ```
 
+## 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)`.
+
+```python
+from pathlib import Path
+from hyperspell import Hyperspell
+
+client = Hyperspell()
+
+client.memories.upload(
+    file=Path("/path/to/file"),
+)
+```
+
+The async client uses the exact same interface. If you pass a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance, the file contents will be read asynchronously automatically.
+
 ## 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 `hyperspell.APIConnectionError` is raised.

src/hyperspell/_files.py

@@ -34,7 +34,7 @@ def assert_is_file_content(obj: object, *, key: str | None = None) -> None:
     if not is_file_content(obj):
         prefix = f"Expected entry at `{key}`" if key is not None else f"Expected file input `{obj!r}`"
         raise RuntimeError(
-            f"{prefix} to be bytes, an io.IOBase instance, PathLike or a tuple but received {type(obj)} instead."
+            f"{prefix} to be bytes, an io.IOBase instance, PathLike or a tuple but received {type(obj)} instead. See https://github.com/hyperspell/python-sdk/tree/main#file-uploads"
         ) from None
 
 

src/hyperspell/resources/memories.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict, List, Union, Iterable, Optional
+from typing import Dict, List, Union, Mapping, Iterable, Optional, cast
 from datetime import datetime
 from typing_extensions import Literal
 
@@ -16,8 +16,8 @@
     memory_upload_params,
     memory_add_bulk_params,
 )
-from .._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
-from .._utils import path_template, maybe_transform, async_maybe_transform
+from .._types import Body, Omit, Query, Headers, NotGiven, FileTypes, omit, not_given
+from .._utils import extract_files, path_template, maybe_transform, deepcopy_minimal, async_maybe_transform
 from .._compat import cached_property
 from .._resource import SyncAPIResource, AsyncAPIResource
 from .._response import (
@@ -549,7 +549,7 @@ def status(
     def upload(
         self,
         *,
-        file: str,
+        file: FileTypes,
         collection: Optional[str] | Omit = omit,
         metadata: Optional[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -583,20 +583,22 @@ def upload(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        body = deepcopy_minimal(
+            {
+                "file": file,
+                "collection": collection,
+                "metadata": metadata,
+            }
+        )
+        files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
         # It should be noted that the actual Content-Type header that will be
         # sent to the server will contain a `boundary` parameter, e.g.
         # multipart/form-data; boundary=---abc--
         extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
         return self._post(
             "/memories/upload",
-            body=maybe_transform(
-                {
-                    "file": file,
-                    "collection": collection,
-                    "metadata": metadata,
-                },
-                memory_upload_params.MemoryUploadParams,
-            ),
+            body=maybe_transform(body, memory_upload_params.MemoryUploadParams),
+            files=files,
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
@@ -1114,7 +1116,7 @@ async def status(
     async def upload(
         self,
         *,
-        file: str,
+        file: FileTypes,
         collection: Optional[str] | Omit = omit,
         metadata: Optional[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -1148,20 +1150,22 @@ async def upload(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        body = deepcopy_minimal(
+            {
+                "file": file,
+                "collection": collection,
+                "metadata": metadata,
+            }
+        )
+        files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
         # It should be noted that the actual Content-Type header that will be
         # sent to the server will contain a `boundary` parameter, e.g.
         # multipart/form-data; boundary=---abc--
         extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
         return await self._post(
             "/memories/upload",
-            body=await async_maybe_transform(
-                {
-                    "file": file,
-                    "collection": collection,
-                    "metadata": metadata,
-                },
-                memory_upload_params.MemoryUploadParams,
-            ),
+            body=await async_maybe_transform(body, memory_upload_params.MemoryUploadParams),
+            files=files,
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),

src/hyperspell/types/memory_upload_params.py

@@ -5,11 +5,13 @@
 from typing import Optional
 from typing_extensions import Required, TypedDict
 
+from .._types import FileTypes
+
 __all__ = ["MemoryUploadParams"]
 
 
 class MemoryUploadParams(TypedDict, total=False):
-    file: Required[str]
+    file: Required[FileTypes]
     """The file to ingest."""
 
     collection: Optional[str]

tests/api_resources/test_memories.py

@@ -388,14 +388,14 @@ def test_streaming_response_status(self, client: Hyperspell) -> None:
     @parametrize
     def test_method_upload(self, client: Hyperspell) -> None:
         memory = client.memories.upload(
-            file="file",
+            file=b"Example data",
         )
         assert_matches_type(MemoryStatus, memory, path=["response"])
 
     @parametrize
     def test_method_upload_with_all_params(self, client: Hyperspell) -> None:
         memory = client.memories.upload(
-            file="file",
+            file=b"Example data",
             collection="collection",
             metadata="metadata",
         )
@@ -404,7 +404,7 @@ def test_method_upload_with_all_params(self, client: Hyperspell) -> None:
     @parametrize
     def test_raw_response_upload(self, client: Hyperspell) -> None:
         response = client.memories.with_raw_response.upload(
-            file="file",
+            file=b"Example data",
         )
 
         assert response.is_closed is True
@@ -415,7 +415,7 @@ def test_raw_response_upload(self, client: Hyperspell) -> None:
     @parametrize
     def test_streaming_response_upload(self, client: Hyperspell) -> None:
         with client.memories.with_streaming_response.upload(
-            file="file",
+            file=b"Example data",
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -793,14 +793,14 @@ async def test_streaming_response_status(self, async_client: AsyncHyperspell) ->
     @parametrize
     async def test_method_upload(self, async_client: AsyncHyperspell) -> None:
         memory = await async_client.memories.upload(
-            file="file",
+            file=b"Example data",
         )
         assert_matches_type(MemoryStatus, memory, path=["response"])
 
     @parametrize
     async def test_method_upload_with_all_params(self, async_client: AsyncHyperspell) -> None:
         memory = await async_client.memories.upload(
-            file="file",
+            file=b"Example data",
             collection="collection",
             metadata="metadata",
         )
@@ -809,7 +809,7 @@ async def test_method_upload_with_all_params(self, async_client: AsyncHyperspell
     @parametrize
     async def test_raw_response_upload(self, async_client: AsyncHyperspell) -> None:
         response = await async_client.memories.with_raw_response.upload(
-            file="file",
+            file=b"Example data",
         )
 
         assert response.is_closed is True
@@ -820,7 +820,7 @@ async def test_raw_response_upload(self, async_client: AsyncHyperspell) -> None:
     @parametrize
     async def test_streaming_response_upload(self, async_client: AsyncHyperspell) -> None:
         async with async_client.memories.with_streaming_response.upload(
-            file="file",
+            file=b"Example data",
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"