pyponent 0.1.0__tar.gz

pyponent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Casey Dale Siatong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyponent-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: pyponent
+Version: 0.1.0
+Summary: A blazing-fast, Server-Driven UI framework for Python using FastAPI and WebSockets.
+Author-email: Casey Dale Siatong <daledev07@gmail.com>
+Project-URL: Homepage, https://github.com/DaleStack/Pyponent
+Project-URL: Bug Tracker, https://github.com/DaleStack/Pyponent/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: build>=1.4.0
+Requires-Dist: fastapi>=0.132.0
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: uvicorn[standard]>=0.41.0
+Requires-Dist: watchfiles>=1.1.1
+Requires-Dist: websocket>=0.2.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# Pyponent
+
+**Pyponent** is a blazing-fast, Server-Driven UI (SDUI) framework for Python. It allows you to build highly interactive, real-time Single Page Applications (SPAs) entirely in Python—without writing a single line of JavaScript, HTML, or CSS (unless you want to).
+
+Powered by **FastAPI** and **WebSockets**, Pyponent manages state on the server, calculates Virtual DOM diffs in pure Python, and surgically updates the browser using granular JSON patches. 
+
+---
+
+## Why was Pyponent made?
+Modern web development often requires massive context switching. To build a dynamic web app, developers usually have to write Python for the backend, design APIs, configure Webpack/Vite, and write JavaScript/React for the frontend. 
+
+**Pyponent was built to eliminate the frontend build step.** It is designed for Python developers who want to build complex, interactive dashboards and tools at the speed of thought, keeping their data, state, and UI logic perfectly synced in one unified codebase.
+
+
+
+---
+
+## Pros and Cons
+
+### Pros
+* **Zero JavaScript:** Build modals, interactive forms, and real-time dashboards using pure Python.
+* **Granular DOM Diffing:** Unlike older frameworks that reload the whole page, Pyponent sends tiny JSON patches over WebSockets, preserving cursor focus and scrolling.
+* **Built-in SPA Routing:** Includes a client-side router (`Router` and `Link`) for instant, zero-refresh page navigation.
+* **Native Tailwind Support:** Turn on Tailwind CSS with a single boolean flag.
+* **Secure by Default:** Because state lives on the server, sensitive business logic and API keys are never exposed to the browser.
+
+### Cons
+* **Requires Always-On Connection:** Pyponent relies entirely on WebSockets. It does not work offline.
+* **Network Latency:** Every button click travels to the server and back. It is incredibly fast, but not suited for high-frequency client-side animations (like 60fps drag-and-drop or WebGL games).
+* **State Management Scale:** Because the server holds the state for every connected user, massive applications with millions of concurrent users will require careful load balancing.
+
+---
+
+## How it Works
+
+
+
+1. **Initial Load:** You define components in Python. Pyponent renders them to a static HTML string and sends it to the browser.
+2. **WebSocket Connection:** The browser connects back to the FastAPI server via WebSockets.
+3. **Interactivity:** When a user clicks a button or types in an input, the browser sends a tiny JSON event `{"event_name": "onClick", "target_id": "btn-1"}` to the server.
+4. **Reconciliation:** Python updates the state, rebuilds the Virtual DOM in memory, and calculates the exact differences.
+5. **Patching:** Python sends a surgical JSON patch back to the browser, updating only the elements that changed.
+
+---
+
+## Installation & Quick Start
+
+*(Note: Pyponent is designed to run alongside Uvicorn and FastAPI).*
+
+```bash
+pip install pyponent fastapi uvicorn
+```
+
+## The "Hello World" App
+
+Create a file named `main.py`
+```python
+from fastapi import FastAPI
+from pyponent.web import setup_pyponent, run
+from pyponent.html import div, h1, p
+
+def App(**props):
+    return div(
+        h1("Hello, Pyponent!"),
+        p("This is a pure Python UI.")
+    )
+
+app = FastAPI()
+
+# Attach Pyponent to your FastAPI app
+setup_pyponent(app, App, title="My First App")
+
+if __name__ == "__main__":
+    run("main:app", port=8000, reload=True)
+```
+Run it via terminal: `python main.py` or `uv run main.py`
+
+
+## Core Features
+
+### 1. State & Interactivity (`use_state`)
+Add interactivity without JavaScript. Just bind state to your HTML elements.
+```python
+from pyponent.hooks import use_state
+from pyponent.html import div, h2, button
+
+def Counter(**props):
+    count, set_count = use_state(0)
+    
+    return div(
+        h2(f"Clicks: {count}"),
+        button("Increment", onClick=lambda e: set_count(count + 1))
+    )
+```
+
+### 2. Live Inputs (No Cursor Loss!)
+Because of Pyponent's surgical diffing engine, you can type into inputs without the DOM reloading.
+
+⚠️ Golden Rule: Always provide a hardcoded id for text inputs!
+```python
+from pyponent.hooks import use_state
+from pyponent.html import div, input_, p
+
+def LiveMirror(**props):
+    text, set_text = use_state("")
+    
+    return div(
+        input_(
+            id="mirror-input", # Required!
+            type="text",
+            value=text,
+            onInput=lambda e: set_text(e.get("value", ""))
+        ),
+        p("You typed: ", text)
+    )
+```
+
+### 3. Tailwind & Custom Head Tags
+Pyponent makes styling effortless. You can inject multiple `meta`, `link`, or `script` tags safely using a list, and opt into Tailwind CSS with a single flag.
+```python
+from pyponent.hooks import use_state
+from pyponent.html import div, input_, p
+from pyponent.web import setup_pyponent
+
+my_seo_tags = [
+    '<meta name="description" content="A blazing fast Pyponent App.">',
+    'styles/sample.css', # Use styles/ directory, it has automatic injection
+    '<script src="[https://js.stripe.com/v3/](https://js.stripe.com/v3/)"></script>'
+]
+
+setup_pyponent(
+    app, 
+    App, 
+    title="My E-Commerce Dashboard", 
+    use_tailwind=True,  # Instantly activates Tailwind CDN!
+    meta_tags=my_seo_tags
+)
+```
+
+### 4. Zero Refresh Routing
+Build Multi-Page Applications without page reloads using the built-in router.
+```python
+from pyponent.router import Router, Link
+
+def Navigation(**props):
+    return div(
+        # Use Link for internal SPA navigation and a tag for external
+        Link(to="/", children=["Home"]),
+        Link(to="/dashboard", children=["Dashboard"])
+    )
+
+def App(**props):
+    return div(
+        Navigation(),
+        Router(
+            initial_path=props.get("initial_path", "/"),
+            routes={
+                "/": HomePage,
+                "/dashboard": DashboardPage
+            }
+        )
+    )
+```
+
+## License
+
+Pyponent is proudly open-source and is licensed under the [MIT License](LICENSE). You are free to use it in personal, open-source, and commercial projects.

