voodoo-framework 1.0.0__tar.gz

voodoo_framework-1.0.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: voodoo-framework
+Version: 1.0.0
+Summary: Voodoo Framework
+Requires-Python: >=3.12
+Requires-Dist: starlette
+Requires-Dist: uvicorn
+Requires-Dist: pydantic
+Requires-Dist: aiosqlite
+Requires-Dist: websockets
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: openai
+Requires-Dist: aiofiles
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"

voodoo_framework-1.0.0/README.md

@@ -0,0 +1,78 @@
+# Voodoo Framework 🪄
+
+**The Modern, Full-Stack Async Python Web Framework.**
+
+Voodoo is an ultra-minimalist, high-performance web framework designed for the AI era. Built on top of Starlette and Uvicorn, it offers a seamless, reactive developer experience by combining a React-like component system in pure Python with robust backend features like background queues, real-time websockets, LLM agents, and built-in SQLite persistence.
+
+## ✨ Features
+
+- **Component-Driven UI**: Build modern, reactive UIs using pure Python components (`Div`, `Card`, `Button`, `Text`) with TailwindCSS integration out of the box. No writing raw HTML/JS required.
+- **Real-Time WebSockets**: Live updates pushed seamlessly to the client with minimal configuration.
+- **Data Persistence**: Built-in async SQLite (`aiosqlite`) ORM using Pydantic models with Row-Level Security (RLS) policies.
+- **Background Workers**: Native task queues for heavy processing, ideal for AI/LLM workloads.
+- **AI Native**: Built-in support for LLM Agents and the Model Context Protocol (MCP).
+- **Observability**: Integrated Telemetry and APM tracing module tracking latencies, metrics, and AI token usage.
+- **Zero Config**: `pyproject.toml` based, zero-configuration setup, hot-reloading, and out-of-the-box smart documentation.
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Python 3.12+
+- `pip`
+
+### Installation
+
+Clone the repository and install the framework in editable mode with development dependencies:
+
+```bash
+git clone https://github.com/your-org/voodoo-framework.git
+cd voodoo-framework
+pip install -e .[dev]
+```
+
+### Running the App
+
+Start the development server using the CLI:
+
+```bash
+voodoo dev
+```
+
+The application will start on `http://localhost:8000`. 
+Check out the built-in Smart Documentation at `http://localhost:8000/docs` to see all available components and APIs.
+
+## 📖 Smart Documentation
+
+Voodoo ships with its own interactive documentation built using the framework itself. When you run the application, navigate to `/docs` in your browser to view:
+
+- Component Library References
+- API Integration Guides
+- Framework Telemetry Status
+- Live Examples
+
+## 🛠 Project Structure
+
+```
+voodoo-framework/
+├── app/               # Your application code
+│   ├── pages/         # File-based routing (index.py, docs.py)
+│   ├── layout.py      # Main layout component
+│   ├── models.py      # Pydantic data models
+│   └── workers.py     # Background task handlers
+├── voodoo/            # Framework core source
+├── tests/             # Pytest async test suite
+└── pyproject.toml     # Project metadata and dependencies
+```
+
+## 🧪 Testing
+
+Run the test suite using `pytest`:
+
+```bash
+pytest
+```
+
+## 📜 License
+
+MIT License. See `LICENSE` for more information.

voodoo_framework-1.0.0/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voodoo-framework"
+version = "1.0.0"
+description = "Voodoo Framework"
+requires-python = ">=3.12"
+dependencies = [
+    "starlette",
+    "uvicorn",
+    "pydantic",
+    "aiosqlite",
+    "websockets",
+    "httpx",
+    "python-dotenv",
+    "pyyaml",
+    "typer",
+    "rich",
+    "openai",
+    "aiofiles"
+]
+
+[project.scripts]
+voodoo = "voodoo.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "ruff",
+    "mypy",
+    "pre-commit"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["voodoo*", "app*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "venv",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "C",  # flake8-comprehensions
+    "B",  # flake8-bugbear
+    "UP", # pyupgrade
+]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = false
+no_implicit_optional = true
+strict_optional = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false

