PyPositron Docs

Library Reference

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.

CSS Selectors Quick Reference

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

Basic Selectors

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

Attribute Selectors

  • "[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"

Combinators

  • "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

PositronWindowWrapper (The ui parameter)

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

Key Attributes

  • 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

Document

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

Essential Properties

  • 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

Essential Methods

  • 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

Common Usage Example

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

Element

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

Essential Properties

  • 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

Essential Methods

  • 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

Common Usage Example

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

Style

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

Usage

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

Common CSS Properties

  • 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

ElementList

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

Usage

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

HTMLWindow

Provides JavaScript window functionality. Available as ui.htmlwindow.

Essential Methods

  • 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)

Usage Example

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

Global Functions

openUI()

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")

Key Parameters

  • 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

Python in HTML (<py> tags)

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

Inline Python Code

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

External Python Files

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

Available Objects in <py> tags

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

For more information: Python in HTML

Additional Classes

Console

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

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

For more information: Console

History, Location, Navigator, Screen

Browser information and navigation objects available through ui.htmlwindow.

For more information: Browser Objects

PositronContext, ExposedFunctions

Internal classes for managing execution context and exposed functions.

For more information: Internal Classes