release: 5.5.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "5.4.0"
+  ".": "5.5.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 48
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-70c42eda2bee929830b2537f758400a58dded1f1ef5686a286e2469c35a041a0.yml
-openapi_spec_hash: cdaeed824e91657b45092765cf55eb42
-config_hash: e3c2679d25f6235381dfb11962fbf3d9
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc/imagekit-362d0336e8f52ab1beb7d9602a3665dbb0277700e8dc01ef4f96fc7651699349.yml
+openapi_spec_hash: f0d797a17b1e8e81707517700cd44b13
+config_hash: 94f48fd13b7d41b8b6a203a3a8cee9ed

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 5.5.0 (2026-05-11)
+
+Full Changelog: [v5.4.0...v5.5.0](https://github.com/imagekit-developer/imagekit-python/compare/v5.4.0...v5.5.0)
+
+### Features
+
+* **api:** manual updates ([965e263](https://github.com/imagekit-developer/imagekit-python/commit/965e26380c05a76c356fc994e0a92dc8efe3ac4e))
+* **internal/types:** support eagerly validating pydantic iterators ([35bcec1](https://github.com/imagekit-developer/imagekit-python/commit/35bcec134edcbbf356f5f93d5a1e719f69b458a3))
+* support setting headers via env ([39cbf90](https://github.com/imagekit-developer/imagekit-python/commit/39cbf90f16813f2ee8f477554ece14f804cc765d))
+
+
+### Bug Fixes
+
+* **client:** add missing f-string prefix in file type error message ([b3926a7](https://github.com/imagekit-developer/imagekit-python/commit/b3926a7b73d379cf56ce3985bc602254fda83f40))
+* use correct field name format for multipart file arrays ([c89d2b3](https://github.com/imagekit-developer/imagekit-python/commit/c89d2b36f2049df445ac5f365ed8dac2544d116b))
+
+
+### Performance Improvements
+
+* **client:** optimize file structure copying in multipart requests ([b22ab86](https://github.com/imagekit-developer/imagekit-python/commit/b22ab86e45de2bbc479942eaa27dd0c9b89cbc91))
+
+
+### Chores
+
+* configure new SDK language ([2b40f08](https://github.com/imagekit-developer/imagekit-python/commit/2b40f08e2757811dd14e29aed78f4f928fd97111))
+* **internal:** more robust bootstrap script ([e5703df](https://github.com/imagekit-developer/imagekit-python/commit/e5703dfdb61f9842a508947555544ad9910a225d))
+* **internal:** reformat pyproject.toml ([15a2ce1](https://github.com/imagekit-developer/imagekit-python/commit/15a2ce1f0293a0ab4d96792379e127f68f5cc64d))
+
 ## 5.4.0 (2026-04-13)
 
 Full Changelog: [v5.3.0...v5.4.0](https://github.com/imagekit-developer/imagekit-python/compare/v5.3.0...v5.4.0)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imagekitio"
-version = "5.4.0"
+version = "5.5.0"
 description = "The official Python library for the ImageKit API"
 dynamic = ["readme"]
 license = "Apache-2.0"
@@ -169,7 +169,7 @@ show_error_codes = true
 #
 # We also exclude our `tests` as mypy doesn't always infer
 # types correctly and Pyright will still catch any type errors.
-exclude = ['src/imagekitio/_files.py', '_dev/.*.py', 'tests/.*']
+exclude = ["src/imagekitio/_files.py", "_dev/.*.py", "tests/.*"]
 
 strict_equality = true
 implicit_reexport = true

scripts/bootstrap

@@ -4,7 +4,7 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ] && [ -t 0 ]; then
+if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "${SKIP_BREW:-}" != "1" ] && [ -t 0 ]; then
   brew bundle check >/dev/null 2>&1 || {
     echo -n "==> Install Homebrew dependencies? (y/N): "
     read -r response

src/imagekitio/_client.py

@@ -21,7 +21,11 @@
     RequestOptions,
     not_given,
 )
-from ._utils import is_given, get_async_library
+from ._utils import (
+    is_given,
+    is_mapping_t,
+    get_async_library,
+)
 from ._compat import cached_property
 from ._version import __version__
 from ._streaming import Stream as Stream, AsyncStream as AsyncStream
@@ -128,6 +132,15 @@ def __init__(
         if base_url is None:
             base_url = f"https://api.imagekit.io"
 
+        custom_headers_env = os.environ.get("IMAGE_KIT_CUSTOM_HEADERS")
+        if custom_headers_env is not None:
+            parsed: dict[str, str] = {}
+            for line in custom_headers_env.split("\n"):
+                colon = line.find(":")
+                if colon >= 0:
+                    parsed[line[:colon].strip()] = line[colon + 1 :].strip()
+            default_headers = {**parsed, **(default_headers if is_mapping_t(default_headers) else {})}
+
         super().__init__(
             version=__version__,
             base_url=base_url,
@@ -396,6 +409,15 @@ def __init__(
         if base_url is None:
             base_url = f"https://api.imagekit.io"
 
+        custom_headers_env = os.environ.get("IMAGE_KIT_CUSTOM_HEADERS")
+        if custom_headers_env is not None:
+            parsed: dict[str, str] = {}
+            for line in custom_headers_env.split("\n"):
+                colon = line.find(":")
+                if colon >= 0:
+                    parsed[line[:colon].strip()] = line[colon + 1 :].strip()
+            default_headers = {**parsed, **(default_headers if is_mapping_t(default_headers) else {})}
+
         super().__init__(
             version=__version__,
             base_url=base_url,

src/imagekitio/_files.py

@@ -3,8 +3,8 @@
 import io
 import os
 import pathlib
-from typing import overload
-from typing_extensions import TypeGuard
+from typing import Sequence, cast, overload
+from typing_extensions import TypeVar, TypeGuard
 
 import anyio
 
@@ -17,7 +17,9 @@
     HttpxFileContent,
     HttpxRequestFiles,
 )
-from ._utils import is_tuple_t, is_mapping_t, is_sequence_t
+from ._utils import is_list, is_mapping, is_tuple_t, is_mapping_t, is_sequence_t
+
+_T = TypeVar("_T")
 
 
 def is_base64_file_input(obj: object) -> TypeGuard[Base64FileInput]:
@@ -97,7 +99,7 @@ async def async_to_httpx_files(files: RequestFiles | None) -> HttpxRequestFiles
     elif is_sequence_t(files):
         files = [(key, await _async_transform_file(file)) for key, file in files]
     else:
-        raise TypeError("Unexpected file type input {type(files)}, expected mapping or sequence")
+        raise TypeError(f"Unexpected file type input {type(files)}, expected mapping or sequence")
 
     return files
 
@@ -121,3 +123,51 @@ async def async_read_file_content(file: FileContent) -> HttpxFileContent:
         return await anyio.Path(file).read_bytes()
 
     return file
+
+
+def deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]]) -> _T:
+    """Copy only the containers along the given paths.
+
+    Used to guard against mutation by extract_files without copying the entire structure.
+    Only dicts and lists that lie on a path are copied; everything else
+    is returned by reference.
+
+    For example, given paths=[["foo", "files", "file"]] and the structure:
+        {
+            "foo": {
+                "bar": {"baz": {}},
+                "files": {"file": <content>}
+            }
+        }
+    The root dict, "foo", and "files" are copied (they lie on the path).
+    "bar" and "baz" are returned by reference (off the path).
+    """
+    return _deepcopy_with_paths(item, paths, 0)
+
+
+def _deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]], index: int) -> _T:
+    if not paths:
+        return item
+    if is_mapping(item):
+        key_to_paths: dict[str, list[Sequence[str]]] = {}
+        for path in paths:
+            if index < len(path):
+                key_to_paths.setdefault(path[index], []).append(path)
+
+        # if no path continues through this mapping, it won't be mutated and copying it is redundant
+        if not key_to_paths:
+            return item
+
+        result = dict(item)
+        for key, subpaths in key_to_paths.items():
+            if key in result:
+                result[key] = _deepcopy_with_paths(result[key], subpaths, index + 1)
+        return cast(_T, result)
+    if is_list(item):
+        array_paths = [path for path in paths if index < len(path) and path[index] == "<array>"]
+
+        # if no path expects a list here, nothing will be mutated inside it - return by reference
+        if not array_paths:
+            return cast(_T, item)
+        return cast(_T, [_deepcopy_with_paths(entry, array_paths, index + 1) for entry in item])
+    return item

src/imagekitio/_models.py

@@ -25,7 +25,9 @@
     ClassVar,
     Protocol,
     Required,
+    Annotated,
     ParamSpec,
+    TypeAlias,
     TypedDict,
     TypeGuard,
     final,
@@ -79,7 +81,15 @@
 from ._constants import RAW_RESPONSE_HEADER
 
 if TYPE_CHECKING:
+    from pydantic import GetCoreSchemaHandler, ValidatorFunctionWrapHandler
+    from pydantic_core import CoreSchema, core_schema
     from pydantic_core.core_schema import ModelField, ModelSchema, LiteralSchema, ModelFieldsSchema
+else:
+    try:
+        from pydantic_core import CoreSchema, core_schema
+    except ImportError:
+        CoreSchema = None
+        core_schema = None
 
 __all__ = ["BaseModel", "GenericModel"]
 
@@ -396,6 +406,76 @@ def model_dump_json(
             )
 
 
+class _EagerIterable(list[_T], Generic[_T]):
+    """
+    Accepts any Iterable[T] input (including generators), consumes it
+    eagerly, and validates all items upfront.
+
+    Validation preserves the original container type where possible
+    (e.g. a set[T] stays a set[T]).  Serialization (model_dump / JSON)
+    always emits a list — round-tripping through model_dump() will not
+    restore the original container type.
+    """
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        source_type: Any,
+        handler: GetCoreSchemaHandler,
+    ) -> CoreSchema:
+        (item_type,) = get_args(source_type) or (Any,)
+        item_schema: CoreSchema = handler.generate_schema(item_type)
+        list_of_items_schema: CoreSchema = core_schema.list_schema(item_schema)
+
+        return core_schema.no_info_wrap_validator_function(
+            cls._validate,
+            list_of_items_schema,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                cls._serialize,
+                info_arg=False,
+            ),
+        )
+
+    @staticmethod
+    def _validate(v: Iterable[_T], handler: "ValidatorFunctionWrapHandler") -> Any:
+        original_type: type[Any] = type(v)
+
+        # Normalize to list so list_schema can validate each item
+        if isinstance(v, list):
+            items: list[_T] = v
+        else:
+            try:
+                items = list(v)
+            except TypeError as e:
+                raise TypeError("Value is not iterable") from e
+
+        # Validate items against the inner schema
+        validated: list[_T] = handler(items)
+
+        # Reconstruct original container type
+        if original_type is list:
+            return validated
+        # str(list) produces the list's repr, not a string built from items,
+        # so skip reconstruction for str and its subclasses.
+        if issubclass(original_type, str):
+            return validated
+        try:
+            return original_type(validated)
+        except (TypeError, ValueError):
+            # If the type cannot be reconstructed, just return the validated list
+            return validated
+
+    @staticmethod
+    def _serialize(v: Iterable[_T]) -> list[_T]:
+        """Always serialize as a list so Pydantic's JSON encoder is happy."""
+        if isinstance(v, list):
+            return v
+        return list(v)
+
+
+EagerIterable: TypeAlias = Annotated[Iterable[_T], _EagerIterable]
+
+
 def _construct_field(value: object, field: FieldInfo, key: str) -> object:
     if value is None:
         return field_get_default(field)

src/imagekitio/_qs.py

@@ -2,17 +2,13 @@
 
 from typing import Any, List, Tuple, Union, Mapping, TypeVar
 from urllib.parse import parse_qs, urlencode
-from typing_extensions import Literal, get_args
+from typing_extensions import get_args
 
-from ._types import NotGiven, not_given
+from ._types import NotGiven, ArrayFormat, NestedFormat, not_given
 from ._utils import flatten
 
 _T = TypeVar("_T")
 
-
-ArrayFormat = Literal["comma", "repeat", "indices", "brackets"]
-NestedFormat = Literal["dots", "brackets"]
-
 PrimitiveData = Union[str, int, float, bool, None]
 # this should be Data = Union[PrimitiveData, "List[Data]", "Tuple[Data]", "Mapping[str, Data]"]
 # https://github.com/microsoft/pyright/issues/3555

src/imagekitio/_types.py

@@ -47,6 +47,9 @@
 ModelT = TypeVar("ModelT", bound=pydantic.BaseModel)
 _T = TypeVar("_T")
 
+ArrayFormat = Literal["comma", "repeat", "indices", "brackets"]
+NestedFormat = Literal["dots", "brackets"]
+
 
 # Approximates httpx internal ProxiesTypes and RequestFiles types
 # while adding support for `PathLike` instances

src/imagekitio/_utils/__init__.py

@@ -24,7 +24,6 @@
     coerce_integer as coerce_integer,
     file_from_path as file_from_path,
     strip_not_given as strip_not_given,
-    deepcopy_minimal as deepcopy_minimal,
     get_async_library as get_async_library,
     maybe_coerce_float as maybe_coerce_float,
     get_required_header as get_required_header,