voodoo_framework-1.0.0/setup.cfg

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

voodoo_framework-1.0.0/tests/test_components.py

@@ -0,0 +1,53 @@
+import pytest
+from voodoo.components import Component, Div, Button, Input, Card, Text, Heading, ChatBox, Table
+
+def test_component_base():
+    comp = Component("Hello", id="test-1", className="bg-red-500", data_custom="value")
+    html = comp.render()
+    assert html == '<div id="test-1" class="bg-red-500" data-custom="value">Hello</div>'
+
+def test_div():
+    div = Div("Content", id="d1")
+    assert div.render() == '<div id="d1">Content</div>'
+
+def test_button():
+    btn = Button("Click Me", id="btn-1", on_click="my_action")
+    html = btn.render()
+    assert html == '<button id="btn-1" onclick="voodoo.sendEvent(\'my_action\', this.id, this.value)">Click Me</button>'
+
+def test_input():
+    inp = Input(id="inp-1", on_change="input_changed", type="text")
+    html = inp.render()
+    assert html == '<input id="inp-1" type="text" onchange="voodoo.sendEvent(\'input_changed\', this.id, this.value)" />'
+
+def test_card():
+    card = Card("Card Content", id="card-1", className="extra-class")
+    html = card.render()
+    assert html == '<div id="card-1" class="bg-[var(--color-surface)] border border-[var(--color-border)] rounded-xl p-6 shadow-xl extra-class">Card Content</div>'
+
+def test_text():
+    text = Text("Span Text", id="txt-1")
+    assert text.render() == '<span id="txt-1">Span Text</span>'
+
+def test_heading():
+    h1 = Heading("H1 Title", id="h-1")
+    assert h1.render() == '<h1 id="h-1">H1 Title</h1>'
+    
+    h3 = Heading("H3 Title", id="h-3", level=3)
+    assert h3.render() == '<h3 id="h-3">H3 Title</h3>'
+
+def test_chatbox():
+    box = ChatBox("Messages", id="chat-1")
+    assert box.render() == '<div id="chat-1" class="flex flex-col space-y-2 overflow-y-auto">Messages</div>'
+
+def test_table():
+    table = Table(
+        headers=["Name", "Age"],
+        rows=[["Alice", 30], ["Bob", 25]],
+        id="tbl-1",
+        className="my-table"
+    )
+    html = table.render()
+    assert html.startswith('<table id="tbl-1" class="my-table">')
+    assert '<th class="px-6 py-4 text-left text-xs font-medium text-[var(--color-text-muted)] uppercase tracking-wider">Name</th>' in html
+    assert '<td class="px-6 py-4 whitespace-nowrap text-sm text-[var(--color-text)]">Alice</td>' in html

voodoo_framework-1.0.0/tests/test_data.py