pyponent-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Pyponent
+
+**Pyponent** is a blazing-fast, Server-Driven UI (SDUI) framework for Python. It allows you to build highly interactive, real-time Single Page Applications (SPAs) entirely in Python—without writing a single line of JavaScript, HTML, or CSS (unless you want to).
+
+Powered by **FastAPI** and **WebSockets**, Pyponent manages state on the server, calculates Virtual DOM diffs in pure Python, and surgically updates the browser using granular JSON patches. 
+
+---
+
+## Why was Pyponent made?
+Modern web development often requires massive context switching. To build a dynamic web app, developers usually have to write Python for the backend, design APIs, configure Webpack/Vite, and write JavaScript/React for the frontend. 
+
+**Pyponent was built to eliminate the frontend build step.** It is designed for Python developers who want to build complex, interactive dashboards and tools at the speed of thought, keeping their data, state, and UI logic perfectly synced in one unified codebase.
+
+
+
+---
+
+## Pros and Cons
+
+### Pros
+* **Zero JavaScript:** Build modals, interactive forms, and real-time dashboards using pure Python.
+* **Granular DOM Diffing:** Unlike older frameworks that reload the whole page, Pyponent sends tiny JSON patches over WebSockets, preserving cursor focus and scrolling.
+* **Built-in SPA Routing:** Includes a client-side router (`Router` and `Link`) for instant, zero-refresh page navigation.
+* **Native Tailwind Support:** Turn on Tailwind CSS with a single boolean flag.
+* **Secure by Default:** Because state lives on the server, sensitive business logic and API keys are never exposed to the browser.
+
+### Cons
+* **Requires Always-On Connection:** Pyponent relies entirely on WebSockets. It does not work offline.
+* **Network Latency:** Every button click travels to the server and back. It is incredibly fast, but not suited for high-frequency client-side animations (like 60fps drag-and-drop or WebGL games).
+* **State Management Scale:** Because the server holds the state for every connected user, massive applications with millions of concurrent users will require careful load balancing.
+
+---
+
+## How it Works
+
+
+
+1. **Initial Load:** You define components in Python. Pyponent renders them to a static HTML string and sends it to the browser.
+2. **WebSocket Connection:** The browser connects back to the FastAPI server via WebSockets.
+3. **Interactivity:** When a user clicks a button or types in an input, the browser sends a tiny JSON event `{"event_name": "onClick", "target_id": "btn-1"}` to the server.
+4. **Reconciliation:** Python updates the state, rebuilds the Virtual DOM in memory, and calculates the exact differences.
+5. **Patching:** Python sends a surgical JSON patch back to the browser, updating only the elements that changed.
+
+---
+
+## Installation & Quick Start
+
+*(Note: Pyponent is designed to run alongside Uvicorn and FastAPI).*
+
+```bash
+pip install pyponent fastapi uvicorn
+```
+
+## The "Hello World" App
+
+Create a file named `main.py`
+```python
+from fastapi import FastAPI
+from pyponent.web import setup_pyponent, run
+from pyponent.html import div, h1, p
+
+def App(**props):
+    return div(
+        h1("Hello, Pyponent!"),
+        p("This is a pure Python UI.")
+    )
+
+app = FastAPI()
+
+# Attach Pyponent to your FastAPI app
+setup_pyponent(app, App, title="My First App")
+
+if __name__ == "__main__":
+    run("main:app", port=8000, reload=True)
+```
+Run it via terminal: `python main.py` or `uv run main.py`
+
+
+## Core Features
+
+### 1. State & Interactivity (`use_state`)
+Add interactivity without JavaScript. Just bind state to your HTML elements.
+```python
+from pyponent.hooks import use_state
+from pyponent.html import div, h2, button
+
+def Counter(**props):
+    count, set_count = use_state(0)
+    
+    return div(
+        h2(f"Clicks: {count}"),
+        button("Increment", onClick=lambda e: set_count(count + 1))
+    )
+```
+
+### 2. Live Inputs (No Cursor Loss!)
+Because of Pyponent's surgical diffing engine, you can type into inputs without the DOM reloading.
+
+⚠️ Golden Rule: Always provide a hardcoded id for text inputs!
+```python
+from pyponent.hooks import use_state
+from pyponent.html import div, input_, p
+
+def LiveMirror(**props):
+    text, set_text = use_state("")
+    
+    return div(
+        input_(
+            id="mirror-input", # Required!
+            type="text",
+            value=text,
+            onInput=lambda e: set_text(e.get("value", ""))
+        ),
+        p("You typed: ", text)
+    )
+```
+
+### 3. Tailwind & Custom Head Tags
+Pyponent makes styling effortless. You can inject multiple `meta`, `link`, or `script` tags safely using a list, and opt into Tailwind CSS with a single flag.
+```python
+from pyponent.hooks import use_state
+from pyponent.html import div, input_, p
+from pyponent.web import setup_pyponent
+
+my_seo_tags = [
+    '<meta name="description" content="A blazing fast Pyponent App.">',
+    'styles/sample.css', # Use styles/ directory, it has automatic injection
+    '<script src="[https://js.stripe.com/v3/](https://js.stripe.com/v3/)"></script>'
+]
+
+setup_pyponent(
+    app, 
+    App, 
+    title="My E-Commerce Dashboard", 
+    use_tailwind=True,  # Instantly activates Tailwind CDN!
+    meta_tags=my_seo_tags
+)
+```
+
+### 4. Zero Refresh Routing
+Build Multi-Page Applications without page reloads using the built-in router.
+```python
+from pyponent.router import Router, Link
+
+def Navigation(**props):
+    return div(
+        # Use Link for internal SPA navigation and a tag for external
+        Link(to="/", children=["Home"]),
+        Link(to="/dashboard", children=["Dashboard"])
+    )
+
+def App(**props):
+    return div(
+        Navigation(),
+        Router(
+            initial_path=props.get("initial_path", "/"),
+            routes={
+                "/": HomePage,
+                "/dashboard": DashboardPage
+            }
+        )
+    )
+```
+
+## License
+
+Pyponent is proudly open-source and is licensed under the [MIT License](LICENSE). You are free to use it in personal, open-source, and commercial projects.

