feat: Simplify image_block() API - accept file object directly (v0.16.0)

BREAKING CHANGE: image_block() now accepts file object instead of individual parameters

- Simplified API from 7 parameters to 1: image_block(file=uploaded.file)
- Auto-extract all metadata from uploaded file object (id, url, name, size, ext, dimensions)
- Auto-detect MIME type from extension or file.mime
- Auto-calculate aspect ratio from dimensions
- Removed aspect_ratio parameter (calculated automatically)
- Updated all tests, examples, and documentation
- Reduces code by 80% and eliminates parameter errors

Migration:
  Old: image_block(file_id=f.id, src=f.url, file_name=f.name, ...)
  New: image_block(file=uploaded.file, caption="...")

Author: m-brtn

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.16.0] - 2025-10-24
+
+### Changed
+
+- **🔧 Breaking**: Simplified `image_block()` API - now accepts file object directly
+  - **Old API** (deprecated): `image_block(file_id=..., src=..., file_name=..., file_size=..., extension=..., dimensions=...)`
+  - **New API**: `image_block(file=uploaded.file, caption="...", width_percent=100)`
+  - Reduces code by 80% - just pass the file object!
+  - All file metadata extracted automatically from uploaded file
+  - MIME type auto-detected from extension or file.mime
+  - Aspect ratio auto-calculated from dimensions
+  - Migration: Replace multiple parameters with single `file=uploaded.file` parameter
+
 ## [0.15.0] - 2025-10-24
 
 ### Added

docs-site/docs/api-reference/document-structure.md

@@ -1292,15 +1292,9 @@ from vaiz import image_block, heading, paragraph
 # Upload image first
 uploaded = client.upload_file("photo.jpg")
 
-# Create image block
+# Create image block - simple! Just pass the file
 image = image_block(
-    file_id=uploaded.file.id,
-    src=uploaded.file.url,
-    file_name="photo.jpg",
-    file_size=uploaded.file.size,
-    extension="jpg",
-    file_type="image/jpeg",
-    dimensions=[1920, 1080],
+    file=uploaded.file,
     caption="Product photo",
     width_percent=75
 )
@@ -1431,10 +1425,7 @@ content = [
     # Image
     paragraph("New interface:"),
     image_block(
-        file_id=screenshot.file.id,
-        src=screenshot.file.url,
-        file_name="app.png",
-        file_size=screenshot.file.size,
+        file=screenshot.file,
         caption="Main screen"
     ),
 

docs-site/docs/guides/document-structure-helpers.md

@@ -667,14 +667,9 @@ from vaiz import image_block, heading, paragraph
 # First, upload the image
 uploaded = client.upload_file("screenshots/dashboard.png")
 
-# Create image block
+# Create image block - simple! Just pass the file
 image = image_block(
-    file_id=uploaded.file.id,
-    src=uploaded.file.url,
-    file_name="dashboard.png",
-    file_size=uploaded.file.size,
-    extension="png",
-    file_type="image/png",
+    file=uploaded.file,
     caption="Main dashboard view"
 )
 
@@ -702,15 +697,9 @@ width, height = img.size
 # Upload image
 uploaded = client.upload_file("photo.jpg")
 
-# Create image block with dimensions
+# Create image block with custom width
 image = image_block(
-    file_id=uploaded.file.id,
-    src=uploaded.file.url,
-    file_name="photo.jpg",
-    file_size=uploaded.file.size,
-    extension="jpg",
-    file_type="image/jpeg",
-    dimensions=[width, height],  # Automatically calculates aspect ratio
+    file=uploaded.file,
     caption="Product photo",
     width_percent=75  # Display at 75% width
 )
@@ -738,28 +727,19 @@ content = [
 
     paragraph("Login screen:"),
     image_block(
-        file_id=screenshot1.file.id,
-        src=screenshot1.file.url,
-        file_name="login.png",
-        file_size=screenshot1.file.size,
+        file=screenshot1.file,
         caption="User authentication"
     ),
 
     paragraph("Dashboard:"),
     image_block(
-        file_id=screenshot2.file.id,
-        src=screenshot2.file.url,
-        file_name="dashboard.png",
-        file_size=screenshot2.file.size,
+        file=screenshot2.file,
         caption="Main dashboard view"
     ),
 
     paragraph("Settings:"),
     image_block(
-        file_id=screenshot3.file.id,
-        src=screenshot3.file.url,
-        file_name="settings.png",
-        file_size=screenshot3.file.size,
+        file=screenshot3.file,
         caption="Configuration panel"
     )
 ]
@@ -919,10 +899,7 @@ content = [
 
     # Logo image
     image_block(
-        file_id=logo.file.id,
-        src=logo.file.url,
-        file_name="logo.png",
-        file_size=logo.file.size,
+        file=logo.file,
         width_percent=50,  # Display at 50% width
         caption="Company Logo"
     ),
@@ -937,10 +914,7 @@ content = [
     heading(2, "New Features"),
     paragraph("We launched a redesigned application:"),
     image_block(
-        file_id=screenshot.file.id,
-        src=screenshot.file.url,
-        file_name="app_screen.png",
-        file_size=screenshot.file.size,
+        file=screenshot.file,
         caption="New dashboard interface"
     ),
 
@@ -991,10 +965,7 @@ description_content = [
 
     heading(3, "Screenshot"),
     image_block(
-        file_id=screenshot.file.id,
-        src=screenshot.file.url,
-        file_name="error.png",
-        file_size=screenshot.file.size,
+        file=screenshot.file,
         caption="Error state"
     ),
 

docs-site/docusaurus.config.ts

@@ -206,8 +206,8 @@ const config: Config = {
       },
       items: [
         {
-          label: "v0.15.0",
-          href: "https://pypi.org/project/vaiz-sdk/0.15.0/",
+          label: "v0.16.0",
+          href: "https://pypi.org/project/vaiz-sdk/0.16.0/",
           position: "left",
         },
         {

examples/comprehensive_blocks_example.py

@@ -134,14 +134,9 @@ def main():
 
             paragraph(text("Project screenshot:")),
 
+            # New simple API - just pass the file!
             image_block(
-                file_id=image_uploaded.file.id,
-                src=image_uploaded.file.url,
-                file_name=image_uploaded.file.name,
-                file_size=image_uploaded.file.size,
-                extension=image_uploaded.file.ext,
-                file_type=image_uploaded.file.mime or "image/png",
-                dimensions=image_uploaded.file.dimension if image_uploaded.file.dimension else None,
+                file=image_uploaded.file,
                 caption="Project Screenshot",
                 width_percent=80
             ),

examples/file_and_image_blocks.py

@@ -90,16 +90,8 @@ def main():
 
             paragraph(text("Here's an embedded image:")),
 
-            image_block(
-                file_id=image_uploaded.file.id,
-                src=image_uploaded.file.url,
-                file_name=image_uploaded.file.name,
-                file_size=image_uploaded.file.size,
-                extension=image_uploaded.file.ext,
-                file_type=image_uploaded.file.mime or "image/png",
-                width_percent=100,
-                dimensions=image_uploaded.file.dimension if image_uploaded.file.dimension else None
-            ),
+            # New simple API - just pass the file!
+            image_block(file=image_uploaded.file),
 
             paragraph(text("Image displayed above", italic=True)),
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vaiz-sdk"
-version = "0.15.0"
+version = "0.16.0"
 description = "Official SDK for interacting with the Vaiz API"
 authors = [{ name = "Vaiz", email = "mail@vaiz.com" }]
 license = "MIT"