vikunja-python 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

vikunja_python-0.1.2.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: vikunja-python
+Version: 0.1.2
+Summary: API wrapper, CLI tool, and MCP server for Vikunja
+Author-email: Your Name <your.email@example.com>
+License-Expression: WTFPL
+Project-URL: Homepage, https://github.com/oedo808/vikunja-python
+Project-URL: Repository, https://github.com/oedo808/vikunja-python
+Project-URL: Documentation, https://github.com/oedo808/vikunja-python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+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
+
+Python API wrapper, CLI tool, MCP server, and Home Assistant integration for the [Vikunja](https://vikunja.io/) task management system.
+
+Built for Python 3.13 with httpx, pydantic v2, fastmcp, and typer.
+
+## Architecture
+
+The project is structured into layers:
+
+- **core/** -- Pydantic models, async HTTP client (httpx), error handling, API token and JWT authentication
+- **cli/** -- Rich CLI built with typer and rich (task CRUD, project views, saved filter queries, dashboard summary)
+- **mcp/** -- MCP server for agentic AI workflows (13 tools including list_tasks, get_task, create_task, list_saved_filter, task_summary)
+- **custom_components/vikunja/** -- Home Assistant HACS integration (config flow, 3 sensors for saved filters)
+
+## Getting Started
+
+### Installation
+
+From PyPI:
+
+```bash
+pip install vikunja-python
+```
+
+Or with uv:
+
+```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"
+VIKUNJA_DEBUG="true"   # Enable verbose stderr logging
+```
+
+## Features
+
+### CLI (vikunja)
+
+The CLI provides a human-friendly interface for managing tasks:
+
+- list-tasks -- List tasks with rich table output (supports saved filters via negative project IDs)
+- list-saved-filter -- Query saved filters (e.g., -2 for Due in 3 Days, -3 for Overdue, -4 for Due Today)
+- summary -- Quick dashboard summary across all saved filters (parallel queries, optimized for ePaper dashboards)
+- get-project -- Project details and views
+- list-view-tasks -- List tasks from a specific project view
+- get-task -- Full task details with description
+- create-task -- Create a new task
+- create-label -- Create a new label
+
+```bash
+uv run vikunja list-tasks
+uv run vikunja list-saved-filter --filter-id -2
+uv run vikunja summary --top 5
+```
+
+### MCP Server (vikunja-mcp)
+
+MCP server for agentic workflows. 13 tools including:
+
+- list_tasks, get_task, create_task, update_task, complete_task, delete_task
+- list_saved_filter -- Query saved filters (e.g., -2 for Due in 3 Days)
+- task_summary -- Dashboard summary across all filters in one parallel call
+- list_projects, get_project, list_project_view_tasks
+- list_labels, create_label
+- add_subtask, add_task_link
+
+```bash
+uv run vikunja-mcp
+```
+
+### Home Assistant Integration
+
+The package includes a HACS-ready custom component for Home Assistant:
+
+- Config flow: URL + API token via the HA UI
+- 3 sensors: Overdue, Due Today, Due in 3 Days (from Vikunja saved filters)
+- Each sensor: state = task count, attributes = task list with IDs, titles, due dates
+- Coordinator polls all filters in parallel every 5 minutes
+
+Copy `custom_components/vikunja/` to your HA config's `custom_components/` directory, restart HA, and add via Settings -> Devices & Services.
+
+## Saved Filter Support
+
+Vikunja saved filters are accessed via negative project IDs:
+
+| ID | Filter |
+|----|--------|
+| -2 | Due in 3 Days |
+| -3 | Overdue |
+| -4 | Due Today |
+
+The API route is `GET /tasks?project_id=-2` (NOT `/projects/-2/tasks`).
+
+## Testing
+
+Unit tests run without Docker:
+
+```bash
+uv run pytest tests/test_task_models_unit.py tests/test_label_model_validation.py -v
+```
+
+Integration tests require Docker (spins up a real Vikunja instance via testcontainers):
+
+```bash
+uv run pytest
+```
+
+## Security & Auth
+
+- API Key auth is the primary authentication method for both CLI and MCP server
+- JWT tokens are used for UI-specific features (kanban buckets, reactions) in the CLI only
+- The MCP server only supports API key authentication
+
+## License
+
+WTFPL - Do What the Fuck You Want to Public License.

{vikunja_python-0.1.0.dist-info → vikunja_python-0.1.2.dist-info}/RECORD

@@ -21,8 +21,8 @@ vikunja_python/core/models/user.py,sha256=ETOV31K9rjIXeMhjSEu2xzroFh8PouVY2fcMi6
 vikunja_python/core/models/webhook.py,sha256=debhzsM4Y_wKrMvS64LLdj2WlLN8G5jll9WBhPIj1Tg,9338
 vikunja_python/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 vikunja_python/mcp/server.py,sha256=0JSVpoT-JlyNtu3k8-0hI03k7tYb3YLlWxCrEgd8THw,31680
-vikunja_python-0.1.0.dist-info/METADATA,sha256=w1k0RIMfwK5jwG4tavoqu9teAaea7H4h8D_yCvMW6YE,554
-vikunja_python-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-vikunja_python-0.1.0.dist-info/entry_points.txt,sha256=pXGwoqxBR9cEnBo9t31b-0mPxz0ztVu79p_YvHBkVT0,101
-vikunja_python-0.1.0.dist-info/top_level.txt,sha256=sWuGn_X83F5Q5auXGSc8Pm0aJbp61_7yMCa2EImJtK4,15
-vikunja_python-0.1.0.dist-info/RECORD,,
+vikunja_python-0.1.2.dist-info/METADATA,sha256=n5j1PzRDKLsyIy427uEL7_iQc6qo2xDY2mG4zhyO3ew,4492
+vikunja_python-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vikunja_python-0.1.2.dist-info/entry_points.txt,sha256=pXGwoqxBR9cEnBo9t31b-0mPxz0ztVu79p_YvHBkVT0,101
+vikunja_python-0.1.2.dist-info/top_level.txt,sha256=sWuGn_X83F5Q5auXGSc8Pm0aJbp61_7yMCa2EImJtK4,15
+vikunja_python-0.1.2.dist-info/RECORD,,

vikunja_python-0.1.0.dist-info/METADATA

@@ -1,16 +0,0 @@
-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"