pyponent-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyponent"
+version = "0.1.0"
+description = "A blazing-fast, Server-Driven UI framework for Python using FastAPI and WebSockets."
+readme = "README.md"
+requires-python = ">=3.13"
+
+authors = [
+    { name = "Casey Dale Siatong", email = "daledev07@gmail.com" }, 
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: User Interfaces",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Intended Audience :: Developers",
+]
+
+dependencies = [
+    "build>=1.4.0",
+    "fastapi>=0.132.0",
+    "pytest>=9.0.2",
+    "uvicorn[standard]>=0.41.0",
+    "watchfiles>=1.1.1",
+    "websocket>=0.2.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.3.0",
+    "build",
+    "twine"
+]
+
+[tool.ruff]
+line-length = 88 # The standard Black line length
+target-version = "py39"
+
+[tool.ruff.lint]
+# E = pycodestyle (standard formatting rules)
+# F = pyflakes (catches unused imports, undefined variables)
+# I = isort (automatically sorts your imports alphabetically)
+select = ["E", "F", "I"]
+
+[project.urls]
+"Homepage" = "https://github.com/DaleStack/Pyponent" 
+"Bug Tracker" = "https://github.com/DaleStack/Pyponent/issues" 
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "src"
+]

pyponent-0.1.0/setup.cfg

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

