Merge branch 'main' into feature/default-parameter-values

Author: ncoghlan

src/lmstudio/history.py

@@ -25,6 +25,8 @@
 from typing_extensions import (
     # Native in 3.11+
     Self,
+    # Native in Python 3.12+
+    Buffer,
     # Native in 3.13+
     TypeIs,
 )
@@ -76,6 +78,7 @@
     "FileHandleDict",
     "FileHandleInput",
     "FileType",
+    "LocalFileInput",
     "SystemPrompt",
     "SystemPromptContent",
     "ToolCallRequest",
@@ -529,17 +532,24 @@ def add_tool_result(self, result: ToolCallResultInput) -> ToolResultMessage:
         return message
 
 
-LocalFileInput = BinaryIO | bytes | str | os.PathLike[str]
+LocalFileInput = BinaryIO | Buffer | str | os.PathLike[str]
 
 
 # Private until file handle caching support is part of the published SDK API
 
 
-def _get_file_details(src: LocalFileInput) -> Tuple[str, bytes]:
+def _get_file_details(src: LocalFileInput) -> Tuple[str, Buffer]:
     """Read file contents as binary data and generate a suitable default name."""
-    if isinstance(src, bytes):
-        # We process bytes as raw data, not a bytes filesystem path
-        data = src
+    data: Buffer
+    if isinstance(src, Buffer):
+        if isinstance(src, memoryview):
+            # If already a memoryview, just use it directly
+            data = src
+        else:
+            # Try to create a memoryview - this will work for any buffer protocol object
+            # including bytes, bytearray, array.array, numpy arrays, etc.
+            data = memoryview(src)
+        # Received raw file data without any name information
         name = str(uuid.uuid4())
     elif hasattr(src, "read"):
         try:
@@ -550,10 +560,13 @@ def _get_file_details(src: LocalFileInput) -> Tuple[str, bytes]:
             raise LMStudioOSError(err_msg) from None
         name = getattr(src, "name", str(uuid.uuid4()))
     else:
+        # At this point, src must be a path-like object
         try:
             src_path = Path(src)
         except Exception as exc:
-            err_msg = f"Expected file-like object, filesystem path, or bytes ({exc!r})"
+            err_msg = (
+                f"Expected file-like object, filesystem path, or data buffer ({exc!r})"
+            )
             raise LMStudioValueError(err_msg) from None
         try:
             data = src_path.read_bytes()
@@ -573,7 +586,7 @@ class _LocalFileData:
     """Local file data to be added to a chat history."""
 
     name: str
-    raw_data: bytes
+    raw_data: Buffer
 
     def __init__(self, src: LocalFileInput, name: str | None = None) -> None:
         default_name, raw_data = _get_file_details(src)

tests/async/test_images_async.py

@@ -7,7 +7,7 @@
 
 from io import BytesIO
 
-from lmstudio import AsyncClient, Chat, FileHandle, LMStudioServerError
+from lmstudio import AsyncClient, Chat, FileHandle, LMStudioServerError, LocalFileInput
 
 from ..support import (
     EXPECTED_VLM_ID,
@@ -17,59 +17,57 @@
     check_sdk_error,
 )
 
+_IMAGE_DATA = IMAGE_FILEPATH.read_bytes()
+
+_FILE_INPUT_CASES: list[tuple[str, LocalFileInput]] = [
+    ("filesystem path", IMAGE_FILEPATH),
+    ("bytes IO stream", BytesIO(_IMAGE_DATA)),
+    ("raw bytes", _IMAGE_DATA),
+    ("mutable buffer", bytearray(_IMAGE_DATA)),
+    ("memoryview", memoryview(_IMAGE_DATA)),
+]
+_FILE_INPUT_CASE_IDS = [case[0] for case in _FILE_INPUT_CASES]
+
 
 @pytest.mark.asyncio
 @pytest.mark.lmstudio
-async def test_upload_from_pathlike_async(caplog: LogCap) -> None:
+@pytest.mark.parametrize(
+    "input_kind,file_input", _FILE_INPUT_CASES, ids=_FILE_INPUT_CASE_IDS
+)
+async def test_prepare_async(
+    caplog: LogCap, input_kind: str, file_input: LocalFileInput
+) -> None:
     caplog.set_level(logging.DEBUG)
     async with AsyncClient() as client:
         session = client.files
-        file = await session._prepare_file(IMAGE_FILEPATH)
+        file = await session._prepare_file(file_input)
         assert file
         assert isinstance(file, FileHandle)
-        logging.info(f"Uploaded file: {file}")
-        image = await session.prepare_image(IMAGE_FILEPATH)
+        logging.info(f"Uploaded file from {input_kind}: {file}")
+        image = await session.prepare_image(file_input)
         assert image
         assert isinstance(image, FileHandle)
-        logging.info(f"Uploaded image: {image}")
+        logging.info(f"Uploaded image from {input_kind}: {image}")
         # Even with the same data uploaded, assigned identifiers should differ
         assert image != file
 
 
 @pytest.mark.asyncio
 @pytest.mark.lmstudio
-async def test_upload_from_file_obj_async(caplog: LogCap) -> None:
+async def test_prepare_from_file_obj_async(caplog: LogCap) -> None:
     caplog.set_level(logging.DEBUG)
     async with AsyncClient() as client:
         session = client.files
         with open(IMAGE_FILEPATH, "rb") as f:
             file = await session._prepare_file(f)
         assert file
         assert isinstance(file, FileHandle)
