Skip to main content

Basics

Complete overview of the Vaiz SDK capabilities and structure.

Client Initialization​

All interactions go through the VaizClient class:

from vaiz import VaizClient

client = VaizClient(
    api_key="your_api_key",
    space_id="your_space_id",
    verify_ssl=True,      # Default: True
    base_url="https://..."  # Optional
)

Core Concepts​

Automatic Type Conversion​

The SDK automatically handles type conversions:

from datetime import datetime
from vaiz.models import CreateTaskRequest

# Input: Python datetime objects
task = CreateTaskRequest(
    name="Task",
    due_end=datetime(2025, 12, 31, 17, 0)
)

# SDK converts to ISO strings for API
response = client.create_task(task)

# Output: Python datetime objects
print(response.task.created_at)     # datetime object
print(response.task.due_end.year)   # 2025

Type Safety with Enums​

Use enums for type-safe values:

from vaiz.models import TaskPriority
from vaiz.models.enums import Icon, Color, UploadFileType

priority = TaskPriority.High           # 3
icon = Icon.Bug                       # "Bug"
color = Color.Red                     # "Red"
file_type = UploadFileType.Image      # "image"

Pydantic Models​

All requests and responses use Pydantic v2 for validation:

from vaiz.models import CreateTaskRequest

# Full IDE autocomplete and validation
task = CreateTaskRequest(
    name="Task",           # Required - will error if missing
    board="board_id",      # Required
    group="group_id",      # Optional
    priority=TaskPriority.High,  # Optional
    assignees=["user_id"]  # Optional
)

# Automatic validation on creation
# Invalid data raises ValidationError

Common Patterns​

Error Handling​

from vaiz.api.base import (
    VaizSDKError,
    VaizAuthError,
    VaizValidationError,
    VaizNotFoundError
)

try:
    response = client.create_task(task)
except VaizAuthError as e:
    print(f"Authentication failed: {e}")
except VaizValidationError as e:
    print(f"Validation error: {e}")
except VaizNotFoundError as e:
    print(f"Resource not found: {e}")
except VaizSDKError as e:
    print(f"SDK error: {e}")

Pagination​

from vaiz.models import GetTasksRequest

all_tasks = []
skip = 0

while True:
    request = GetTasksRequest(
        completed=False,
        limit=50,
        skip=skip
    )
    
    response = client.get_tasks(request)
    tasks = response.payload.tasks
    
    if not tasks:
        break
    
    all_tasks.extend(tasks)
    skip += 50
    
    if len(tasks) < 50:
        break  # Last page

print(f"Total: {len(all_tasks)} tasks")

Working with Dates​

from datetime import datetime, timedelta

# Create with dates
task = CreateTaskRequest(
    name="Sprint Task",
    due_start=datetime.now(),
    due_end=datetime.now() + timedelta(weeks=2)
)

response = client.create_task(task)

# Use datetime methods
days_left = (response.task.due_end - datetime.now()).days
print(f"Days remaining: {days_left}")

Batch Operations​

# Create multiple tasks
tasks_data = [
    ("Design mockups", TaskPriority.High),
    ("Implement API", TaskPriority.High),
    ("Write tests", TaskPriority.Medium),
]

for name, priority in tasks_data:
    task = CreateTaskRequest(
        name=name,
        board="board_id",
        group="group_id",
        priority=priority
    )
    client.create_task(task)

Best Practices​

Use Environment Variables​

# ✅ Good
from dotenv import load_dotenv
import os

load_dotenv()
client = VaizClient(
    api_key=os.getenv("VAIZ_API_KEY"),
    space_id=os.getenv("VAIZ_SPACE_ID")
)

# ❌ Bad
client = VaizClient(
    api_key="hardcoded_key",  # Never commit API keys!
    space_id="hardcoded_id"
)

Use Type Hints​

# ✅ Good
from vaiz.models import Task, GetTasksRequest
from typing import List

def get_completed_tasks() -> List[Task]:
    request = GetTasksRequest(completed=True)
    response = client.get_tasks(request)
    return response.payload.tasks

# ❌ Bad
def get_tasks():  # No type hints
    request = GetTasksRequest(completed=True)
    return client.get_tasks(request).payload.tasks

Handle Errors​

# ✅ Good
from vaiz.api.base import VaizSDKError

try:
    response = client.create_task(task)
    return response.task
except VaizSDKError as e:
    logger.error(f"Failed to create task: {e}")
    return None

# ❌ Bad
response = client.create_task(task)  # Can crash
return response.task

Use Helper Functions​

The SDK provides helper functions for common operations:

from vaiz import make_text_value, make_date_value, make_select_option

# Clean, type-safe value creation
value = make_text_value("Hello")
date = make_date_value(datetime.now())
option = make_select_option("High", Color.Red, Icon.Flag)

See all helper functions →

Guides​

Explore detailed documentation for each SDK feature:

Check out Examples for ready-to-use code and Common Patterns for best practices.