vikunja-python 0.1.0__tar.gz

vikunja_python-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: vikunja-python
+Version: 0.1.0
+Summary: API wrapper, CLI tool, and MCP server for Vikunja
+Author-email: Your Name <your.email@example.com>
+License-Expression: WTFPL
+Requires-Python: >=3.13.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: dateparser>=1.2.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: fastmcp>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Requires-Dist: testcontainers[mysql]>=4.0.0; extra == "test"

vikunja_python-0.1.0/README.md

@@ -0,0 +1,85 @@
+# Vikunja Python
+
+An open-source (WTFPL) API wrapper, rich CLI tool, and Model Context Protocol (MCP) server for the [Vikunja](https://vikunja.io/) task management system.
+
+Built for **Python 3.13** using `httpx`, `pydantic v2`, and `fastmcp`.
+
+## 🏗 Architecture
+
+The project is structured into three distinct layers to ensure modularity and clean dependency management:
+
+- **`/core`**: The engine. Handles Pydantic models, HTTP client logic, and error handling. (Minimal dependencies).
+- **`/cli`**: A high-visual-impact command-line interface built with `typer` and `rich`.
+- **`/mcp`**: A Model Context Protocol server designed for agentic workflows, optimized for smaller LLMs (like Gemma).
+
+## 🚀 Getting Started
+
+### Installation
+This project uses `uv` for modern Python package management.
+
+```bash
+uv sync --all-extras
+```
+
+### Environment Variables
+Configure your Vikunja instance in a `.env` file or your shell:
+
+```bash
+VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
+VIKUNJA_API_TOKEN="your_api_token_here"  # Recommended for MCP
+VIKUNJA_JWT_TOKEN="your_jwt_here"        # Required for Buckets/Reactions in CLI
+VIKUNJA_DEBUG="true"                     # Set to true or 1 to enable verbose stderr logging
+```
+
+## 🛠 Features & Tooling
+
+### CLI (`vikunja`)
+The CLI provides a rich, human-friendly interface for managing your workspace.
+- **Tasks & Projects**: Full CRUD support with formatted tables.
+- **Buckets (Kanban)**: List and manage columns (Requires JWT).
+- **Reactions**: Add emojis to tasks (Requires JWT).
+- **Labels**: List and categorize tasks.
+- **Auth**: Built-in `login` command to generate JWTs.
+
+```bash
+uv run vikunja list-tasks
+uv run vikunja login
+```
+
+### MCP Server (`vikunja-mcp`)
+A powerful server that gives LLMs "hands" to manage your Vikunja instance. Optimized for reliability and low turn-count.
+- **Global Search**: Find tasks across all projects in one turn.
+- **Bulk Scaffolding**: Create projects and multiple tasks in a single operation.
+- **Smart Dates**: Natural language date parsing (e.g., "remind me next Friday").
+- **Task Memory**: Full support for reading and writing task comments.
+- **Explicit Hierarchy**: Clear directional tools for subtasks and dependencies.
+
+```bash
+# Start via STDIO (for Claude Desktop)
+uv run vikunja-mcp
+
+# Start via SSE (HTTP)
+uv run vikunja-mcp dev --transport sse
+```
+
+## 🔒 Security & Auth Policy
+
+- **MCP Protocol**: The MCP server is strictly limited to **API Key Authentication**. We do not support user/password login via MCP to ensure secure, scoped agentic access.
+- **UI-Only Features**: Features like Buckets (Kanban columns) and Reactions currently require a JWT (UI Session). These are supported in the CLI but are excluded from the MCP server to maintain protocol security.
+
+## 🧪 Testing
+
+We use `testcontainers-python` to run integration tests against a live, ephemeral Vikunja instance. No mocks, just real API verification.
+
+```bash
+uv run pytest
+```
+
+## 🗺 Future Roadmap
+- [ ] **Backgrounds**: Support for Unsplash project backgrounds.
+- [ ] **Attachments**: File upload/download support.
+- [ ] **Webhooks**: Core models for receiving Vikunja events.
+- [ ] **Bulk Labels**: Tools for mass-tagging tasks.
+
+## 📜 License
+WTFPL - Do What the Fuck You Want to Public License.

vikunja_python-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "vikunja-python"
+version = "0.1.0"
+description = "API wrapper, CLI tool, and MCP server for Vikunja"
+authors = [
+    { name = "Your Name", email = "your.email@example.com" }
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "dateparser>=1.2.0",
+    "typer>=0.12.0",
+    "fastmcp>=0.1.0",
+]
+requires-python = ">=3.13.12"
+license = "WTFPL"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "testcontainers[mysql]>=4.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["vikunja_python*"]
+exclude = ["custom_components*", "tests*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[project.scripts]
+vikunja = "vikunja_python.cli.main:app"
+vikunja-mcp = "vikunja_python.mcp.server:main"
+

vikunja_python-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vikunja_python-0.1.0/tests/test_auth_integration.py

@@ -0,0 +1,40 @@
+import httpx
+import pytest
+from vikunja_python.core.models.base import Token
+
+@pytest.mark.asyncio
+async def test_full_auth_lifecycle(vikunja_auth):
+    """Test full authentication lifecycle using the ephemeral test container."""
+    VIKUNJA_URL = vikunja_auth["base_url"]
+    USERNAME = vikunja_auth["username"]
+    PASSWORD = vikunja_auth["password"]
+    
+    async with httpx.AsyncClient(follow_redirects=True) as client:
+        print("\n[1] Attempting Login...")
+        login_payload = {
+            "long_token": True,
+            "password": PASSWORD,
+            "username": USERNAME
+        }
+        login_resp = await client.post(f"{VIKUNJA_URL}/login", json=login_payload)
+        
+        assert login_resp.status_code == 200, f"Login failed: {login_resp.text}"
+        
+        # Validate Token model
+        token_data = login_resp.json()
+        token_obj = Token(**token_data)
+        assert token_obj.token is not None
+        print("✅ Login successful & Token validated")
+
+        print("\n[2] Attempting Token Refresh...")
+        refresh_resp = await client.get(f"{VIKUNJA_URL}/user/token/refresh", headers={"Authorization": f"Bearer {token_obj.token}"})
+        if refresh_resp.status_code == 200:
+             print("✅ Token refreshed successfully via GET.")
+             new_token_data = refresh_resp.json()
+             assert "token" in new_token_data
+        elif refresh_resp.status_code == 404:
+             print("⚠️  Refresh endpoint not found or incorrect method.")
+
+        print("\n[3] Attempting Logout...")
+        logout_resp = await client.post(f"{VIKUNJA_URL}/logout", headers={"Authorization": f"Bearer {token_obj.token}"})
+        assert logout_resp.status_code in [200, 204, 404]

vikunja_python-0.1.0/tests/test_cli_core.py

@@ -0,0 +1,60 @@
+import asyncio
+import os
+import pytest
+from vikunja_python.core.client import VikunjaClient
+from vikunja_python.core.models.task import Task
+from vikunja_python.core.models.project import Project
+
+@pytest.mark.asyncio
+async def test_cli_integration_basic(vikunja_auth):
+    """Verify that the CLI-facing core client works with the testcontainer."""
+    base_url = vikunja_auth["base_url"]
+    token = vikunja_auth["token"]
+    
+    async with VikunjaClient(base_url, token) as client:
+        # 1. Create a project
+        proj_data = await client.request("PUT", "/projects", json={"title": "CLI Project"})
+        project = Project(**proj_data)
+        assert project.title == "CLI Project"
+        
+        # 2. Create a task via client (simulating CLI action)
+        task_data = await client.request("PUT", f"/projects/{project.id}/tasks", json={"title": "CLI Task"})
+        task = Task(**task_data)
+        assert task.title == "CLI Task"
+        assert task.project_id == project.id
+        
+        # 4. Update task
+        update_data = await client.request("POST", f"/tasks/{task.id}", json={"done": True})
+        assert update_data["done"] is True
+        
+        # 5. Create another task for relationship
+        task2_data = await client.request("PUT", f"/projects/{project.id}/tasks", json={"title": "Task 2"})
+        task2 = Task(**task2_data)
+        
+        # 6. Create relationship
+        rel_data = await client.request("PUT", f"/tasks/{task.id}/relations", json={
+            "other_task_id": task2.id,
+            "relation_kind": "subtask"
+        })
+        assert rel_data["other_task_id"] == task2.id
+        
+        # 7. Delete tasks
+        await client.request("DELETE", f"/tasks/{task.id}")
+        await client.request("DELETE", f"/tasks/{task2.id}")
+        
+        # Verify deletion
+        check = await client.request("GET", f"/tasks/{task.id}")
+        assert check["status_code"] == 404
+
+@pytest.mark.asyncio
+async def test_error_handling_structured(vikunja_auth):
+    """Verify that the client returns structured error data instead of crashing."""
+    base_url = vikunja_auth["base_url"]
+    token = vikunja_auth["token"]
+    
+    async with VikunjaClient(base_url, token) as client:
+        # Request non-existent project
+        data = await client.request("GET", "/projects/999999")
+        assert "error" in data
+        assert data["status_code"] == 404
+        assert "details" in data

vikunja_python-0.1.0/tests/test_container.py

@@ -0,0 +1,26 @@
+import pytest
+import httpx
+from vikunja_python.core.models.user import User
+
+@pytest.mark.asyncio
+async def test_container_running(vikunja_server):
+    """Test that the container is reachable via HTTP."""
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(f"{vikunja_server}/info")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "version" in data
+
+@pytest.mark.asyncio
+async def test_auth_works(vikunja_auth):
+    """Test that authentication provides a valid token."""
+    assert vikunja_auth["token"] is not None
+    assert vikunja_auth["username"] is not None
+
+@pytest.mark.asyncio
+async def test_authenticated_client(async_client):
+    """Test that the authenticated client can fetch the current user."""
+    resp = await async_client.get("/user")
+    assert resp.status_code == 200
+    user = User(**resp.json())
+    assert user.id > 0

vikunja_python-0.1.0/tests/test_phase6_integration.py

@@ -0,0 +1,122 @@
+import pytest
+from vikunja_python.core.models.phase6_medium import (
+    Bucket, BucketCreateRequest, BucketUpdateRequest, BucketMoveRequest,
+    ReactionKind, Reaction, ReactionMapEntry, ReactionCreateRequest,
+    SubscriptionType, Subscription, SubscriptionCreateRequest
+)
+from vikunja_python.core.models.project import Project
+
+@pytest.mark.asyncio
+async def test_project_lifecycle(async_client):
+    """CRUD lifecycle for Project to validate model"""
+    # 1. Create
+    project_data = {"title": "Hermes Test Project"}
+    resp = await async_client.put("/projects", json=project_data)
+    assert resp.status_code in [200, 201]
+    
+    new_project_json = resp.json()
+    project_id = new_project_json['id']
+    
+    project_obj = Project(**new_project_json)
+    assert project_obj.id == project_id
+    
+    # 2. Get
+    resp = await async_client.get(f"/projects/{project_id}")
+    assert resp.status_code == 200
+    Project(**resp.json())
+
+    # 3. Delete
+    resp = await async_client.delete(f"/projects/{project_id}")
+    assert resp.status_code in [200, 204]
+
+@pytest.mark.asyncio
+async def test_bucket_lifecycle(async_client):
+    """CRUD lifecycle for Bucket"""
+    # 1. Create Project for bucket
+    project_data = {"title": "Project for Bucket Test"}
+    resp = await async_client.put("/projects", json=project_data)
+    assert resp.status_code in [200, 201]
+    project_id = resp.json()['id']
+    
+    # Vikunja buckets need a view
+    # A view is automatically created for a project. Let's get the views.
+    resp = await async_client.get(f"/projects/{project_id}/views")
+    assert resp.status_code == 200
+    views = resp.json()
+    assert len(views) > 0
+    view_id = views[0]['id']
+    
+    # 2. Create Bucket
+    bucket_payload = {"title": "Hermes Test Column"}
+    resp = await async_client.put(f"/projects/{project_id}/views/{view_id}/buckets", json=bucket_payload)
+    assert resp.status_code in [200, 201]
+    
+    new_bucket_json = resp.json()
+    bucket_id = new_bucket_json['id']
+    Bucket(**new_bucket_json)
+
+    # Create a second bucket so we can delete the first one without a 412 precondition error
+    await async_client.put(f"/projects/{project_id}/views/{view_id}/buckets", json={"title": "Keep Column"})
+    
+    # 3. Update
+    update_payload = {"title": "Hermes Updated Column"}
+    resp = await async_client.post(f"/projects/{project_id}/views/{view_id}/buckets/{bucket_id}", json=update_payload)
+    assert resp.status_code == 200
+    Bucket(**resp.json())
+
+    # 4. Delete
+    resp = await async_client.delete(f"/projects/{project_id}/views/{view_id}/buckets/{bucket_id}")
+    assert resp.status_code in [200, 204]
+    
+@pytest.mark.asyncio
+async def test_reaction_lifecycle(async_client):
+    """CRUD lifecycle for Reaction"""
+    # 1. Create Project and Task
+    project_data = {"title": "Project for Reaction Test"}
+    resp = await async_client.put("/projects", json=project_data)
+    project_id = resp.json()['id']
+    
+    task_payload = {"title": "Task for Reaction", "project_id": project_id}
+    resp = await async_client.put(f"/projects/{project_id}/tasks", json=task_payload)
+    assert resp.status_code in [200, 201], f"Failed to create task: {resp.text}"
+    task_id = resp.json()['id']
+    
+    # 2. Create Reaction
+    reaction_payload = {"value": "❤️"}
+    # Note: Vikunja spec says PUT /tasks/{id}/reactions
+    resp = await async_client.put(f"/tasks/{task_id}/reactions", json=reaction_payload)
+    
+    assert resp.status_code in [200, 201], f"Reaction failed: {resp.text}"
+    new_reaction_json = resp.json()
+    Reaction(**new_reaction_json)
+    
+    # 3. Delete Reaction
+    resp = await async_client.post(f"/tasks/{task_id}/reactions/delete", json={"value": "❤️"})
+    assert resp.status_code in [200, 204]
+
+@pytest.mark.asyncio
+async def test_subscription_lifecycle(async_client):
+    """CRUD lifecycle for Subscription"""
+    # 1. Create Project and Task
+    project_data = {"title": "Project for Sub Test"}
+    resp = await async_client.put("/projects", json=project_data)
+    project_id = resp.json()['id']
+    
+    task_payload = {"title": "Task for Sub Test", "project_id": project_id}
+    resp = await async_client.put(f"/projects/{project_id}/tasks", json=task_payload)
+    task_id = resp.json()['id']
+    
+    # 2. Create Subscription
+    # The spec actually says PUT /subscriptions/task/{entityID}
+    resp = await async_client.put(f"/subscriptions/task/{task_id}")
+    
+    if resp.status_code == 200:
+        new_sub_json = resp.json()
+        Subscription(**new_sub_json)
+    else:
+        # Some versions just return 204 on PUT
+        assert resp.status_code in [200, 201, 204], f"Subscription failed: {resp.text}"
+    
+    # 3. Delete Subscription
+    resp = await async_client.delete(f"/subscriptions/task/{task_id}")
+    assert resp.status_code in [200, 204]

vikunja_python-0.1.0/tests/test_task_hierarchy_integration.py

@@ -0,0 +1,165 @@
+import pytest
+from vikunja_python.core.models.task import Task
+from vikunja_python.core.models.label import Label, LabelCreateRequest
+
+@pytest.mark.asyncio
+async def test_task_hierarchy_and_labels_integration(async_client):
+    """
+    Mandatory integration test for Phase 6 enhancements:
+    1. Label creation
+    2. Hierarchical task creation (subtasks)
+    3. Detailed listing with expansion
+    """
+    # 1. Create a Label
+    label_payload = {"title": "IntegrationTest", "hex_color": "#ff00ff"}
+    resp = await async_client.put("/labels", json=label_payload)
+    assert resp.status_code in [200, 201]
+    label_id = resp.json()["id"]
+    
+    # 2. Create a Project
+    proj_resp = await async_client.put("/projects", json={"title": "Hierarchy Project"})
+    assert proj_resp.status_code in [200, 201]
+    project_id = proj_resp.json()["id"]
+    
+    # 3. Create Parent Task
+    parent_resp = await async_client.put(f"/projects/{project_id}/tasks", json={"title": "Parent Task"})
+    assert parent_resp.status_code in [200, 201]
+    parent_id = parent_resp.json()["id"]
+    
+    # 4. Create Subtask using the relation endpoint
+    sub_resp = await async_client.put(f"/projects/{project_id}/tasks", json={"title": "Child Task"})
+    assert sub_resp.status_code in [200, 201]
+    child_id = sub_resp.json()["id"]
+    
+    # Create the subtask relationship
+    rel_payload = {"other_task_id": child_id, "relation_kind": "subtask"}
+    rel_resp = await async_client.put(f"/tasks/{parent_id}/relations", json=rel_payload)
+    assert rel_resp.status_code in [200, 201]
+    
+    # 5. Add label to Parent
+    await async_client.put(f"/tasks/{parent_id}/labels", json={"label_id": label_id})
+    
+    # 6. Test list_tasks with expansion (The core of the enhancement)
+    # GET /projects/{id}/tasks?expand=subtasks
+    list_resp = await async_client.get(f"/projects/{project_id}/tasks", params={"expand": ["subtasks"]})
+    assert list_resp.status_code == 200
+    tasks_data = list_resp.json()
+
+    # Use the Task model to parse the response
+    tasks = [Task(**item) for item in tasks_data]
+    parent_task = next((t for t in tasks if t.id == parent_id), None)
+
+    assert parent_task is not None
+    assert len(parent_task.subtasks) == 1
+    assert parent_task.subtasks[0].id == child_id
+    assert parent_task.subtasks[0].title == "Child Task"
+
+    # 7. Verify Labels are present (v2.3.0 returns them by default)
+    assert len(parent_task.labels) == 1
+    assert parent_task.labels[0].id == label_id
+    assert parent_task.labels[0].hex_color == "#ff00ff"
+
+@pytest.mark.asyncio
+async def test_pagination_integration(async_client):
+    """Verify that pagination parameters are respected."""
+    # Create a project and 3 tasks
+    proj_resp = await async_client.put("/projects", json={"title": "Pagination Project"})
+    project_id = proj_resp.json()["id"]
+    
+    for i in range(3):
+        await async_client.put(f"/projects/{project_id}/tasks", json={"title": f"Task {i}"})
+        
+    # List with per_page=2
+    list_resp = await async_client.get("/tasks", params={"per_page": 2, "filter": f"project_id = {project_id}"})
+    assert list_resp.status_code == 200
+    assert len(list_resp.json()) == 2
+    
+    # Check headers for pagination info (as defined in base.py/task.py)
+    assert "x-pagination-total-pages" in list_resp.headers
+    assert int(list_resp.headers["x-pagination-total-pages"]) >= 2
+
+@pytest.mark.asyncio
+async def test_expand_parameter_sanitization(async_client, vikunja_auth):
+    """
+    Verify that the MCP list_tasks tool correctly sanitizes the expand parameter
+    to prevent 412 Precondition Failed errors from the Vikunja API.
+    """
+    # 1. Create a Project
+    proj_resp = await async_client.put("/projects", json={"title": "Expand Test Project"})
+    assert proj_resp.status_code in [200, 201]
+    project_id = proj_resp.json()["id"]
+    
+    # 2. Call the raw API with an invalid expand parameter to prove it fails (412)
+    raw_resp = await async_client.get("/tasks", params={"expand": ["labels", "invalid_field"]})
+    assert raw_resp.status_code == 412
+    
+    # 3. Import and call the MCP tool function directly to test its sanitization logic
+    from vikunja_python.mcp.server import list_tasks
+    import os
+    
+    # Set env vars temporarily for the tool's get_client() call
+    os.environ["VIKUNJA_URL"] = vikunja_auth["base_url"]
+    os.environ["VIKUNJA_API_TOKEN"] = vikunja_auth["token"]
+    
+    # Call tool with invalid 'labels' and valid 'subtasks'
+    # The tool should filter out 'labels' and send only 'subtasks', returning 200 OK.
+    result = await list_tasks(project_id=project_id, expand=["labels", "subtasks"])
+    
+    # If it failed with 412, result would start with "Error fetching tasks: 412" or similar
+    assert "Error fetching tasks" not in result
+    assert "No tasks found" in result or "ID:" in result # Should succeed (return empty string or tasks)
+    
+    # 4. Call tool with ONLY invalid params
+    # The tool should filter all out and send no expand param at all, returning 200 OK.
+    result2 = await list_tasks(project_id=project_id, expand=["labels", "invalid_field"])
+    assert "Error fetching tasks" not in result2
+    assert "No tasks found" in result2 or "ID:" in result2
+
+@pytest.mark.asyncio
+async def test_invalid_expand_sanitization_v2(async_client, vikunja_auth):
+    """
+    Explicitly verify that 'attachments', 'reminders', and 'assignees' 
+    are sanitized out to prevent 412 errors.
+    """
+    from vikunja_python.mcp.server import list_tasks
+    import os
+    
+    os.environ["VIKUNJA_URL"] = vikunja_auth["base_url"]
+    os.environ["VIKUNJA_API_TOKEN"] = vikunja_auth["token"]
+    
+    # These three specifically caused 412 errors in the wild
+    invalid_expands = ["attachments", "reminders", "assignees"]
+    
+    # Call tool with these invalid expands
+    # If sanitization fails, the API will return 412 and the tool will return an error string.
+    result = await list_tasks(expand=invalid_expands)
+    
+    assert "Error fetching tasks: 412" not in result
+    assert "Error fetching tasks" not in result
+
+@pytest.mark.asyncio
+async def test_get_task_expansion_integration(async_client, vikunja_auth):
+    """Verify that get_task supports full expansion including attachments/reminders."""
+    from vikunja_python.mcp.server import get_task
+    import os
+    
+    os.environ["VIKUNJA_URL"] = vikunja_auth["base_url"]
+    os.environ["VIKUNJA_API_TOKEN"] = vikunja_auth["token"]
+
+    # 1. Create a task with a description
+    proj_resp = await async_client.put("/projects", json={"title": "GetTask Project"})
+    project_id = proj_resp.json()["id"]
+    task_resp = await async_client.put(f"/projects/{project_id}/tasks", json={"title": "Detailed Task", "description": "Full details here"})
+    task_id = task_resp.json()["id"]
+    
+    # 2. Test get_task with expansion
+    # Note: We can't easily upload attachments in this test without more setup, 
+    # but we can verify the API call doesn't 412.
+    result = await get_task(task_id=task_id, expand=["attachments", "reminders", "assignees", "comments"])
+    
+    assert "Error fetching task" not in result
+    assert "ID: " in result
+    assert "Full details here" in result
+    assert "Detailed Task" in result
+
+

vikunja_python-0.1.0/tests/test_task_models_unit.py

@@ -0,0 +1,73 @@
+import pytest
+from vikunja_python.core.models.task import Task
+from vikunja_python.core.models.base import Label
+
+def test_task_model_with_subtasks():
+    """Verify that the Task model can handle nested subtasks."""
+    subtask_data = {
+        "id": 2,
+        "title": "Subtask 1",
+        "identifier": "#2",
+        "project_id": 1,
+        "done": False,
+        "created": "2026-05-05T12:00:00Z",
+        "updated": "2026-05-05T12:00:00Z"
+    }
+    
+    task_data = {
+        "id": 1,
+        "title": "Parent Task",
+        "identifier": "#1",
+        "project_id": 1,
+        "done": False,
+        "created": "2026-05-05T12:00:00Z",
+        "updated": "2026-05-05T12:00:00Z",
+        "subtasks": [subtask_data]
+    }
+    
+    task = Task(**task_data)
+    assert task.id == 1
+    assert len(task.subtasks) == 1
+    assert task.subtasks[0].id == 2
+    assert task.subtasks[0].title == "Subtask 1"
+
+def test_task_model_with_labels():
+    """Verify that the Task model handles expanded labels."""
+    label_data = {
+        "id": 10,
+        "title": "Urgent",
+        "hex_color": "ff0000",
+        "created": "2026-05-05T12:00:00Z",
+        "updated": "2026-05-05T12:00:00Z"
+    }
+    
+    task_data = {
+        "id": 1,
+        "title": "Task with labels",
+        "identifier": "#1",
+        "project_id": 1,
+        "done": False,
+        "created": "2026-05-05T12:00:00Z",
+        "updated": "2026-05-05T12:00:00Z",
+        "labels": [label_data]
+    }
+    
+    task = Task(**task_data)
+    assert len(task.labels) == 1
+    assert task.labels[0].title == "Urgent"
+    assert task.labels[0].hex_color == "#ff0000"
+
+def test_label_model_validation():
+    """Test label model validation (hex color format)."""
+    # Both models now normalize to include # prefix
+    
+    from vikunja_python.core.models.base import Label as BaseLabel
+    l1 = BaseLabel(id=1, title="test", hex_color="ff0000", created="2026-05-05T12:00:00Z", updated="2026-05-05T12:00:00Z")
+    assert l1.hex_color == "#ff0000"
+    
+    from vikunja_python.core.models.label import Label as FullLabel
+    l2 = FullLabel(id=1, title="test", hex_color="#ff0000")
+    assert l2.hex_color == "#ff0000"
+    
+    with pytest.raises(ValueError):
+        FullLabel(id=1, title="test", hex_color="invalid")