This section provides essential documentation for the PyPositron library classes and functions. For comprehensive guides with all properties and methods, see the individual class documentation links below.

Since many PyPositron methods use CSS selectors (like querySelector and querySelectorAll), here's a quick reference for common CSS selector patterns:

• "#myId": Selects element with id="myId"
• ".myClass": Selects all elements with class="myClass"
• "div": Selects all <div> elements
• "*": Selects all elements

• "[type='text']": Selects elements with type="text"
• "[data-value]": Selects elements that have a data-value attribute
• "[href^='https']": Selects elements where href starts with "https"
• "[class*='btn']": Selects elements where class contains "btn"

• "div p": Selects all <p> elements inside <div> elements (descendant)
• "div > p": Selects all <p> elements where the parent is a <div> (child)
• "div + p": Selects the first <p> element that is placed immediately after <div> (adjacent sibling)

For complete CSS selectors reference: W3Schools CSS Selectors | MDN CSS Selectors

A wrapper for a PyPositron window with event loop thread and context. This is the object passed to your main function.

• window: The underlying webview.Window object
• context: The PositronContext object for managing execution context
• document: The Document object for DOM manipulation
• exposed: The ExposedFunctions object for interacting with exposed Python functions
• htmlwindow: The HTMLWindow object providing JavaScript window functionality

For more information: PositronWindowWrapper

Provides methods for interacting with the DOM. Available as ui.document in your main function.

• body -> Element: Gets the document body element
• title -> str: Gets or sets the title of the document
• URL -> str: Returns the full URL of the HTML document

• getElementById(element_id: str) -> Element: Gets element by ID
• getElementsByClassName(class_name: str) -> ElementList: Gets elements by class name
• querySelector(selector: str) -> Element: Gets first element matching CSS selector
• querySelectorAll(selector: str) -> ElementList: Gets all elements matching CSS selector
• createElement(tag_name: str) -> Element: Creates a new element
• addEventListener(event_type: str, callback: Callable) -> bool: Attaches event handler to document

def main(ui):
    # Get elements
    button = ui.document.getElementById("myButton")
    title = ui.document.querySelector("h1")
    
    # Set content
    ui.document.title = "My App"
    title.innerText = "Welcome!"
    
    # Add event listener
    def on_click():
        print("Button clicked!")
    button.addEventListener("click", on_click)

For more information: Document

Represents a DOM element. Returned by document methods like getElementById.

• innerText -> str: Gets or sets the text content
• innerHTML -> str: Gets or sets the HTML content
• value: Gets or sets the value (for form elements)
• style -> Style: Gets the style object for CSS manipulation
• id -> str: Gets or sets the element ID
• className -> str: Gets or sets the CSS class names

• addEventListener(event_type: str, callback: Callable) -> bool: Adds event handler
• setAttribute(name: str, value: str): Sets an attribute
• getAttribute(name: str) -> str: Gets an attribute value
• appendChild(child: Element): Appends a child element
• click(): Simulates a click on the element
• focus(): Gives focus to the element

def main(ui):
    button = ui.document.getElementById("submitBtn")
    
    # Set properties
    button.innerText = "Click Me!"
    button.style.backgroundColor = "blue"
    button.style.color = "white"
    
    # Add event handler
    def handle_click():
        button.innerText = "Clicked!"
    button.addEventListener("click", handle_click)

For more information: Element

Represents the CSS style of an element. Allows direct CSS property manipulation.

element.style.color = "red"
element.style.backgroundColor = "blue"
element.style.fontSize = "16px"
element.style.display = "none"

• color: Text color
• backgroundColor: Background color
• fontSize: Font size
• display: Display type ("block", "inline", "none")
• width, height: Element dimensions
• margin, padding: Spacing

For more information: Style

Represents a collection of DOM elements. Returned by methods like getElementsByClassName.

buttons = ui.document.getElementsByClassName("btn")

# Access by index
first_button = buttons[0]

# Iterate through elements
for button in buttons:
    button.addEventListener("click", my_handler)

# Get count
count = len(buttons)

For more information: ElementList

Provides JavaScript window functionality. Available as ui.htmlwindow.

• alert(message: str): Shows an alert dialog
• confirm(message: str) -> bool: Shows a confirm dialog
• prompt(message: str, default: str = '') -> str: Shows a prompt dialog (These ones specifically are also available in ui.document as ui.document.alert, ui.document.confirm, and ui.document.prompt)

def main(ui):
    ui.htmlwindow.alert("Welcome to my app!")
    
    if ui.htmlwindow.confirm("Do you want to continue?"):
        name = ui.htmlwindow.prompt("Enter your name:")
        print(f"Hello, {name}!")

For more information: HTMLWindow

The main function to create and display a PyPositron window.

import py_positron

def main(ui):
    # Your app code here
    pass

py_positron.openUI("index.html", main=main, width=800, height=600, title="My App")

• html_path: str: Path to the HTML file to load
• main: Callable: Function to run when window opens
• width: int: Window width (default: 900)
• height: int: Window height (default: 700)
• title: str: Window title (default: "Window")
• functions: list: List of Python functions to expose to JavaScript

For more information: Global Functions

PyPositron supports embedding Python code directly in HTML using <py> tags:

<py>
print("Hello from Python!")
button = document.getElementById("myButton")
button.innerText = "Updated from Python"
</py>

<py src="path/to/script.py"></py>

• window: The webview window object
• document: The Document object for DOM manipulation
• exposed: Access to exposed functions

For more information: Python in HTML

Browser console for debugging. Available as ui.htmlwindow.console.

Key Methods: log(), error(), warn(), clear()

For more information: Console

Browser information and navigation objects available through ui.htmlwindow.

For more information: Browser Objects

Internal classes for managing execution context and exposed functions.

For more information: Internal Classes