-
Notifications
You must be signed in to change notification settings - Fork 2
Global Functions
itzmetanjim edited this page Jul 1, 2025
·
2 revisions
PyPositron provides several global functions that serve as the main entry points for creating and managing PyPositron applications. These functions handle window creation, event loop management, and utility operations.
The primary function for creating and displaying a PyPositron window. This is the main entry point for most PyPositron applications.
openUI(html_path, main=None, after_close=None, width=900, height=700, title="Window",
functions=None, x=None, y=None, resizable=True, fullscreen=False,
min_size=(200, 100), hidden=False, frameless=False, easy_drag=True,
shadow=True, focus=True, minimized=False, maximized=False, on_top=False,
confirm_close=False, background_color='#FFFFFF', transparent=False,
text_select=False, zoomable=False, draggable=False, vibrancy=False,
gui=None, debug=False, http_server=False, http_port=None,
user_agent=None, private_mode=True, storage_path=None, icon=None) -> PositronWindowWrapper-
html_path: str: Path to the HTML file to load. This should be relative to your Python script or an absolute path.
-
main: Callable[[PositronWindowWrapper], None] | None: Function to run when the window opens. Receives a PositronWindowWrapper object as parameter. Default: None -
after_close: Callable[[PositronWindowWrapper], None] | None: Function to run when the window closes. Default: None -
functions: list | None: List of Python functions to expose to JavaScript. These become available in<py>tags and JavaScript. Default: None
-
width: int: Window width in pixels. Default: 900 -
height: int: Window height in pixels. Default: 700 -
title: str: Window title shown in the title bar. Default: "Window" -
background_color: str: Window background color in CSS format. Default: '#FFFFFF' -
icon: str | None: Path to window icon file. Only supported in Qt/GTK backends. Default: None
-
x: int | None: X coordinate of the window position. Default: None (center) -
y: int | None: Y coordinate of the window position. Default: None (center) -
min_size: tuple[int, int]: Minimum window size as (width, height). Default: (200, 100) -
resizable: bool: Whether the window can be resized. Default: True
-
hidden: bool: Whether the window is initially hidden. Default: False -
fullscreen: bool: Whether the window starts in fullscreen mode. Default: False -
minimized: bool: Whether the window is initially minimized. Default: False -
maximized: bool: Whether the window is initially maximized. Default: False -
focus: bool: Whether the window has focus when created. Default: True
-
frameless: bool: Whether the window has no frame/border (no title bar, borders). Default: False -
easy_drag: bool: Whether frameless windows can be easily dragged. Default: True -
shadow: bool: Whether the window has a drop shadow. Default: True -
on_top: bool: Whether the window stays on top of other windows. Default: False -
confirm_close: bool: Whether to show confirmation dialog when closing. Default: False -
transparent: bool: Whether the window background is transparent. Default: False -
vibrancy: bool: Whether the window has vibrancy effect on macOS. Default: False
-
text_select: bool: Whether text selection is enabled in the webview. Default: False -
zoomable: bool: Whether content can be zoomed (Ctrl+/Ctrl-). Default: False -
draggable: bool: Whether the window can be dragged. Default: False
-
gui: webview.GUIType | None: GUI toolkit to use. Options: 'qt', 'gtk', 'cef', 'mshtml', 'edgechromium', 'android'. Default: None (auto-select) -
debug: bool: Whether to enable debug mode (developer tools). Default: False -
private_mode: bool: Whether to run in private browsing mode. Default: True -
user_agent: str | None: Custom user agent string. Default: None
-
http_server: bool: Whether to serve local files using HTTP server instead of file:// protocol. Default: False -
http_port: int | None: HTTP server port. Default: None (auto-select)
-
storage_path: str | None: Path for storing browser data (cookies, localStorage, etc.). Default: None
-
PositronWindowWrapper: A wrapper object providing access to the window and context.
-
RuntimeError: If not called from the main thread -
FileNotFoundError: If the HTML file is not found
import py_positron
def main(ui):
ui.document.getElementById("title").innerText = "Hello PyPositron!"
py_positron.openUI("index.html", main=main)import py_positron
def main(ui):
# Your app logic here
pass
def on_close(ui):
print("Window is closing...")
py_positron.openUI(
"app.html",
main=main,
after_close=on_close,
width=1200,
height=800,
title="My PyPositron App",
resizable=True,
background_color="#f0f0f0"
)import py_positron
def main(ui):
# Create custom title bar since window is frameless
title_bar = ui.document.getElementById("titleBar")
close_btn = ui.document.getElementById("closeBtn")
def close_window():
ui.window.destroy()
close_btn.addEventListener("click", close_window)
py_positron.openUI(
"frameless.html",
main=main,
frameless=True,
easy_drag=True,
width=800,
height=600
)import py_positron
def calculate_sum(a, b):
return a + b
def get_system_info():
import platform
return {
"system": platform.system(),
"python_version": platform.python_version()
}
def main(ui):
# Functions are now available in JavaScript and <py> tags
pass
py_positron.openUI(
"calculator.html",
main=main,
functions=[calculate_sum, get_system_info]
)import py_positron
def main(ui):
pass
py_positron.openUI(
"debug.html",
main=main,
debug=True, # Enables developer tools
http_server=True, # Serves files via HTTP
http_port=8080
)Starts the webview event loop. This function is typically not needed as openUI() handles this automatically, but it can be useful in advanced scenarios.
start() -> Noneimport py_positron
# This is usually handled automatically by openUI()
py_positron.start()Escapes a string for safe use in JavaScript code. This is useful when dynamically generating JavaScript code or when passing Python strings that may contain special characters.
escape_js_string(string: str) -> str-
string: str: The string to escape
-
str: The escaped string safe for JavaScript
import py_positron
def main(ui):
user_input = "Hello 'World' with \"quotes\" and \n newlines"
safe_string = py_positron.escape_js_string(user_input)
# Now safe to use in JavaScript
js_code = f"console.log('{safe_string}');"
# Or when setting element content
element = ui.document.getElementById("output")
element.innerText = safe_stringProcesses and executes Python code embedded in HTML <py> tags. This function is used internally by PyPositron but can be called manually for advanced use cases.
run_python_code_in_html(html_content: str, context: PositronContext) -> str-
html_content: str: HTML content containing<py>tags -
context: PositronContext: The execution context for Python code
-
str: HTML content with<py>tags processed and executed
This function is primarily used internally, but understanding it helps when working with <py> tags:
<!-- This gets processed by run_python_code_in_html() -->
<py>
button = document.getElementById("myButton")
button.innerText = "Updated by Python!"
button.style.color = "blue"
</py>import py_positron
def add(a, b):
return float(a) + float(b)
def subtract(a, b):
return float(a) - float(b)
def multiply(a, b):
return float(a) * float(b)
def divide(a, b):
if float(b) == 0:
return "Error: Division by zero"
return float(a) / float(b)
def main(ui):
# Calculator logic
display = ui.document.getElementById("display")
buttons = ui.document.getElementsByClassName("calc-btn")
current_value = ""
operator = None
stored_value = None
def update_display():
display.value = current_value or "0"
def handle_number(num):
nonlocal current_value
current_value += str(num)
update_display()
def handle_operator(op):
nonlocal current_value, operator, stored_value
if current_value:
stored_value = float(current_value)
current_value = ""
operator = op
def calculate():
nonlocal current_value, operator, stored_value
if stored_value is not None and current_value and operator:
try:
if operator == "+":
result = add(stored_value, current_value)
elif operator == "-":
result = subtract(stored_value, current_value)
elif operator == "*":
result = multiply(stored_value, current_value)
elif operator == "/":
result = divide(stored_value, current_value)
current_value = str(result)
operator = None
stored_value = None
update_display()
except Exception as e:
current_value = "Error"
update_display()
# Set up button event handlers
for button in buttons:
value = button.getAttribute("data-value")
if value:
if value.isdigit() or value == ".":
button.addEventListener("click", lambda: handle_number(value))
elif value in ["+", "-", "*", "/"]:
button.addEventListener("click", lambda: handle_operator(value))
elif value == "=":
button.addEventListener("click", calculate)
elif value == "clear":
def clear():
nonlocal current_value, operator, stored_value
current_value = ""
operator = None
stored_value = None
update_display()
button.addEventListener("click", clear)
update_display()
py_positron.openUI(
"calculator.html",
main=main,
title="PyPositron Calculator",
width=300,
height=400,
resizable=False,
functions=[add, subtract, multiply, divide]
)import py_positron
import os
import json
def get_directory_contents(path):
try:
items = []
for item in os.listdir(path):
item_path = os.path.join(path, item)
items.append({
"name": item,
"path": item_path,
"is_directory": os.path.isdir(item_path),
"size": os.path.getsize(item_path) if os.path.isfile(item_path) else 0
})
return items
except Exception as e:
return []
def main(ui):
current_path = os.getcwd()
path_display = ui.document.getElementById("currentPath")
file_list = ui.document.getElementById("fileList")
def update_file_list():
nonlocal current_path
path_display.innerText = current_path
file_list.innerHTML = ""
contents = get_directory_contents(current_path)
# Add parent directory option
if current_path != os.path.dirname(current_path):
parent_item = ui.document.createElement("div")
parent_item.className = "file-item directory"
parent_item.innerText = ".."
parent_item.addEventListener("click", lambda: navigate_to(os.path.dirname(current_path)))
file_list.appendChild(parent_item)
# Add files and directories
for item in contents:
item_element = ui.document.createElement("div")
item_element.className = f"file-item {'directory' if item['is_directory'] else 'file'}"
item_element.innerText = item['name']
if item['is_directory']:
item_element.addEventListener("click", lambda: navigate_to(item['path']))
file_list.appendChild(item_element)
def navigate_to(path):
nonlocal current_path
if os.path.isdir(path):
current_path = path
update_file_list()
# Initial load
update_file_list()
py_positron.openUI(
"filemanager.html",
main=main,
title="PyPositron File Manager",
width=800,
height=600,
functions=[get_directory_contents]
)-
Keep the main function focused: Use the main function primarily for UI setup and event binding.
-
Handle errors gracefully: Always wrap potentially failing operations in try-catch blocks.
-
Use appropriate window settings: Choose window parameters that make sense for your application type.
-
Expose only necessary functions: Only expose Python functions to JavaScript that are actually needed.
-
Clean up resources: Use the
after_closecallback to clean up any resources when the window closes. -
Test different backends: If you encounter issues, try different GUI backends using the
guiparameter. -
Use debug mode during development: Enable debug mode to access developer tools for easier debugging.
# Good practice example
import py_positron
import logging
def safe_file_operation(filename):
try:
with open(filename, 'r') as f:
return f.read()
except Exception as e:
logging.error(f"File operation failed: {e}")
return f"Error: {str(e)}"
def main(ui):
try:
# Initialize UI components
setup_event_handlers(ui)
load_initial_data(ui)
except Exception as e:
ui.htmlwindow.alert(f"Initialization error: {e}")
def cleanup(ui):
# Clean up resources
logging.info("Application closing")
py_positron.openUI(
"app.html",
main=main,
after_close=cleanup,
debug=True, # Enable during development
functions=[safe_file_operation]
)-
PositronWindowWrapper: The object returned by
openUI() -
Python in HTML: Using
<py>tags and exposed functions - Document: DOM manipulation
- HTMLWindow: Browser window functionality