Merge branch 'main' into reset-modules

Author: falkoschindler

.cursor/rules .cursor/rules/general.mdc.cursor/rules renamed to .cursor/rules/general.mdc

@@ -1,10 +1,14 @@
+---
+alwaysApply: true
+---
+
 # Cursor AI Quick Reference
 
 **Read these files before working:**
 
-1. [README.md](../README.md) - Project overview and setup
-2. [AGENTS.md](../AGENTS.md) - AI agent guidelines and code review instructions
-3. [CONTRIBUTING.md](../CONTRIBUTING.md) - Coding standards and workflow
+1. [README.md](../../README.md) - Project overview and setup
+2. [AGENTS.md](../../AGENTS.md) - AI agent guidelines and code review instructions
+3. [CONTRIBUTING.md](../../CONTRIBUTING.md) - Coding standards and workflow
 
 ## Quick Reference
 

.github/workflows/publish.yml

@@ -133,14 +133,14 @@ jobs:
           python-version: "3.11"
       - name: Install httpx
         run: pip install httpx
-      - name: Update version in pyproject.toml and citation.cff
+      - name: Update version in citation.cff
         run: python .github/workflows/update_version.py ${GITHUB_REF#refs/tags/}
       - name: Commit and push changes
         run: |
           git config --global user.name "github-actions[bot]"
           git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add pyproject.toml CITATION.cff
-          git commit -m "Update version"
+          git add CITATION.cff
+          git commit -m "Update citation version"
           git push origin HEAD:main
 
   verify:

.github/workflows/update_version.py

@@ -5,15 +5,6 @@
 
 if __name__ == '__main__':
     version = sys.argv[1].lstrip('v')
-
-    path = Path('pyproject.toml')
-    lines = path.read_text(encoding='utf-8').splitlines()
-    for i, line in enumerate(lines):
-        if line.startswith('version = '):
-            lines[i] = f'version = "{version}.dev0"'
-            break
-    path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
-
     path = Path('CITATION.cff')
     lines = path.read_text(encoding='utf-8').splitlines()
     for i, line in enumerate(lines):

CITATION.cff

@@ -8,8 +8,8 @@ authors:
     given-names: Rodja
     orcid: https://orcid.org/0009-0009-4735-6227
 title: "NiceGUI: Web-based user interfaces with Python. The nice way."
-version: 3.0.4
-date-released: "2025-10-10"
+version: 3.1.0
+date-released: "2025-10-22"
 url: https://github.com/zauberzeug/nicegui
 doi: 10.5281/zenodo.7785516
 identifiers:

CONTRIBUTING.md

@@ -241,6 +241,7 @@ If you plan to implement a new element you can follow these suggestions:
 8. Add a documentation file in `website/documentation/content`.
    By calling the `@doc.demo(...)` function with an element as a parameter the docstring is used as a description.
    The docstrings are written in restructured-text.
+   Make sure to use the correct syntax (like double backticks for code).
    Refer to the new documentation page using `@doc.intro(...)` in any documentation section `website/documentation/content/section_*.py`.
 9. Create a pull-request (see below).
 

deploy.py

@@ -21,23 +21,20 @@ def run(cmd: list[str], *, capture: bool = False) -> str:
 run(['fly', 'deploy', '--wait-timeout', '600', '--lease-timeout', '30s', '--build-arg', f'VERSION={version}'])
 
 instances = {
-    'yul': 2,  # Montreal, Quebec (Canada)
+    'yyz': 2,  # Toronto, Ontario (Canada)
     'iad': 3,  # Washington DC, Virginia (US)
     'sjc': 2,  # San Jose, California (US)
     'lax': 2,  # Los Angeles, California (US)
     'mia': 2,  # Miami, Florida (US)
     'sea': 2,  # Seattle, Washington (US)
     'fra': 3,  # Frankfurt, Germany
     'ams': 2,  # Amsterdam, Netherlands
-    'mad': 1,  # Madrid, Spain
     'cdg': 2,  # Paris, France
     'lhr': 2,  # London, England (UK)
-    'otp': 1,  # Bucharest, Romania
     'jnb': 1,  # Johannesburg, South Africa
     'bom': 1,  # Mumbai, India
     'nrt': 3,  # Tokyo, Japan
-    'sin': 2,  # Singapore
-    'hkg': 3,  # Hong Kong
+    'sin': 3,  # Singapore
     'syd': 1,  # Sydney, Australia
     'gru': 1,  # Sao Paulo, Brazil
 }

examples/api_requests/main.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+import random
+
+import httpx
+
+from nicegui import ui
+
+
+async def show_new_quote():
+    async with httpx.AsyncClient() as client:
+        response = await client.get('https://zenquotes.io/api/quotes')
+        quote = random.choice(response.json())['q']
+    label.text = f'“{quote}”'
+
+with ui.card().classes('max-w-md mx-auto mt-20 p-12 gap-12 rounded-2xl shadow-lg border border-gray-100 items-center'):
+    label = ui.label('Click on "Next Quote" to get a quote') \
+        .classes('text-gray-700 italic text-lg text-center font-serif')
+
+    ui.button('Next Quote', on_click=show_new_quote) \
+        .classes('bg-gray-800 hover:bg-gray-900 text-sm px-4 py-2 rounded-xl shadow-md transition duration-200')
+
+ui.run()

examples/threaded_nicegui/main.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+import threading
+
+from nicegui import Event, app, ui
+
+
+class GUI:
+    """Encapsulates NiceGUI in a separate thread with Event-based communication.
+
+    This pattern is useful for any scenario where the main thread needs to remain available for other work.
+    """
+
+    def __init__(self) -> None:
+        self.message = Event[str]()  # NOTE: broadcast data to all clients currently visiting self.root
+
+    def start(self) -> None:
+        """Start the NiceGUI server in a separate thread."""
+        started = threading.Event()
+        app.on_startup(started.set)
+        thread = threading.Thread(target=lambda: ui.run(self.root, reload=False), daemon=True)
+        thread.start()
+        if not started.wait(timeout=3.0):  # NOTE: wait for the server to start
+            raise RuntimeError('NiceGUI did not start within 3 seconds.')
+
+    def root(self) -> None:
+        """Create the UI for each new visitor."""
+        ui.label('NiceGUI running in separate thread').classes('text-h6')
+        message_label = ui.label('Waiting for CLI input...')
+        self.message.subscribe(message_label.set_text)
+
+
+if __name__ == '__main__':
+    gui = GUI()
+    gui.start()
+    print('Type messages to update website from the main thread (or "quit" to exit).\n')
+    try:
+        while (user_input := input('> ')) != 'quit':
+            gui.message.emit(user_input)
+    except (EOFError, KeyboardInterrupt):
+        pass

examples/xterm/main.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Example for connecting a `Xterm` element with a `Bash` process running in a pty.
+
+WARNING: This example gives the clients full access to the server through Bash. Use with caution!
+"""
+import os
+import pty
+import signal
+from functools import partial
+
+from nicegui import core, events, ui
+
+
+@ui.page('/')
+def _page():
+    terminal = ui.xterm()
+
+    pty_pid, pty_fd = pty.fork()  # create a new pseudo-terminal (pty) fork of the process
+    if pty_pid == pty.CHILD:
+        os.execv('/bin/bash', ('bash',))  # child process of the fork gets replaced with "bash"
+    print('Terminal opened')
+
+    @partial(core.loop.add_reader, pty_fd)
+    def pty_to_terminal():
+        try:
+            data = os.read(pty_fd, 1024)
+        except OSError:
+            print('Stopping reading from pty')  # error reading the pty; probably bash was exited
+            core.loop.remove_reader(pty_fd)
+        else:
+            terminal.write(data)
+
+    @terminal.on_data
+    def terminal_to_pty(event: events.XtermDataEventArguments):
+        try:
+            os.write(pty_fd, event.data.encode('utf-8'))
+        except OSError:
+            pass  # error writing to the pty; probably bash was exited
+
+    @ui.context.client.on_delete
+    def kill_bash():
+        os.close(pty_fd)
+        os.kill(pty_pid, signal.SIGKILL)
+        print('Terminal closed')
+
+
+ui.run()

fetch_milestone.py

@@ -9,8 +9,10 @@
 
 parser = argparse.ArgumentParser(description='Fetch the content of a milestone from a GitHub repo.')
 parser.add_argument('milestone_title', help='Title of the milestone to fetch.')
+parser.add_argument('--check', action='store_true', help='Check if the description mentions all issues.')
 args = parser.parse_args()
 milestone_title: str = args.milestone_title
+check: bool = args.check
 
 page = 0
 while True:
@@ -23,6 +25,7 @@
     matching = [m for m in milestones if m['title'] == milestone_title]
     if matching:
         milestone_number = matching[0]['number']
+        milestone_description = matching[0]['description']
         break
 
 
@@ -32,13 +35,23 @@ def link(number: int) -> str:
     return escape_mask.format('', f'https://github.com/zauberzeug/nicegui/issues/{number}', f'#{number}')
 
 
-issues = httpx.get(f'{BASE_URL}/issues?milestone={milestone_number}&state=all', timeout=5).json()
+issues = []
+page = 0
+while True:
+    page += 1
+    response = httpx.get(f'{BASE_URL}/issues?milestone={milestone_number}&state=all&page={page}', timeout=5)
+    page_issues = response.json()
+    if not page_issues:
+        break
+    issues.extend(page_issues)
+
 notes: dict[str, list[str]] = {
     'New features and enhancements': [],
     'Bugfixes': [],
     'Documentation': [],
     'Testing': [],
     'Dependencies': [],
+    'Infrastructure': [],
     'Others': [],
 }
 for issue in issues:
@@ -63,6 +76,8 @@ def link(number: int) -> str:
         notes['Testing'].append(note)
     elif 'dependencies' in labels:
         notes['Dependencies'].append(note)
+    elif 'infrastructure' in labels:
+        notes['Infrastructure'].append(note)
     else:
         notes['Others'].append(note)
 
@@ -74,3 +89,8 @@ def link(number: int) -> str:
     for line in lines:
         print(f'- {line}')
     print()
+
+if check:
+    for issue in issues:
+        if f'#{issue["number"]}' not in milestone_description:
+            print(f'Issue {link(issue["number"])} is not mentioned in the milestone description')