fix: Address review feedback for multipart file upload fix

- Make Pillow an optional dependency (lazy import with try/except)
- Remove Pillow from mandatory requirements, setup.py, pyproject.toml
- Add extras_require so users can `pip install okta[images]`
- Add logger.warning() when file type detection falls back
- Fix mutable default args in RequestExecutor.create_request()
- Fix param_serialize() docstring to match actual return signature
- Use case-insensitive Content-Type header lookup for OAuth forms
- Simplify JPEG detection to cover all SOI marker variants
- Restore issue #131 reference comment for json param handling

Author: BinoyOza-okta

okta/api_client.py

@@ -23,12 +23,12 @@
 import datetime
 import io
 import json
+import logging
 import mimetypes
 import os
 import re
 import tempfile
 from enum import Enum
-from PIL import Image
 from typing import Tuple, Optional, List, Dict, Union
 from urllib.parse import quote
 
@@ -49,6 +49,8 @@
 
 RequestSerialized = Tuple[str, str, Dict[str, str], Optional[str], List[str]]
 
+logger = logging.getLogger("okta-sdk-python")
+
 
 class ApiClient:
     """Generic API client for OpenAPI client library builds.
@@ -205,8 +207,7 @@ def param_serialize(
         :param _request_auth: set to override the auth_settings for an a single
                               request; this effectively ignores the authentication
                               in the spec for a single request.
-        :return: tuple of form (path, http_method, query_params, header_params,
-            body, post_params, files)
+        :return: tuple of (method, url, header_params, body, post_params)
         """
 
         config = self.configuration
@@ -578,21 +579,14 @@ def files_parameters(self, files: Dict[str, Union[str, bytes]]):
             elif isinstance(v, bytes):
                 filedata = v
 
-                # Validate file size
-                if len(filedata) < 4:
-                    raise ValueError(f"File data too small ({len(filedata)} bytes) - minimum 4 bytes required")
-                if len(filedata) > 2 * 1024 * 1024:  # 2MB limit (matches Okta's background image limit)
-                    raise ValueError(f"File data too large ({len(filedata)} bytes) - maximum 2MB allowed")
-
                 # Detect file type from magic bytes
-                # Note: This is client-side validation only. Okta API performs
-                # comprehensive server-side image validation as the security boundary.
-                if filedata.startswith(b'\x89PNG\r\n\x1a\n'):  # Full PNG signature
+                # Note: This is client-side detection for correct Content-Type
+                # assignment. Okta API performs server-side image validation
+                # as the security boundary.
+                if filedata.startswith(b'\x89PNG\r\n\x1a\n'):
                     filename = f"{k}.png"
                     mimetype = "image/png"
-                elif filedata.startswith(b'\xFF\xD8\xFF\xE0') or \
-                        filedata.startswith(b'\xFF\xD8\xFF\xE1') or \
-                        filedata.startswith(b'\xFF\xD8\xFF\xDB'):  # JPEG variants
+                elif filedata.startswith(b'\xFF\xD8'):  # All JPEG variants start with SOI marker
                     filename = f"{k}.jpg"
                     mimetype = "image/jpeg"
                 elif filedata.startswith(b'GIF87a') or filedata.startswith(b'GIF89a'):
@@ -602,6 +596,7 @@ def files_parameters(self, files: Dict[str, Union[str, bytes]]):
                     # For unknown types, attempt PIL validation if available
                     pil_validated = False
                     try:
+                        from PIL import Image  # Lazy import — Pillow is optional
                         img = Image.open(io.BytesIO(filedata))
                         img.verify()  # Verify it's actually a valid image
                         format_to_ext = {'PNG': 'png', 'JPEG': 'jpg', 'GIF': 'gif'}
@@ -610,17 +605,24 @@ def files_parameters(self, files: Dict[str, Union[str, bytes]]):
                         mimetype = f"image/{ext if ext != 'jpg' else 'jpeg'}"
                         pil_validated = True
                     except ImportError:
