pgwidgets-python 0.1.3__tar.gz

pgwidgets_python-0.1.3/.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 100
+extend-ignore = E501

pgwidgets_python-0.1.3/.gitignore

@@ -0,0 +1,12 @@
+__pycache__
+*.py[co]
+*.egg
+*.egg-info
+dist
+build
+docs/_build
+node_modules
+.DS_Store
+*~
+\#*\#
+.*.swp

pgwidgets_python-0.1.3/.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev

pgwidgets_python-0.1.3/LICENSE.md

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, PGWidgets developers
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pgwidgets_python-0.1.3/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: pgwidgets-python
+Version: 0.1.3
+Summary: Python bindings for the pgwidgets JavaScript widget library
+Author: PGWidgets Developers
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/naojsoft/pgwidgets-python
+Project-URL: Repository, https://github.com/naojsoft/pgwidgets-python
+Keywords: widgets,ui,gui,websocket,browser
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pgwidgets-js
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: furo; extra == "dev"
+Requires-Dist: sphinx-autodoc-typehints; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# pgwidgets — Python Bindings
+
+Python bindings for the [pgwidgets](https://github.com/naojsoft/pgwidgets-js)
+JavaScript widget library. Build desktop-style browser UIs from Python
+with a familiar Qt/GTK-style API.
+
+## Installation
+
+```bash
+pip install pgwidgets-python
+```
+
+This will also install `pgwidgets-js` (the JavaScript assets) and
+`websockets` as dependencies.
+
+## Quick Start
+
+```python
+from pgwidgets.sync import Application
+
+app = Application()
+
+@app.on_connect
+def setup(session):
+    Widgets = session.get_widgets()
+
+    top = Widgets.TopLevel(title="Hello", resizable=True)
+    top.resize(400, 300)
+
+    vbox = Widgets.VBox(spacing=8, padding=10)
+    btn = Widgets.Button("Click me")
+    label = Widgets.Label("Ready")
+
+    btn.on("activated", lambda: label.set_text("Clicked!"))
+
+    vbox.add_widget(btn, 0)
+    vbox.add_widget(label, 1)
+    top.set_widget(vbox)
+    top.show()
+
+app.run()
+```
+
+Run the script, then open the printed URL in your browser.
+
+## Sync vs Async
+
+Both APIs provide the same widget classes and methods.
+
+**Synchronous** (recommended for most use cases):
+```python
+from pgwidgets.sync import Application
+app = Application()
+
+@app.on_connect
+def setup(session):
+    Widgets = session.get_widgets()
+    btn = Widgets.Button("Click")      # blocking call
+    btn.set_text("New text")           # blocking call
+
+app.run()
+```
+
+**Asynchronous** (for asyncio applications):
+```python
+from pgwidgets.async_ import Application
+app = Application()
+
+@app.on_connect
+async def setup(session):
+    Widgets = session.get_widgets()
+    btn = await Widgets.Button("Click")    # awaitable
+    await btn.set_text("New text")         # awaitable
+
+await app.run()
+```
+
+## How It Works
+
+The `Application` class starts two servers:
+- An **HTTP server** (default port 9501) that serves the pgwidgets JS/CSS
+  and a connector page
+- A **WebSocket server** (default port 9500) for the JSON command protocol
+
+When you open the URL in a browser, the page loads pgwidgets and connects
+back over WebSocket. Python widget constructors and method calls are
+translated to JSON messages and executed in the browser. Callbacks are
+forwarded back to Python.
+
+## License
+
+BSD 3-Clause

pgwidgets_python-0.1.3/README.md

@@ -0,0 +1,92 @@
+# pgwidgets — Python Bindings
+
+Python bindings for the [pgwidgets](https://github.com/naojsoft/pgwidgets-js)
+JavaScript widget library. Build desktop-style browser UIs from Python
+with a familiar Qt/GTK-style API.
+
+## Installation
+
+```bash
+pip install pgwidgets-python
+```
+
+This will also install `pgwidgets-js` (the JavaScript assets) and
+`websockets` as dependencies.
+
+## Quick Start
+
+```python
+from pgwidgets.sync import Application
+
+app = Application()
+
+@app.on_connect
+def setup(session):
+    Widgets = session.get_widgets()
+
+    top = Widgets.TopLevel(title="Hello", resizable=True)
+    top.resize(400, 300)
+
+    vbox = Widgets.VBox(spacing=8, padding=10)
+    btn = Widgets.Button("Click me")
+    label = Widgets.Label("Ready")
+
+    btn.on("activated", lambda: label.set_text("Clicked!"))
+
+    vbox.add_widget(btn, 0)
+    vbox.add_widget(label, 1)
+    top.set_widget(vbox)
+    top.show()
+
+app.run()
+```
+
+Run the script, then open the printed URL in your browser.
+
+## Sync vs Async
+
+Both APIs provide the same widget classes and methods.
+
+**Synchronous** (recommended for most use cases):
+```python
+from pgwidgets.sync import Application
+app = Application()
+
+@app.on_connect
+def setup(session):
+    Widgets = session.get_widgets()
+    btn = Widgets.Button("Click")      # blocking call
+    btn.set_text("New text")           # blocking call
+
+app.run()
+```
+
+**Asynchronous** (for asyncio applications):
+```python
+from pgwidgets.async_ import Application
+app = Application()
+
+@app.on_connect
+async def setup(session):
+    Widgets = session.get_widgets()
+    btn = await Widgets.Button("Click")    # awaitable
+    await btn.set_text("New text")         # awaitable
+
+await app.run()
+```
+
+## How It Works
+
+The `Application` class starts two servers:
+- An **HTTP server** (default port 9501) that serves the pgwidgets JS/CSS
+  and a connector page
+- A **WebSocket server** (default port 9500) for the JSON command protocol
+
+When you open the URL in a browser, the page loads pgwidgets and connects
+back over WebSocket. Python widget constructors and method calls are
+translated to JSON messages and executed in the browser. Callbacks are
+forwarded back to Python.
+
+## License
+
+BSD 3-Clause

pgwidgets_python-0.1.3/docs/Makefile

@@ -0,0 +1,15 @@
+# Minimal makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

pgwidgets_python-0.1.3/docs/api/async.rst

@@ -0,0 +1,27 @@
+pgwidgets.async\_
+=================
+
+.. module:: pgwidgets.async_
+
+Asynchronous API for pgwidgets.
+
+Application
+-----------
+
+.. autoclass:: pgwidgets.async_.application.Application
+   :members:
+   :show-inheritance:
+
+Session
+-------
+
+.. autoclass:: pgwidgets.async_.application.Session
+   :members:
+   :show-inheritance:
+
+Widget
+------
+
+.. autoclass:: pgwidgets.async_.widget.Widget
+   :members:
+   :show-inheritance:

pgwidgets_python-0.1.3/docs/api/index.rst

@@ -0,0 +1,10 @@
+API Reference
+=============
+
+Auto-generated API documentation from source docstrings.
+
+.. toctree::
+   :maxdepth: 2
+
+   sync
+   async

pgwidgets_python-0.1.3/docs/api/sync.rst

@@ -0,0 +1,27 @@
+pgwidgets.sync
+==============
+
+.. module:: pgwidgets.sync
+
+Synchronous API for pgwidgets.
+
+Application
+-----------
+
+.. autoclass:: pgwidgets.sync.application.Application
+   :members:
+   :show-inheritance:
+
+Session
+-------
+
+.. autoclass:: pgwidgets.sync.application.Session
+   :members:
+   :show-inheritance:
+
+Widget
+------
+
+.. autoclass:: pgwidgets.sync.widget.Widget
+   :members:
+   :show-inheritance:

pgwidgets_python-0.1.3/docs/architecture.rst

@@ -0,0 +1,94 @@
+Architecture
+============
+
+Overview
+--------
+
+pgwidgets follows a client-server architecture. Python is the server; the
+browser is the client. Widget constructors and method calls in Python are
+translated to JSON messages and sent over WebSocket to the browser, where the
+pgwidgets JavaScript library executes them. User interactions (clicks, input,
+etc.) travel back as callback messages.
+
+::
+
+   Python (server)                     Browser (client)
+   +-----------------+                 +------------------+
+   | Application     |   WebSocket    | pgwidgets JS     |
+   |   Session  <----|----JSON------->|   widget tree     |
+   |     widgets     |                |   DOM rendering   |
+   +-----------------+                +------------------+
+          |
+          | HTTP (static files)
+          v
+   JS/CSS assets served to browser
+
+Servers
+-------
+
+The ``Application`` class starts two servers:
+
+**HTTP server** (default port 9501)
+   Serves the pgwidgets JavaScript/CSS assets and a connector HTML page.
+   When a browser hits ``/``, it gets ``remote.html`` with the WebSocket URL
+   injected. Set ``http_server=False`` if you serve the static files from
+   your own web server (Flask, FastAPI, nginx, etc.).
+
+**WebSocket server** (default port 9500)
+   Carries the JSON command protocol. Each browser tab opens one WebSocket
+   connection, which becomes one ``Session``.
+
+JSON Protocol
+-------------
+
+All messages are JSON objects with a ``type`` field.
+
+**Python -> Browser:**
+
+- ``{"type": "init", "id": 0}`` -- reset the browser to a clean slate.
+- ``{"type": "create", "wid": 1, "class": "Button", "args": ["Click"]}`` --
+  create a widget.
+- ``{"type": "call", "wid": 1, "method": "set_text", "args": ["New"]}`` --
+  call a method on a widget.
+- ``{"type": "listen", "wid": 1, "action": "activated"}`` -- subscribe to a
+  callback.
+- ``{"type": "unlisten", "wid": 1, "action": "activated"}`` -- unsubscribe.
+
+**Browser -> Python:**
+
+- ``{"type": "result", "id": 1, "value": ...}`` -- method return value.
+- ``{"type": "error", "id": 1, "error": "..."}`` -- method error.
+- ``{"type": "callback", "wid": 1, "action": "activated", "args": [...]}`` --
+  user interaction.
+- ``{"type": "file-chunk", ...}`` -- chunked file data (see :doc:`callbacks`).
+
+Session Model
+-------------
+
+Each browser tab that connects gets its own ``Session`` object. The session
+owns:
+
+- A widget map (``wid`` -> Python widget wrapper)
+- A callback registry (``"wid:action"`` -> handler function)
+- A message-ID counter for request/response matching
+
+Multiple sessions can be active concurrently (controlled by ``max_sessions``).
+
+Lifecycle:
+
+1. Browser opens the URL and loads ``remote.html``.
+2. JavaScript connects to the WebSocket server.
+3. Python sends ``init``; browser acknowledges.
+4. ``on_connect`` callback fires with the new ``Session``.
+5. User code creates widgets, registers callbacks.
+6. When the browser tab closes, ``on_disconnect`` fires and the session is
+   cleaned up.
+
+Widget References
+-----------------
+
+Widgets are identified by integer IDs (``wid``). When a Python widget is
+passed as an argument to another widget's method (e.g., ``vbox.add_widget(btn,
+0)``), the framework automatically converts the Python ``Widget`` object to a
+``{"__wid__": N}`` reference on the wire, and converts it back on return
+values.