pyponent-0.1.0/src/pyponent/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pyponent-0.1.0/src/pyponent/core.py

@@ -0,0 +1,86 @@
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Union
+
+from .hooks import dispatcher_context
+
+
+@dataclass
+class VNode:
+    tag: Union[str, Callable]
+    props: Dict[str, Any] = field(default_factory=dict)
+    children: List[Union["VNode", str]] = field(default_factory=list)
+    id: str = field(init=False)  # Tell dataclass we will set this ourselves
+
+    def __post_init__(self):
+        # Guarantee an ID for every element for the Diffing Engine
+        if "id" not in self.props:
+            self.props["id"] = f"pyp-{uuid.uuid4().hex[:8]}"
+        self.id = self.props["id"]
+
+
+def render_to_string(node: Union[VNode, str]) -> str:
+    if isinstance(node, str):
+        return node
+
+    html_attrs = []
+    for key, value in node.props.items():
+        if not key.startswith("on"):
+            html_attrs.append(f'{key}="{value}"')
+
+    attr_str = " " + " ".join(html_attrs) if html_attrs else ""
+    children_str = "".join(render_to_string(child) for child in node.children)
+    return f"<{node.tag}{attr_str}>{children_str}</{node.tag}>"
+
+
+def fire_event(
+    node: Union["VNode", str], target_id: str, event_name: str, event_data: dict = None
+) -> bool:
+    if isinstance(node, str):
+        return False
+
+    if node.props.get("id") == target_id:
+        handler = node.props.get(event_name)
+        if handler:
+            try:
+                # Pass the typing payload to the user's function
+                handler(event_data or {})
+            except TypeError:
+                # If they didn't ask for the payload (like a simple button click),
+                # run it empty
+                handler()
+            return True
+        return False
+
+    for child in node.children:
+        if fire_event(child, target_id, event_name, event_data):
+            return True
+
+    return False
+
+
+def resolve_vdom(node: Union[VNode, str], path: str = "root") -> Union[VNode, str]:
+    if isinstance(node, str):
+        return node
+
+    if callable(node.tag):
+        node_id = f"{node.tag.__name__}_{path}"
+        current_dispatcher = dispatcher_context.get()
+        current_dispatcher.prepare_render(node_id)
+
+        try:
+            # Use ** to unpack the dictionary into keyword arguments
+            resolved_component = node.tag(**node.props)
+        except TypeError:
+            resolved_component = node.tag()
+
+        return resolve_vdom(resolved_component, path)
+
+    resolved_children = []
+    for index, child in enumerate(node.children):
+        if child is None:
+            continue
+        child_path = f"{path}.{index}"
+        resolved_children.append(resolve_vdom(child, child_path))
+
+    return VNode(tag=node.tag, props=node.props, children=resolved_children)