-                        # PIL not available - continue to fallback
-                        pass
+                        logger.warning(
+                            "Could not detect file type from magic bytes and "
+                            "Pillow is not installed for advanced detection. "
+                            "Install it with: pip install pillow"
+                        )
                     except Exception:
-                        # PIL validation failed - file may not be a valid image
-                        pass
+                        logger.warning(
+                            "File type detection failed — the file may not "
+                            "be a valid image. Okta accepts PNG, JPEG, and "
+                            "GIF formats only."
+                        )
 
                     if not pil_validated:
-                        # Fallback: Default to PNG with warning
-                        # Server-side validation will reject if not a valid image
-                        filename = f"{k}.png"
-                        mimetype = "image/png"
+                        # Fallback: default to application/octet-stream for
+                        # unrecognized types; server-side validation will
+                        # reject if the file is not a valid image.
+                        filename = f"{k}.bin"
+                        mimetype = "application/octet-stream"
             else:
                 raise ValueError("Unsupported file value")
             params.append(tuple([k, tuple([filename, filedata, mimetype])]))

okta/http_client.py

@@ -143,11 +143,16 @@ async def send_request(self, request):
                         # Remove Content-Type header - aiohttp.FormData will set it with boundary
                         params["headers"] = _remove_content_type_header(request_headers)
                     else:
-                        # Remove Content-Type header - aiohttp.FormData will set it with boundary
-                        if request_headers.get("Content-Type") == "application/x-www-form-urlencoded":
+                        # Regular form data (e.g., OAuth client_assertion)
+                        # For url-encoded forms, let aiohttp handle encoding
+                        ct = next((v for k, v in request_headers.items()
+                                   if k.lower() == "content-type"), None)
+                        if ct == "application/x-www-form-urlencoded":
                             params["headers"] = _remove_content_type_header(request_headers)
                         params["data"] = request["form"]
             json_data = request.get("json")
+            # Only include json param when present; empty value causes issues
+            # (ref: https://github.com/okta/okta-sdk-python/issues/131)
             if json_data:
                 params["json"] = json_data
             if self._timeout:

okta/request_executor.py

@@ -134,7 +134,7 @@ async def create_request(
         url: str,
         body: dict = None,
         headers: dict = None,
-        form: dict = None,
+        form=None,
         oauth=False,
         keep_empty_params=False,
     ):