@@ -0,0 +1,95 @@
+import pytest
+import pytest_asyncio
+import asyncio
+from voodoo.data import BaseModel, on_insert, on_update, rls_policy
+
+class User(BaseModel):
+    name: str
+    age: int
+    is_active: bool
+
+class Post(BaseModel):
+    title: str
+    content: str
+    user_id: int
+
+inserted_users = []
+updated_users = []
+
+@on_insert(User)
+async def hook_insert_user(user):
+    inserted_users.append(user.name)
+
+@on_update(User)
+def hook_update_user(user):
+    updated_users.append(user.name)
+
+@rls_policy(Post)
+def post_policy(context):
+    if context.get("role") == "admin":
+        return None
+    return f"user_id = {context.get('user_id', 0)}"
+
+@pytest_asyncio.fixture(autouse=True)
+async def clear_db(test_db):
+    await test_db.execute("DELETE FROM user")
+    await test_db.execute("DELETE FROM post")
+    await test_db.commit()
+
+@pytest.mark.asyncio
+async def test_orm_operations(test_db):
+    # Insert
+    u = User()
+    u.name = "Alice"
+    u.age = 30
+    u.is_active = True
+    await u.insert()
+    
+    assert u.id is not None
+    
+    # Wait for the async trigger to execute
+    await asyncio.sleep(0.01)
+    assert "Alice" in inserted_users
+    
+    # Find all
+    users = await User.find_all()
+    assert len(users) == 1
+    assert users[0].name == "Alice"
+    assert users[0].age == 30
+    assert users[0].is_active is True
+    
+    # Update
+    u.age = 31
+    await u.update()
+    
+    # Wait for the sync trigger to execute (called directly in update)
+    await asyncio.sleep(0.01)
+    assert "Alice" in updated_users
+    
+    users = await User.find_all()
+    assert users[0].age == 31
+
+@pytest.mark.asyncio
+async def test_rls_policies(test_db):
+    p1 = Post()
+    p1.title = "Hello"
+    p1.content = "World"
+    p1.user_id = 1
+    await p1.insert()
+    
+    p2 = Post()
+    p2.title = "Secret"
+    p2.content = "Admin only"
+    p2.user_id = 2
+    await p2.insert()
+    
+    # User 1 context
+    user_context = {"user_id": 1, "role": "user"}
+    posts = await Post.find_all(user_context=user_context)
+    assert len(posts) == 1
+    assert posts[0].title == "Hello"
+    
+    # Admin context
+    admin_context = {"user_id": 99, "role": "admin"}
+    all_posts = await Post.find_all(user_context=admin_context)
+    assert len(all_posts) == 2

voodoo_framework-1.0.0/tests/test_i18n.py

@@ -0,0 +1,73 @@
+import os
+import json
+import pytest
+from starlette.testclient import TestClient
+from starlette.applications import Starlette
+from starlette.routing import Route
+from starlette.responses import PlainTextResponse
+
+from voodoo.i18n import I18n, _, current_language, I18nMiddleware
+
+@pytest.fixture
+def mock_locales(tmp_path):
+    locales_dir = tmp_path / "locales"
+    locales_dir.mkdir()
+    
+    en_data = {"hello": "Hello", "nested": {"key": "Value {name}"}}
+    pt_data = {"hello": "Olá", "nested": {"key": "Valor {name}"}}
+    
+    (locales_dir / "en.json").write_text(json.dumps(en_data), encoding="utf-8")
+    (locales_dir / "pt.json").write_text(json.dumps(pt_data), encoding="utf-8")
+    
+    return str(locales_dir)
+
+def test_i18n_loading(mock_locales):
+    i18n = I18n(locales_dir=mock_locales)
+    
+    assert i18n.get_translation("en", "hello") == "Hello"
+    assert i18n.get_translation("pt", "hello") == "Olá"
+    
+    # Fallback to default
+    assert i18n.get_translation("es", "hello") == "Hello"
+    
+    # Missing key
+    assert i18n.get_translation("en", "missing.key") == "missing.key"
+    
+    # Interpolation
+    assert i18n.get_translation("en", "nested.key", name="World") == "Value World"
+    assert i18n.get_translation("pt", "nested.key", name="Mundo") == "Valor Mundo"
+
+def test_i18n_middleware(mock_locales):
+    i18n = I18n(locales_dir=mock_locales)
+    
+    async def homepage(request):
+        # We temporarily override the global i18n_instance in the test
+        # but here we can just use the context var directly
+        import voodoo.i18n
+        voodoo.i18n.i18n_instance = i18n
+        
+        return PlainTextResponse(f"Lang: {current_language.get()} - Msg: {_('hello')}")
+        
+    app = Starlette(routes=[Route("/", homepage)])
+    app.add_middleware(I18nMiddleware, i18n=i18n)
+    
+    client = TestClient(app)
+    
+    # 1. Default
+    resp = client.get("/")
+    assert resp.text == "Lang: en - Msg: Hello"
+    
+    # 2. Accept-Language header
+    resp = client.get("/", headers={"Accept-Language": "pt-BR,pt;q=0.9,en-US;q=0.8"})
+    assert resp.text == "Lang: pt - Msg: Olá"
+    
+    # 3. Cookie
+    client.cookies = {"voodoo_lang": "pt"}
+    resp = client.get("/")
+    assert resp.text == "Lang: pt - Msg: Olá"
+    
+    # 4. Query Param
+    resp = client.get("/?lang=en")
+    assert resp.text == "Lang: en - Msg: Hello"
+    # Query param sets the cookie
+    assert "voodoo_lang=en" in resp.headers.get("set-cookie", "")

