ImageInput

def ImageInput(  # noqa: N802
    url: str | None = None,
    *,
    file_id: str | None = None,
    filename: str | None = None,
    data: bytes | None = None,
    media_type: ImageMediaType | None = None,
    path: str | PathLike[str] | None = None,
) -> ImageUrlInput | FileIdInput | BinaryInput:
    """Factory for creating image input events.

    Usage:
        ImageInput("https://example.com/img.png")           # URL
        ImageInput(file_id="file-abc123")                   # pre-uploaded file
        ImageInput(data=raw_bytes, media_type="image/png")  # raw binary
        ImageInput(path="photo.jpg")                        # local file
    """
    if url is not None:
        return ImageUrlInput(url)

    if file_id is not None:
        return FileIdInput(file_id, filename=filename)

    if path is not None:
        p = Path(path)
        suffix = p.suffix.lower()
        resolved_type = _EXTENSION_TO_MEDIA_TYPE.get(suffix)

        if resolved_type is None:
            if media_type is None:
                raise ValueError(
                    f"Cannot infer image media type from extension '{suffix}'. Provide 'media_type' explicitly."
                )

            resolved_type = media_type

        return BinaryInput(
            p.read_bytes(),
            media_type=resolved_type,
            vendor_metadata={"filename": p.name},
            kind=BinaryType.IMAGE,
        )

    if data is not None:
        if media_type is None:
            raise ValueError("'media_type' is required when using 'data'")
        return BinaryInput(
            data,
            media_type=media_type,
            kind=BinaryType.IMAGE,
        )

    raise ValueError("ImageInput() requires one of: 'url', 'file_id', 'data' + 'media_type', or 'path'")