@@ -146,9 +146,11 @@ async def create_request(
             url (str): URL to send request to
             body (dict, optional): Request body. Defaults to None.
             headers (dict, optional): Request headers. Defaults to None.
-            form (dict, optional): Form data. Defaults to None.
+            form (dict or list, optional): Form data. Dict for url-encoded forms,
+                list of tuples for multipart file uploads. Defaults to None.
             oauth: Should use oauth? Defaults to False.
-            keep_empty_params: Should request body keep parameters with empty values? Defaults to False.
+            keep_empty_params: Should request body keep parameters with empty
+                values? Defaults to False.
 
         Returns:
             dict, Exception: Tuple of Dictionary repr of HTTP request and
@@ -164,6 +166,8 @@ async def create_request(
 
         # Build request
         # Get predetermined headers and build URL
+        if headers is None:
+            headers = {}
         headers = {**self._custom_headers, **headers}
         headers = {**self._default_headers, **headers}
         if self._config["client"]["orgUrl"] not in url:

openapi/templates/api_client.mustache

@@ -11,12 +11,12 @@
 import datetime
 import io
 import json
+import logging
 import mimetypes
 import os
 import re
 import tempfile
 from enum import Enum
-from PIL import Image
 from typing import Tuple, Optional, List, Dict, Union
 from urllib.parse import quote
 
@@ -40,6 +40,8 @@ from {{packageName}}.exceptions.exceptions import (
 
 RequestSerialized = Tuple[str, str, Dict[str, str], Optional[str], List[str]]
 
+logger = logging.getLogger("okta-sdk-python")
+
 class ApiClient:
     """Generic API client for OpenAPI client library builds.
 
@@ -208,8 +210,7 @@ class ApiClient:
         :param _request_auth: set to override the auth_settings for an a single
                               request; this effectively ignores the authentication
                               in the spec for a single request.
-        :return: tuple of form (path, http_method, query_params, header_params,
-            body, post_params, files)
+        :return: tuple of (method, url, header_params, body, post_params)
         """
 
         config = self.configuration
@@ -591,21 +592,14 @@ class ApiClient:
             elif isinstance(v, bytes):
                 filedata = v
 
-                # Validate file size
-                if len(filedata) < 4:
-                    raise ValueError(f"File data too small ({len(filedata)} bytes) - minimum 4 bytes required")
-                if len(filedata) > 2 * 1024 * 1024:  # 2MB limit (matches Okta's background image limit)
-                    raise ValueError(f"File data too large ({len(filedata)} bytes) - maximum 2MB allowed")
-
                 # Detect file type from magic bytes
-                # Note: This is client-side validation only. Okta API performs
-                # comprehensive server-side image validation as the security boundary.
-                if filedata.startswith(b'\x89PNG\r\n\x1a\n'):  # Full PNG signature
+                # Note: This is client-side detection for correct Content-Type
+                # assignment. Okta API performs server-side image validation
+                # as the security boundary.
+                if filedata.startswith(b'\x89PNG\r\n\x1a\n'):
                     filename = f"{k}.png"
                     mimetype = "image/png"
-                elif filedata.startswith(b'\xFF\xD8\xFF\xE0') or \
-                        filedata.startswith(b'\xFF\xD8\xFF\xE1') or \
-                        filedata.startswith(b'\xFF\xD8\xFF\xDB'):  # JPEG variants
+                elif filedata.startswith(b'\xFF\xD8'):  # All JPEG variants start with SOI marker
                     filename = f"{k}.jpg"
                     mimetype = "image/jpeg"
                 elif filedata.startswith(b'GIF87a') or filedata.startswith(b'GIF89a'):
@@ -615,6 +609,7 @@ class ApiClient:
                     # For unknown types, attempt PIL validation if available
                     pil_validated = False
                     try:
+                        from PIL import Image  # Lazy import — Pillow is optional
                         img = Image.open(io.BytesIO(filedata))
                         img.verify()  # Verify it's actually a valid image
                         format_to_ext = {'PNG': 'png', 'JPEG': 'jpg', 'GIF': 'gif'}
@@ -623,17 +618,24 @@ class ApiClient:
                         mimetype = f"image/{ext if ext != 'jpg' else 'jpeg'}"
                         pil_validated = True
                     except ImportError:
-                        # PIL not available - continue to fallback
-                        pass
+                        logger.warning(
+                            "Could not detect file type from magic bytes and "
+                            "Pillow is not installed for advanced detection. "
+                            "Install it with: pip install pillow"
+                        )
                     except Exception:
-                        # PIL validation failed - file may not be a valid image
-                        pass
+                        logger.warning(
+                            "File type detection failed — the file may not "
+                            "be a valid image. Okta accepts PNG, JPEG, and "
+                            "GIF formats only."
+                        )
 
                     if not pil_validated:
-                        # Fallback: Default to PNG with warning
-                        # Server-side validation will reject if not a valid image
-                        filename = f"{k}.png"
-                        mimetype = "image/png"
+                        # Fallback: default to application/octet-stream for
+                        # unrecognized types; server-side validation will
+                        # reject if the file is not a valid image.
+                        filename = f"{k}.bin"
+                        mimetype = "application/octet-stream"
             else:
                 raise ValueError("Unsupported file value")
             params.append(tuple([k, tuple([filename, filedata, mimetype])]))

openapi/templates/okta/http_client.mustache

@@ -131,11 +131,16 @@ class HTTPClient:
                         # Remove Content-Type header - aiohttp.FormData will set it with boundary
                         params["headers"] = _remove_content_type_header(request_headers)
                     else:
-                        # Remove Content-Type header - aiohttp.FormData will set it with boundary
-                        if request_headers.get("Content-Type") == "application/x-www-form-urlencoded":
+                        # Regular form data (e.g., OAuth client_assertion)
+                        # For url-encoded forms, let aiohttp handle encoding
+                        ct = next((v for k, v in request_headers.items()
+                                   if k.lower() == "content-type"), None)
+                        if ct == "application/x-www-form-urlencoded":
                             params["headers"] = _remove_content_type_header(request_headers)
                         params["data"] = request["form"]
             json_data = request.get("json")
+            # Only include json param when present; empty value causes issues
+            # (ref: https://github.com/okta/okta-sdk-python/issues/131)
             if json_data:
                 params["json"] = json_data
             if self._timeout:

openapi/templates/okta/request_executor.mustache

@@ -134,10 +134,12 @@ class RequestExecutor:
         url: str,
         body: dict = None,
         headers: dict = None,
-        form: dict = None,
+        form=None,
         oauth=False,
         keep_empty_params=False,
     ):
+    async def create_request(self, method: str, url: str, body: dict = None,
+                             headers: dict = None, form=None, oauth=False, keep_empty_params=False):
         """
         Creates request for request executor's HTTP client.
 
@@ -147,8 +149,12 @@ class RequestExecutor:
             body (dict, optional): Request body. Defaults to None.
             headers (dict, optional): Request headers. Defaults to None.
             form (dict, optional): Form data. Defaults to None.
+            headers (dict, optional): Request headers. Defaults to None.
+            form (dict or list, optional): Form data. Dict for url-encoded forms,
+                list of tuples for multipart file uploads. Defaults to None.
             oauth: Should use oauth? Defaults to False.
-            keep_empty_params: Should request body keep parameters with empty values? Defaults to False.
+            keep_empty_params: Should request body keep parameters with empty
+                values? Defaults to False.
 
         Returns:
             dict, Exception: Tuple of Dictionary repr of HTTP request and
@@ -164,6 +170,8 @@ class RequestExecutor:
 
         # Build request
         # Get predetermined headers and build URL
+        if headers is None:
+            headers = {}
         headers = {**self._custom_headers, **headers}
         headers = {**self._default_headers, **headers}
         if self._config["client"]["orgUrl"] not in url:

openapi/templates/pyproject.mustache

@@ -27,7 +27,6 @@ pycryptodome = ">= 3.9.0"
 {{/hasHttpSignatureMethods}}
 pydantic = ">=2"
 typing-extensions = ">=4.7.1"
-pillow = "12.1.1"
 
 [tool.poetry.dev-dependencies]
 pytest = ">=7.2.1"

openapi/templates/requirements.mustache

@@ -2,7 +2,6 @@ aenum==3.1.11
 aiohttp==3.12.14
 blinker==1.9.0
 jwcrypto==1.5.6
-pillow==12.1.1
 pycryptodomex==3.23.0
 pydantic==2.11.3
 pydash==8.0.5

openapi/templates/setup.mustache

@@ -45,7 +45,6 @@ REQUIRES = [
     "PyYAML >= 6.0.2",
     "requests >= 2.32.3",
     "xmltodict >= 0.14.2",
-    "pillow >= 12.1.1",
 ]
 
 def get_version():
@@ -78,6 +77,9 @@ setup(
     url="https://github.com/okta/okta-sdk-python",
     keywords=["OpenAPI", "OpenAPI-Generator", "Okta Admin Management"],
     install_requires=REQUIRES,
+    extras_require={
+        "images": ["pillow >= 9.0.0"],
+    },
     packages=find_packages(exclude=["test", "tests"]),
     include_package_data=True,
     license="Apache-2.0",

pyproject.toml

@@ -16,7 +16,6 @@ urllib3 = ">= 1.25.3"
 python-dateutil = ">=2.8.2"
 pydantic = ">=2"
 typing-extensions = ">=4.7.1"
-pillow = "12.1.1"
 
 [tool.poetry.dev-dependencies]
 pytest = ">=7.2.1"