pgwidgets_python-0.1.3/docs/async.rst

@@ -0,0 +1,152 @@
+Asynchronous API
+================
+
+The async API lives in ``pgwidgets.async_``. All widget constructors and
+method calls are coroutines that must be awaited.
+
+.. code-block:: python
+
+   from pgwidgets.async_ import Application
+
+Application
+-----------
+
+.. code-block:: python
+
+   app = Application(
+       ws_port=9500,
+       http_port=9501,
+       host="127.0.0.1",
+       http_server=True,
+       concurrency_handling="per_session",
+       max_sessions=1,
+       logger=None,
+   )
+
+The constructor parameters are the same as the sync version (see :doc:`sync`).
+
+on_connect / on_disconnect
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Handlers can be sync or async:
+
+.. code-block:: python
+
+   @app.on_connect
+   async def setup(session):
+       Widgets = session.get_widgets()
+       top = await Widgets.TopLevel(title="Hello")
+       await top.show()
+
+   @app.on_disconnect
+   async def teardown(session):
+       print(f"Session {session.id} disconnected")
+
+Running
+~~~~~~~
+
+.. code-block:: python
+
+   # Inside an async context
+   await app.run()
+
+   # Or with asyncio.run()
+   import asyncio
+   asyncio.run(main())
+
+``await app.close()`` shuts down all sessions and causes ``run()`` to return.
+
+Session
+-------
+
+The async ``Session`` has the same interface as the sync version, but methods
+are coroutines:
+
+.. code-block:: python
+
+   Widgets = session.get_widgets()          # sync -- returns namespace
+   btn = await Widgets.Button("Click me")   # async -- creates widget
+   await btn.set_text("New text")           # async -- calls method
+   await session.close()                    # async
+   timer = await session.make_timer(duration=1000)  # async
+
+Concurrency Modes
+-----------------
+
+In the async API, concurrency is managed with ``asyncio.Lock`` instead of
+threads:
+
+**per_session** (default)
+   Each session gets its own ``asyncio.Lock``. Callbacks within a session
+   are serialized, but different sessions can interleave at ``await`` points.
+
+**serialized**
+   All callbacks from all sessions are serialized under a single global
+   ``asyncio.Lock``.
+
+**concurrent**
+   Callbacks are dispatched via ``asyncio.ensure_future`` with no
+   serialization.
+
+Callbacks
+~~~~~~~~~
+
+Callback handlers can be sync or async. Async handlers are awaited:
+
+.. code-block:: python
+
+   async def on_click():
+       await status.set_text("Clicked!")
+
+   await btn.on("activated", on_click)
+
+Full Example
+------------
+
+.. code-block:: python
+
+   import asyncio
+   import logging
+   from pgwidgets.async_ import Application
+
+   logging.basicConfig(level=logging.INFO)
+   logger = logging.getLogger("pgwidgets")
+
+   async def main():
+       app = Application(max_sessions=4, logger=logger)
+
+       @app.on_connect
+       async def on_session(session):
+           Widgets = session.get_widgets()
+
+           top = await Widgets.TopLevel(title="Async Demo", resizable=True)
+           await top.resize(400, 300)
+
+           vbox = await Widgets.VBox(spacing=8, padding=10)
+           status = await Widgets.Label("Click a button!")
+
+           hbox = await Widgets.HBox(spacing=6)
+           btn = await Widgets.Button("Hello")
+           await hbox.add_widget(btn, 0)
+
+           entry = await Widgets.TextEntry(text="Type here", linehistory=5)
+
+           await vbox.add_widget(hbox, 0)
+           await vbox.add_widget(entry, 0)
+           await vbox.add_widget(status, 1)
+           await top.set_widget(vbox)
+           await top.show()
+
+           async def on_hello():
+               await status.set_text("Hello!")
+
+           async def on_entry(text):
+               await status.set_text(f"Entered: {text}")
+
+           await btn.on("activated", on_hello)
+           await entry.on("activated", on_entry)
+
+       await app.run()
+
+   if __name__ == "__main__":
+       asyncio.run(main())