pyponent-0.1.0/src/pyponent/diff.py

@@ -0,0 +1,36 @@
+from .core import VNode, render_to_string
+
+
+def diff_vdom(old, new):
+    patches = []
+
+    if old.tag != new.tag:
+        return [{"type": "replace", "id": old.id, "html": render_to_string(new)}]
+
+    new.id = old.id
+    new.props["id"] = old.id
+
+    # Filter out functions before diffing and sending
+    safe_old_props = {
+        k: v for k, v in old.props.items() if not callable(v) and not k.startswith("on")
+    }
+    safe_new_props = {
+        k: v for k, v in new.props.items() if not callable(v) and not k.startswith("on")
+    }
+
+    if safe_old_props != safe_new_props:
+        patches.append({"type": "props", "id": new.id, "props": safe_new_props})
+
+    if len(old.children) != len(new.children):
+        inner_html = "".join(render_to_string(c) for c in new.children)
+        patches.append({"type": "inner_html", "id": new.id, "html": inner_html})
+    else:
+        for o_child, n_child in zip(old.children, new.children):
+            if isinstance(o_child, VNode) and isinstance(n_child, VNode):
+                patches.extend(diff_vdom(o_child, n_child))
+            elif o_child != n_child:
+                inner_html = "".join(render_to_string(c) for c in new.children)
+                patches.append({"type": "inner_html", "id": new.id, "html": inner_html})
+                break
+
+    return patches

pyponent-0.1.0/src/pyponent/hooks.py

@@ -0,0 +1,85 @@
+import contextvars
+import threading
+
+
+class Dispatcher:
+    def __init__(self):
+        self.states = {}
+        self.hook_indices = {}
+        self.current_node_id = None
+        self.trigger_render = None
+
+        # Effect Tracking
+
+        # Stores previous dependencies: {node_id: [deps_1, deps_2]}
+        self.effects = {}
+        # Tracks the cursor for effects
+        self.effect_indices = {}
+        # A queue of effects to run AFTER the render is complete
+        self.pending_effects = []
+
+    def prepare_render(self, node_id: str):
+        self.current_node_id = node_id
+        self.hook_indices[node_id] = 0
+        self.effect_indices[node_id] = 0  # Reset effect cursor
+
+        if node_id not in self.states:
+            self.states[node_id] = []
+        if node_id not in self.effects:
+            self.effects[node_id] = []
+
+
+dispatcher_context: contextvars.ContextVar[Dispatcher] = contextvars.ContextVar(
+    "dispatcher"
+)  # noqa: E501
+
+
+def use_state(initial_value):
+    dispatcher = dispatcher_context.get()
+    node_id = dispatcher.current_node_id
+    idx = dispatcher.hook_indices[node_id]
+
+    if len(dispatcher.states[node_id]) == idx:
+        dispatcher.states[node_id].append(initial_value)
+
+    def set_state(new_value):
+        dispatcher.states[node_id][idx] = new_value
+        if dispatcher.trigger_render:
+            dispatcher.trigger_render()
+
+    value = dispatcher.states[node_id][idx]
+    dispatcher.hook_indices[node_id] += 1
+    return value, set_state
+
+
+# The use_effect hook
+def use_effect(callback, deps=None):
+    dispatcher = dispatcher_context.get()
+    node_id = dispatcher.current_node_id
+    idx = dispatcher.effect_indices[node_id]
+
+    # If this is the very first render for this effect
+    if len(dispatcher.effects[node_id]) == idx:
+        dispatcher.effects[node_id].append(deps)
+        dispatcher.pending_effects.append(callback)
+    else:
+        # Compare previous dependencies with the new ones
+        prev_deps = dispatcher.effects[node_id][idx]
+
+        # If deps is None, it runs every single render.
+        # If deps changed, we update the stored deps and queue the effect.
+        if deps is None or prev_deps != deps:
+            dispatcher.effects[node_id][idx] = deps
+            dispatcher.pending_effects.append(callback)
+
+    dispatcher.effect_indices[node_id] += 1
+
+
+def use_async_effect(callback, deps=None):
+    """A custom hook that automatically runs the callback in a background thread."""
+
+    def thread_runner():
+        threading.Thread(target=callback).start()
+
+    # We pass our thread_runner into the standard use_effect
+    use_effect(thread_runner, deps)