vikunja-python 0.1.0__py3-none-any.whl

vikunja_python/core/models/base.py

@@ -0,0 +1,193 @@
+"""
+Vikunja Pydantic Models - Base Configuration
+
+All Vikunja API models inherit from VikunjaBaseModel for consistent configuration.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from datetime import datetime
+from typing import Optional
+import re
+
+
+class VikunjaBaseModel(BaseModel):
+    """
+    Base model with common configuration for all Vikunja API models.
+    
+    Configuration:
+        extra='ignore': Ignore undocumented fields from API (prevents crashes on upstream changes)
+        populate_by_name=True: Accept both snake_case and camelCase field names
+        from_attributes=True: Support ORM mode if needed for database integration
+    """
+    model_config = ConfigDict(
+        extra='ignore',           # Ignore undocumented API fields
+        populate_by_name=True,    # Allow both naming conventions
+        from_attributes=True,     # Support ORM mode
+    )
+
+
+# ============================================================================
+# Shared Nested Models (used across multiple entities)
+# ============================================================================
+
+class User(VikunjaBaseModel):
+    """
+    User object as returned by the Vikunja API.
+
+    Appears in: assignees[], created_by, owner (projects), labels.created_by
+    """
+    id: int = Field(..., description="Unique user identifier")
+    username: str = Field(..., description="Username")
+    email: Optional[str] = Field(None, description="Email address")
+    name: Optional[str] = Field(None, description="Display name (may be empty string)")
+    created: datetime = Field(..., description="Account creation timestamp (ISO 8601)")
+    updated: datetime = Field(..., description="Last update timestamp (ISO 8601)")
+
+class Label(VikunjaBaseModel):
+    """
+    Label (tag) assigned to tasks.
+    
+    API endpoint: /labels
+    Used in: Task.labels[]
+    """
+    id: int = Field(..., description="Unique label identifier")
+    title: str = Field(..., description="Label text/title")
+    description: Optional[str] = Field(None, description="Label description (markdown)")
+    hex_color: Optional[str] = Field(None, description="Hex color code")
+
+    @field_validator('hex_color')
+    @classmethod
+    def validate_hex_color(cls, v):
+        """Validate and normalize hex color format (#RRGGBB)."""
+        if v is None or v == "":
+            return None
+        # Add # if missing
+        if not v.startswith('#'):
+            v = f'#{v}'
+        if not re.match(r'^#[0-9A-Fa-f]{6}$', v):
+            return None # Or raise error, but base model should be lenient
+        return v
+    created_by: Optional[User] = Field(None, description="User who created this label")
+    created: datetime = Field(..., description="Creation timestamp (ISO 8601)")
+    updated: datetime = Field(..., description="Last update timestamp (ISO 8601)")
+
+
+class TaskComment(VikunjaBaseModel):
+    """
+    Comment on a task.
+    
+    API endpoint: /tasks/{id}/comments
+    
+    UNKNOWN: Full structure not yet verified from API response
+    TODO: Extract from actual API call with expand=comments
+    """
+    # UNKNOWN: Field definitions pending API verification
+    id: Optional[int] = Field(None, description="Comment ID")
+    text: Optional[str] = Field(None, description="Comment text (markdown)")
+    # TODO: Add remaining fields after API inspection
+
+
+class TaskAttachment(VikunjaBaseModel):
+    """
+    File attachment on a task.
+    
+    API endpoint: /tasks/{id}/attachments
+    
+    UNKNOWN: Full structure not yet verified from API response
+    TODO: Extract from actual API call with expand=attachments
+    """
+    # UNKNOWN: Field definitions pending API verification
+    id: Optional[int] = Field(None, description="Attachment ID")
+    filename: Optional[str] = Field(None, description="Original filename")
+    # TODO: Add remaining fields after API inspection
+
+
+class TaskReminder(VikunjaBaseModel):
+    """
+    Reminder for a task.
+    
+    API endpoint: /tasks/{id}/reminders
+    
+    UNKNOWN: Full structure not yet verified from API response
+    TODO: Extract from actual API call with expand=reminders
+    """
+    # UNKNOWN: Field definitions pending API verification
+    id: Optional[int] = Field(None, description="Reminder ID")
+    reminder_at: Optional[datetime] = Field(None, description="When reminder triggers")
+    # TODO: Add remaining fields after API inspection
+
+
+# ============================================================================
+# Error Handling Models
+# ============================================================================
+
+class ErrorDetail(VikunjaBaseModel):
+    """
+    Structured error response for LLM consumption.
+    
+    Vikunja API returns errors in this format:
+        {"code": <int>, "message": "<string>"}
+    
+    The 'code' field is an error code (e.g., 11 = invalid token).
+    """
+    code: int = Field(..., description="Machine-readable error code")
+    message: str = Field(..., description="Human-readable error message")
+
+
+class Message(VikunjaBaseModel):
+    """
+    Generic API message wrapper.
+    
+    Used for simple success/error messages from the API.
+    """
+    code: Optional[int] = Field(None, description="Error code if applicable")
+    message: str = Field(..., description="Message text")
+
+
+# ============================================================================
+# Authentication Models
+# ============================================================================
+
+class Token(VikunjaBaseModel):
+    """
+    Authentication token response.
+    
+    Returned by: POST /login, POST /auth/openid/{provider}/callback
+    """
+    # UNKNOWN: Exact fields not yet verified - placeholder based on JWT patterns
+    token: Optional[str] = Field(None, description="JWT token")
+    expires_at: Optional[datetime] = Field(None, description="Token expiration time")
+    # TODO: Verify exact fields from /login response
+
+
+# ============================================================================
+# Pagination Metadata (from API headers)
+# ============================================================================
+
+class PaginationInfo(VikunjaBaseModel):
+    """
+    Pagination metadata from response headers.
+    
+    Vikunja returns pagination info in headers:
+        x-pagination-total-pages: <int>
+        x-pagination-result-count: <int>
+    """
+    total_pages: Optional[int] = Field(None, description="Total number of pages")
+    result_count: Optional[int] = Field(None, description="Number of items in current response")
+    # TODO: Add page/per_page if returned in body
+
+
+# ============================================================================
+# Generic Response Wrappers
+# ============================================================================
+
+class ListResponse(VikunjaBaseModel):
+    """
+    Generic wrapper for list responses with pagination.
+    
+    Usage: ListResponse[Task] for task lists
+    """
+    success: bool = Field(True, description="Request succeeded")
+    items: list = Field(default_factory=list, description="List of items")
+    error: Optional[ErrorDetail] = Field(None, description="Error if request failed")
+    pagination: Optional[PaginationInfo] = Field(None, description="Pagination metadata")

vikunja_python/core/models/bulk_assignees.py

@@ -0,0 +1,98 @@
+"""
+Bulk Assignment Models
+
+Models for bulk task assignment operations.
+Based on Vikunja API v2.3.0 specification.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class User(BaseModel):
+    """User representation for bulk assignments."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    id: int = Field(..., description="The unique user ID")
+    username: str = Field(..., description="The username")
+    name: str = Field(..., description="The full name of the user")
+    email: Optional[str] = Field(None, description="The email address of the user")
+    created: datetime = Field(..., description="Account creation timestamp")
+    updated: datetime = Field(..., description="Last update timestamp")
+
+
+class BulkAssignees(BaseModel):
+    """Request to bulk assign users to tasks.
+    
+    Used when assigning multiple users to a single task or the same set of users
+    to multiple tasks.
+    """
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    assignees: list[User] = Field(..., description="List of users to assign to the task(s)")
+
+
+class BulkAssigneesCreateRequest(BaseModel):
+    """Request to create bulk assignments for a task."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    assignees: list[int] = Field(
+        ..., 
+        description="List of user IDs to assign to the task"
+    )
+
+
+class BulkAssigneesResponse(BaseModel):
+    """Response from a bulk assignment operation."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    assignees: list[User] = Field(..., description="List of assigned users")
+
+
+class BulkTask(BaseModel):
+    """Bulk task operation request.
+    
+    Used for updating multiple tasks with the same field values at once.
+    """
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    task_ids: list[int] = Field(
+        ..., 
+        description="List of task IDs to update"
+    )
+    fields: list[str] = Field(
+        ..., 
+        description="List of field names to update (e.g., 'title', 'priority', 'done')"
+    )
+    values: dict = Field(
+        default_factory=dict, 
+        description="Map of field names to values. Only fields in the 'fields' list will be updated."
+    )
+
+
+class BulkTaskResponse(BaseModel):
+    """Response from a bulk task operation."""
+    
+    model_config = ConfigDict(extra='ignore')
+    
+    tasks: list[dict] = Field(
+        default_factory=list, 
+        description="List of updated task objects"
+    )
+    success_count: int = Field(
+        0, 
+        description="Number of tasks successfully updated"
+    )
+    failure_count: int = Field(
+        0, 
+        description="Number of tasks that failed to update"
+    )

vikunja_python/core/models/filter.py

@@ -0,0 +1,134 @@
+"""
+Filter Models for Vikunja API
+
+Covers: models.SavedFilter and related types
+API endpoints: /filters, /filters/{id}
+
+Note: GET /filters returns 405 (Method Not Allowed) - use PUT to create filters.
+      Filters are typically managed through the UI or project views.
+"""
+
+from pydantic import Field
+from datetime import datetime
+from typing import Optional, Any
+from .base import VikunjaBaseModel, User
+
+
+# ============================================================================
+# Task Collection (filter definition)
+# ============================================================================
+
+class TaskCollection(VikunjaBaseModel):
+    """
+    Filter query definition for matching tasks.
+    
+    Used in: SavedFilter.filters
+    
+    Documentation: https://vikunja.io/docs/filters
+    
+    Example filter syntax: "done = false && priority >= 3"
+    """
+    filter: Optional[str] = Field(None, description="Filter expression (e.g., 'done = false && priority >= 3')")
+    filter_include_nulls: bool = Field(False, description="Include null values in results")
+    order_by: Optional[list[str]] = Field(None, description="Order direction: ['asc'] or ['desc']")
+    s: Optional[str] = Field(None, description="Search term")
+    sort_by: Optional[list[str]] = Field(None, description="Fields to sort by (e.g., ['due_date', 'priority'])")
+
+
+# ============================================================================
+# Saved Filter Entity Model
+# ============================================================================
+
+class SavedFilter(VikunjaBaseModel):
+    """
+    Saved filter model representing a user-created filter preset.
+    
+    API endpoint: PUT /filters (create), GET /filters/{id}, POST /filters/{id}, DELETE /filters/{id}
+    
+    Fields from API spec (models.SavedFilter):
+        - id: Unique numeric ID
+        - title: Filter name (1-250 chars, required)
+        - description: Optional description
+        - filters: TaskCollection defining the filter logic
+        - is_favorite: Whether filter is favorited
+        - owner: User who owns this filter
+        - created: Creation timestamp (auto-set, read-only)
+        - updated: Last update timestamp (auto-set, read-only)
+    """
+    
+    # Core Identification (2 fields)
+    id: Optional[int] = Field(None, description="Unique filter identifier (auto-assigned on create)")
+    title: str = Field(..., min_length=1, max_length=250, description="Filter name/title")
+    
+    # Filter Definition (2 fields)
+    description: Optional[str] = Field(None, description="Filter description")
+    filters: Optional[TaskCollection] = Field(None, description="Filter logic definition")
+    
+    # Status & Ownership (2 fields)
+    is_favorite: bool = Field(False, description="Marked as favorite")
+    owner: Optional[User] = Field(None, description="Filter owner")
+    
+    # Timestamps (auto-managed by server) - 2 fields
+    created: Optional[datetime] = Field(None, description="Creation timestamp (read-only)")
+    updated: Optional[datetime] = Field(None, description="Last update timestamp (read-only)")
+
+
+# ============================================================================
+# Filter Request Models
+# ============================================================================
+
+class SavedFilterCreateRequest(VikunjaBaseModel):
+    """
+    Request body for creating a new saved filter.
+    
+    Required fields: title, filters
+    Optional fields: description, is_favorite
+    
+    API endpoint: PUT /filters
+    """
+    title: str = Field(..., min_length=1, max_length=250, description="Filter name (required)")
+    filters: TaskCollection = Field(..., description="Filter logic definition")
+    
+    # Optional fields
+    description: Optional[str] = Field(None, description="Filter description")
+    is_favorite: bool = Field(False, description="Mark as favorite")
+    
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return self.model_dump(exclude_none=True)
+
+
+class SavedFilterUpdateRequest(VikunjaBaseModel):
+    """
+    Request body for updating a saved filter.
+    
+    All fields optional - only provided fields are updated.
+    
+    API endpoint: POST /filters/{id}
+    """
+    title: Optional[str] = Field(None, min_length=1, max_length=250)
+    description: Optional[str] = None
+    filters: Optional[TaskCollection] = None
+    is_favorite: Optional[bool] = None
+    
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return self.model_dump(exclude_none=True)
+
+
+# ============================================================================
+# Filter List/Get Response Models
+# ============================================================================
+
+class SavedFilterListResponse(VikunjaBaseModel):
+    """Response for filter list operations."""
+    success: bool = Field(True, description="Request succeeded")
+    filters: list[SavedFilter] = Field(default_factory=list, description="List of saved filters")
+    error: Optional[Any] = Field(None, description="Error if request failed")
+
+
+class SavedFilterGetResponse(VikunjaBaseModel):
+    """Response for getting a single filter."""
+    success: bool = Field(True, description="Request succeeded")
+    filter: Optional[SavedFilter] = Field(None, description="The saved filter")
+    error: Optional[Any] = Field(None, description="Error if request failed")

vikunja_python/core/models/label.py

@@ -0,0 +1,230 @@
+"""
+Label Models for Vikunja API
+
+Covers: models.Label, LabelCreateRequest, LabelUpdateRequest, LabelListResponse
+API endpoints: /labels (CRUD operations)
+
+Labels are reusable tags that can be applied to tasks. Each label has:
+- title (required): Display name shown on tasks
+- hex_color: 7-character hex color code (#RRGGBB)
+- description: Optional explanatory text
+- created/updated: Auto-managed timestamps
+- created_by: User who created the label
+
+Usage Examples:
+    # Create a new label
+    label = LabelCreateRequest(
+        title="bug",
+        hex_color="#ff0000",
+        description="Bug reports and issues"
+    )
+    
+    # Update an existing label
+    update = LabelUpdateRequest(
+        title="critical-bug",  # Rename the label
+        hex_color="#ff0000"     # Keep same color
+    )
+"""
+
+from pydantic import Field, field_validator
+from datetime import datetime
+from typing import Optional
+import re
+from .base import VikunjaBaseModel, User
+
+
+# ============================================================================
+# Label Model (Full structure from API spec)
+# ============================================================================
+
+class Label(VikunjaBaseModel):
+    """
+    A reusable label/tag for categorizing tasks.
+    
+    API endpoint: /labels
+    
+    Labels are shared across projects and can be applied to multiple tasks.
+    Each label has a unique ID, title, color, and optional description.
+    
+    Fields from API spec (models.Label):
+        - id: Unique identifier (auto-assigned)
+        - title: Display name (required, 1-250 chars)
+        - hex_color: Color in #RRGGBB format (max 7 chars)
+        - description: Optional explanatory text
+        - created: Auto-set creation timestamp
+        - updated: Auto-set update timestamp  
+        - created_by: User who created the label
+    
+    Example from API response:
+        {
+            "id": 1,
+            "title": "bug",
+            "hex_color": "#ff0000",
+            "description": "Bug reports and issues",
+            "created": "2024-01-15T10:30:00Z",
+            "updated": "2024-01-15T10:30:00Z",
+            "created_by": {...}
+        }
+    """
+    
+    # Core Identification (2 fields)
+    id: Optional[int] = Field(None, description="Unique label ID (auto-assigned by server)")
+    title: str = Field(
+        ..., 
+        min_length=1, 
+        max_length=250,
+        description="Label display name shown on tasks"
+    )
+    
+    # Visual Properties (2 fields)
+    hex_color: Optional[str] = Field(
+        None,
+        max_length=7,
+        description="Hex color code (#RRGGBB format)"
+    )
+    description: Optional[str] = Field(None, description="Optional label description")
+    
+    # Metadata (3 fields - auto-managed by server)
+    created: Optional[datetime] = Field(None, description="Creation timestamp (read-only)")
+    updated: Optional[datetime] = Field(None, description="Last update timestamp (read-only)")
+    created_by: Optional[User] = Field(None, description="User who created this label")
+    
+    @field_validator('hex_color')
+    @classmethod
+    def validate_hex_color(cls, v):
+        """Validate and normalize hex color format (#RRGGBB)."""
+        if v is None or v == "":
+            return None
+        # Add # if missing
+        if not v.startswith('#'):
+            v = f'#{v}'
+        if not re.match(r'^#[0-9A-Fa-f]{6}$', v):
+            raise ValueError(f"Invalid hex color format: {v}. Expected #RRGGBB or RRGGBB")
+        return v
+
+
+# ============================================================================
+# Label Create Request Model
+# ============================================================================
+
+class LabelCreateRequest(VikunjaBaseModel):
+    """
+    Request body for creating a new label.
+    
+    Required fields: title (1-250 chars)
+    Optional fields: hex_color, description
+    
+    API endpoint: POST /labels
+    
+    Example:
+        req = LabelCreateRequest(
+            title="bug",
+            hex_color="#ff0000",
+            description="Bug reports and issues"
+        )
+    
+    Validation:
+        - title: 1-250 characters, required
+        - hex_color: Must be valid #RRGGBB format if provided
+        - description: Any length if provided
+    """
+    title: str = Field(
+        ..., 
+        min_length=1, 
+        max_length=250,
+        description="Label display name (required)"
+    )
+    hex_color: Optional[str] = Field(None, max_length=7, description="Hex color (#RRGGBB)")
+    description: Optional[str] = Field(None, description="Optional label description")
+    
+    @field_validator('hex_color')
+    @classmethod
+    def validate_hex_color(cls, v):
+        """Validate and normalize hex color format."""
+        if v is None or v == "":
+            return None
+        if not v.startswith('#'):
+            v = f'#{v}'
+        if not re.match(r'^#[0-9A-Fa-f]{6}$', v):
+            raise ValueError(f"Invalid hex color format: {v}. Expected #RRGGBB or RRGGBB")
+        return v
+
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict for API submission."""
+        return self.model_dump(exclude_none=True)
+
+
+# ============================================================================
+# Label Update Request Model  
+# ============================================================================
+
+class LabelUpdateRequest(VikunjaBaseModel):
+    """
+    Request body for updating an existing label.
+    
+    All fields are optional - only provided fields are updated.
+    
+    API endpoint: POST /labels/{id} (implied)
+    
+    Example:
+        # Rename a label, keep color
+        req = LabelUpdateRequest(
+            title="critical-bug"  # Only title changes
+        )
+        
+        # Update color only
+        req = LabelUpdateRequest(
+            hex_color="#ff6600"  # Only color changes
+        )
+    """
+    title: Optional[str] = Field(None, min_length=1, max_length=250, description="New label name")
+    hex_color: Optional[str] = Field(None, max_length=7, description="New hex color (#RRGGBB)")
+    description: Optional[str] = Field(None, description="New label description")
+    
+    @field_validator('hex_color')
+    @classmethod
+    def validate_hex_color(cls, v):
+        """Validate and normalize hex color format."""
+        if v is None or v == "":
+            return None
+        if not v.startswith('#'):
+            v = f'#{v}'
+        if not re.match(r'^#[0-9A-Fa-f]{6}$', v):
+            raise ValueError(f"Invalid hex color format: {v}. Expected #RRGGBB or RRGGBB")
+        return v
+    
+    def model_dump_for_api(self) -> dict:
+        """Convert to dict, excluding None values."""
+        return self.model_dump(exclude_none=True)
+
+
+# ============================================================================
+# Label Response Models
+# ============================================================================
+
+class LabelListResponse(VikunjaBaseModel):
+    """Response for listing labels."""
+    success: bool = Field(True, description="Request succeeded")
+    labels: list[Label] = Field(default_factory=list, description="List of labels")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class LabelGetResponse(VikunjaBaseModel):
+    """Response for getting a single label."""
+    success: bool = Field(True, description="Request succeeded")
+    label: Optional[Label] = Field(None, description="The requested label")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class LabelCreateResponse(VikunjaBaseModel):
+    """Response for creating a label."""
+    success: bool = Field(True, description="Request succeeded")
+    label: Optional[Label] = Field(None, description="The created label")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class LabelUpdateResponse(VikunjaBaseModel):
+    """Response for updating a label."""
+    success: bool = Field(True, description="Request succeeded")
+    label: Optional[Label] = Field(None, description="The updated label")
+    error: Optional[str] = Field(None, description="Error message if failed")