-        logging.info(f"Uploaded file: {file}")
+        logging.info(f"Uploaded file from file object: {file}")
         with open(IMAGE_FILEPATH, "rb") as f:
             image = await session.prepare_image(f)
         assert image
         assert isinstance(image, FileHandle)
-        logging.info(f"Uploaded image: {image}")
-        # Even with the same data uploaded, assigned identifiers should differ
-        assert image != file
-
-
-@pytest.mark.asyncio
-@pytest.mark.lmstudio
-async def test_upload_from_bytesio_async(caplog: LogCap) -> None:
-    caplog.set_level(logging.DEBUG)
-    async with AsyncClient() as client:
-        session = client.files
-        file = await session._prepare_file(BytesIO(IMAGE_FILEPATH.read_bytes()))
-        assert file
-        assert isinstance(file, FileHandle)
-        logging.info(f"Uploaded file: {file}")
-        image = await session.prepare_image(BytesIO(IMAGE_FILEPATH.read_bytes()))
-        assert image
-        assert isinstance(image, FileHandle)
-        logging.info(f"Uploaded image: {image}")
+        logging.info(f"Uploaded image from file object: {image}")
         # Even with the same data uploaded, assigned identifiers should differ
         assert image != file
 

tests/sync/test_images_sync.py

@@ -14,7 +14,7 @@
 
 from io import BytesIO
 
-from lmstudio import Client, Chat, FileHandle, LMStudioServerError
+from lmstudio import Client, Chat, FileHandle, LMStudioServerError, LocalFileInput
 
 from ..support import (
     EXPECTED_VLM_ID,
@@ -24,56 +24,55 @@
     check_sdk_error,
 )
 
+_IMAGE_DATA = IMAGE_FILEPATH.read_bytes()
+
+_FILE_INPUT_CASES: list[tuple[str, LocalFileInput]] = [
+    ("filesystem path", IMAGE_FILEPATH),
+    ("bytes IO stream", BytesIO(_IMAGE_DATA)),
+    ("raw bytes", _IMAGE_DATA),
+    ("mutable buffer", bytearray(_IMAGE_DATA)),
+    ("memoryview", memoryview(_IMAGE_DATA)),
+]
+_FILE_INPUT_CASE_IDS = [case[0] for case in _FILE_INPUT_CASES]
+
 
 @pytest.mark.lmstudio
-def test_upload_from_pathlike_sync(caplog: LogCap) -> None:
+@pytest.mark.parametrize(
+    "input_kind,file_input", _FILE_INPUT_CASES, ids=_FILE_INPUT_CASE_IDS
+)
+def test_prepare_sync(
+    caplog: LogCap, input_kind: str, file_input: LocalFileInput
+) -> None:
     caplog.set_level(logging.DEBUG)
     with Client() as client:
         session = client.files
-        file = session._prepare_file(IMAGE_FILEPATH)
+        file = session._prepare_file(file_input)
         assert file
         assert isinstance(file, FileHandle)
-        logging.info(f"Uploaded file: {file}")
-        image = session.prepare_image(IMAGE_FILEPATH)
+        logging.info(f"Uploaded file from {input_kind}: {file}")
+        image = session.prepare_image(file_input)
         assert image
         assert isinstance(image, FileHandle)
-        logging.info(f"Uploaded image: {image}")
+        logging.info(f"Uploaded image from {input_kind}: {image}")
         # Even with the same data uploaded, assigned identifiers should differ
         assert image != file
 
 
 @pytest.mark.lmstudio
-def test_upload_from_file_obj_sync(caplog: LogCap) -> None:
+def test_prepare_from_file_obj_sync(caplog: LogCap) -> None:
     caplog.set_level(logging.DEBUG)
     with Client() as client:
         session = client.files
         with open(IMAGE_FILEPATH, "rb") as f:
             file = session._prepare_file(f)
         assert file
         assert isinstance(file, FileHandle)
-        logging.info(f"Uploaded file: {file}")
+        logging.info(f"Uploaded file from file object: {file}")
         with open(IMAGE_FILEPATH, "rb") as f:
             image = session.prepare_image(f)
         assert image
         assert isinstance(image, FileHandle)
-        logging.info(f"Uploaded image: {image}")
-        # Even with the same data uploaded, assigned identifiers should differ
-        assert image != file
-
-
-@pytest.mark.lmstudio
-def test_upload_from_bytesio_sync(caplog: LogCap) -> None:
-    caplog.set_level(logging.DEBUG)
-    with Client() as client:
-        session = client.files
-        file = session._prepare_file(BytesIO(IMAGE_FILEPATH.read_bytes()))
-        assert file
-        assert isinstance(file, FileHandle)
-        logging.info(f"Uploaded file: {file}")
-        image = session.prepare_image(BytesIO(IMAGE_FILEPATH.read_bytes()))
-        assert image
-        assert isinstance(image, FileHandle)
-        logging.info(f"Uploaded image: {image}")
+        logging.info(f"Uploaded image from file object: {image}")
         # Even with the same data uploaded, assigned identifiers should differ
         assert image != file