voodoo_framework-1.0.0/tests/test_queue.py

@@ -0,0 +1,35 @@
+import pytest
+import asyncio
+from voodoo.queue import queue, enqueue, start_workers, stop_workers
+
+processed_items = []
+
+@queue("test_queue")
+async def process_item(payload):
+    processed_items.append(payload)
+
+@queue("sync_queue")
+def process_sync_item(payload):
+    processed_items.append(f"sync-{payload}")
+
+@pytest.mark.asyncio
+async def test_queue_workers():
+    processed_items.clear()
+    
+    # Enqueue items
+    await enqueue("test_queue", "item1")
+    await enqueue("test_queue", "item2")
+    await enqueue("sync_queue", "item3")
+    
+    # Start workers
+    await start_workers()
+    
+    # Allow workers to process the queue
+    await asyncio.sleep(0.1)
+    
+    # Stop workers
+    await stop_workers()
+    
+    assert "item1" in processed_items
+    assert "item2" in processed_items
+    assert "sync-item3" in processed_items

voodoo_framework-1.0.0/tests/test_theme.py

@@ -0,0 +1,33 @@
+import pytest
+from voodoo.theme import Theme, ThemeColors, set_theme, default_theme
+
+def test_default_theme():
+    assert default_theme.mode == "dark"
+    assert default_theme.colors.primary == "#007AFF"
+
+def test_custom_theme():
+    custom_colors = ThemeColors(primary="#FF0000", extra={"custom": "#00FF00"})
+    theme = Theme(mode="light", colors=custom_colors)
+    
+    assert theme.mode == "light"
+    assert theme.colors.primary == "#FF0000"
+    
+    css_vars = theme.to_css_variables()
+    assert "--color-primary: #FF0000;" in css_vars
+    assert "--color-custom: #00FF00;" in css_vars
+    
+    tw_config = theme.to_tailwind_config()
+    assert '"primary": "#FF0000"' in tw_config
+    assert '"custom": "#00FF00"' in tw_config
+
+def test_set_theme():
+    original_theme = default_theme
+    try:
+        new_theme = Theme(mode="light")
+        set_theme(new_theme)
+        
+        # In voodoo.theme namespace, default_theme should be updated
+        import voodoo.theme
+        assert voodoo.theme.default_theme.mode == "light"
+    finally:
+        set_theme(original_theme)

voodoo_framework-1.0.0/tests/test_websocket.py

@@ -0,0 +1,52 @@
+import pytest
+import json
+from voodoo.core import register_event, ws_manager
+
+def test_websocket_event(client):
+    received = []
+    
+    async def async_dummy_handler(element_id, value):
+        received.append((element_id, value))
+        await ws_manager.broadcast_patch("target-1", "<b>Updated</b>")
+        
+    register_event("test_action", async_dummy_handler)
+    
+    with client.websocket_connect("/_voodoo_ws") as websocket:
+        websocket.send_text(json.dumps({
+            "type": "event",
+            "event": "test_action",
+            "id": "btn-1",
+            "value": "clicked"
+        }))
+        
+        # Receive the patch response
+        response = websocket.receive_text()
+        data = json.loads(response)
+        
+        assert data["type"] == "patch"
+        assert data["id"] == "target-1"
+        assert data["html"] == "<b>Updated</b>"
+        
+    assert len(received) == 1
+    assert received[0] == ("btn-1", "clicked")
+
+def test_websocket_append(client):
+    async def append_handler(element_id, value):
+        await ws_manager.broadcast_append("list-1", "<li>New Item</li>")
+        
+    register_event("append_action", append_handler)
+    
+    with client.websocket_connect("/_voodoo_ws") as websocket:
+        websocket.send_text(json.dumps({
+            "type": "event",
+            "event": "append_action",
+            "id": "add-btn",
+            "value": ""
+        }))
+        
+        response = websocket.receive_text()
+        data = json.loads(response)
+        
+        assert data["type"] == "append"
+        assert data["id"] == "list-1"
+        assert data["html"] == "<li>New Item</li>"

voodoo_framework-1.0.0/voodoo/__init__.py

@@ -0,0 +1,51 @@
+from .core import create_app, register_event, ws_manager
+from .components import Div, Button, Input, Card, Text, Heading, ChatBox, Table
+from .data import BaseModel, on_insert, on_update, rls_policy, get_db
+from .queue import queue, enqueue
+from .agent import Agent
+from .api import api
+from .storage import storage
+from .mcp import mcp, MCPClient
+from .status import ServiceStatus
+from .telemetry import trace, TelemetryMiddleware, telemetry_store
+from .config import config
+from .theme import Theme, ThemeColors, set_theme, default_theme
+from .i18n import _, I18n, i18n_instance
+
+__all__ = [
+    "create_app",
+    "register_event",
+    "ws_manager",
+    "Div",
+    "Button",
+    "Input",
+    "Card",
+    "Text",
+    "Heading",
+    "ChatBox",
+    "Table",
+    "BaseModel",
+    "on_insert",
+    "on_update",
+    "rls_policy",
+    "get_db",
+    "queue",
+    "enqueue",
+    "Agent",
+    "api",
+    "storage",
+    "mcp",
+    "MCPClient",
+    "ServiceStatus",
+    "trace",
+    "TelemetryMiddleware",
+    "telemetry_store",
+    "config",
+    "Theme",
+    "ThemeColors",
+    "set_theme",
+    "default_theme",
+    "_",
+    "I18n",
+    "i18n_instance"
+]

voodoo_framework-1.0.0/voodoo/agent.py

@@ -0,0 +1,37 @@
+import asyncio
+from typing import AsyncGenerator, List, Dict
+
+class Agent:
+    def __init__(self, system_prompt: str = "You are a helpful AI assistant."):
+        self.system_prompt = system_prompt
+        self.history: List[Dict[str, str]] = [
+            {"role": "system", "content": system_prompt}
+        ]
+
+    async def stream(self, prompt: str) -> AsyncGenerator[str, None]:
+        from voodoo.telemetry import telemetry_store
+        self.history.append({"role": "user", "content": prompt})
+        
+        # In a real scenario, this would connect to OpenAI/Anthropic etc.
+        # For this standalone framework, we'll simulate a streaming response
+        # or use an actual API if configured.
+        
+        # Simulating a stream of tokens:
+        words = f"This is an AI response to: '{prompt}'. In a real app, this streams from an LLM. Here are some more tokens to simulate streaming.".split(" ")
+        
+        telemetry_store.record_agent_tokens(len(prompt.split()) + len(words))
+        
+        full_response = ""
+        for word in words:
+            await asyncio.sleep(0.1)  # Simulate network latency
+            token = word + " "
+            full_response += token
+            yield token
+            
+        self.history.append({"role": "assistant", "content": full_response.strip()})
+        
+    async def run(self, prompt: str) -> str:
+        response = ""
+        async for chunk in self.stream(prompt):
+            response += chunk
+        return response