App and running

        Everything you need to start an application. See also the
        [architecture](/pyzed/guides/architecture/) guide.

See also multiple windows and async and subscriptions.

Application

App

Base class for applications (Elm architecture, like Iced). It is also the main window, so it inherits everything from Window. Override view() and, if you use messages, update(message). State lives in instance attributes.

Class attribute	Default	Description
title	"Pyzed"	Window title. Can be a callable (or property) that returns the text.
size	(1280, 800)	Initial window size.
font_size	14	Default text size.
theme	themes.ONE_DARK	A Theme, the name of a registered theme or themes.auto(light, dark). Change it at any time.
style	None	The global style: a pz.Style for the whole window. Its text color, size, background, border color and radius become theme tokens. See Styles.
system_dark	True	Whether the system is in dark mode (updated by the runtime).
tab_focus	True	Tab and Shift+Tab move the focus between the fields of the window. See Accessibility.
splash	None	A Splash window shown before the main window opens.
rendering	None	A Rendering: GPU or CPU, graphics API, GPU and vsync. None reads [tool.pyzed.rendering] of the project’s pyproject.toml.

The remaining window options (min_size, resizable, decorations, icon, scale…) are on Window.

Method	Description
view()	Returns the widget tree. Called after every message.
update(message)	Receives messages. Can return a Command, a list of them, a coroutine, a generator (regular or async) or another message.
on_start()	Optional. Runs once at startup; can return a Command or a coroutine.
on_key(combo)	Optional. Receives every key as "ctrl-shift-p", "escape", "up"…
on_key_up(key)	Optional. Receives key releases by name ("left", "space").
subscriptions()	Optional. Returns the active subscriptions (pz.every, pz.listen). Re-evaluated after every update.
resolved_theme()	The concrete Theme in use (resolves names and themes.auto).
run()	Opens the window and blocks until the app exits.
screenshot(path, *, size=None, scale=2.0, wait=0.1)	Renders the current state to a PNG without a window.

If view() raises an exception, the window shows the traceback instead of closing.

Methods and properties

App.subscriptions

App.subscriptions()

Timers and streams that should run right now (re-evaluated after every update).

App.run

App.run(*, reload=None, watch=())

Opens the window and blocks until the app exits.

App.screenshot

App.screenshot(path, *, size=None, scale=2.0, wait=0.1)

Renders the current state off-screen (no GPU or display needed) into a PNG.

run

run(app, *, reload=None, watch=())

Runs an app: opens the window and blocks until it is closed. Accepts the class or an instance.

Parameter	Description
app	An App instance (or the class, which is instantiated with no arguments).
reload	Hot reload: saving a project file updates the running window and keeps its state. None follows PYZED_RELOAD (set by pyzed dev).
watch	Extra folders or files to watch for hot reload.

screenshot

screenshot(app, path, *, size=None, scale=2.0, wait=0.1)

Renders app offscreen (no window, no GPU) and saves a PNG. Useful for tests and documentation.

Parameter	Description
app	An App instance (or the class, which is instantiated with no arguments).
path	Path of the output PNG.
size	Logical size (width, height). Defaults to app.size.
scale	PNG scale factor (2.0 = retina).
wait	Seconds to wait before capturing (for on_start tasks).

pz.screenshot(MyApp, "docs/ui.png", size=(800, 600))

post

post(message)

Sends a message to the running app from any thread. Raises RuntimeError if no app is running.

Parameter	Description
message	Any Python value, or a callable.

def worker():
    for i in range(100):
        time.sleep(0.05)
        pz.post(("progress", i / 100))

threading.Thread(target=worker, daemon=True).start()

UNCHANGED

UNCHANGED(...)

Return it from a callback that changed nothing on screen (a pointer move you only record, a focus change): the window is not rebuilt. Any other return value redraws as usual. See the performance guide.

def pointer_moved(self, x, y):
    self.pointer = (x, y)
    return pz.UNCHANGED  # nothing visible changed: no rebuild

load_font

load_font(source)

Loads an extra font (path to a .ttf/.otf or its bytes) so you can use it by family name: text("hello", font="JetBrains Mono").

Parameter	Description
source	Path to the font file, or bytes.

Windows

Window

An extra window with its own view(), title, size and theme. Open it by returning window.open() (or Command.open_window(window)). Inside it, self.app is the app, so windows share state; the messages it produces go to its update(), which by default forwards them to app.update().

Attribute	Default	Description
title	"Pyzed"	Text or callable.
size	(800, 600)	Initial size.
min_size, max_size	None	Size limits.
position	None	"center" or (x, y).
resizable	True	Whether it can be resized.
decorations	True	False removes the system frame (custom title bar with drag()).
transparent, maximized, fullscreen	False	Initial state.
scale	1.0	UI scale.
theme	None	Its own theme; None uses the app’s.
style	None	Its own global style; None uses the app’s.
icon	None	The window’s icon (title bar, taskbar): a path to an image or its bytes. Set it on pz.Window to give every window the same one. See Icons and metadata.
app_id	None	Linux: the app id the desktop matches with a .desktop file (com.acme.shop).
app	—	The app that owns the window (assigned when it opens).
window_size	—	Current size in logical pixels (updated by the runtime).
window_position	—	Where the window is on the screen, its outer top-left corner (updated by the runtime; None on Wayland).

Method	Description
view()	Required. Returns the window’s widget tree.
update(message)	Receives the window’s messages (by default forwards them to the app).
open() / close() / drag()	Commands to open it, close it or start moving it.
is_open	Whether it is open.
resolved_theme()	The concrete Theme it uses.
on_open()	When it opens.
on_close()	When the user asks to close it; return False to prevent it.
on_resize(width, height)	When it is resized.
on_key(combo), subscriptions()	As in App.
on_file_hover(path), on_file_drop(path), on_file_leave()	Files dragged from the system over the window, dropped on it (once per file) or taken away. By default they go to the ui.DropZone they land on.

Methods and properties

Window.view

Window.view()

Returns the window’s root widget; subclasses must override it.

Window.update

Window.update(message)

Handles a message produced in this window (forwards to the app by default).

Window.on_close

Window.on_close()

Called when the user asks to close the window. Return False to keep it open.

Window.on_file_hover

Window.on_file_hover(path)

A file dragged from the system is over the window: lights up the ui.DropZone it would land on.

Window.on_file_drop

Window.on_file_drop(path)

A file was dropped on the window from the system (once per file): goes to a ui.DropZone.

Window.on_file_leave

Window.on_file_leave()

The files dragged over the window left it without being dropped.

Window.is_open

Window.is_open  # property

Whether the window is currently open.

Window.open

Window.open()

A command that opens this window: return settings.open().

Window.close

Window.close()

A command that closes this window: on_press=self.close.

Window.drag

Window.drag()

A command that starts moving the window (for custom title bars).

Window.minimize

Window.minimize()

A command that minimizes the window.

Window.toggle_maximize

Window.toggle_maximize()

A command that maximizes the window, or restores it when it is maximized.

Window.frame_menus

Window.frame_menus()

The menus on the left of a custom frame’s title bar (frame = "custom"): a list of ui.Menu.

Window.resolved_theme

Window.resolved_theme()

The concrete theme this window uses right now (with its global style’s colors and sizes).

Window.resolved_style

Window.resolved_style()

The global style of this window: pz.set_style with its own (or the app’s) style on top.

Splash

class Splash

A splash screen: a frameless window with an image, centered on the screen, shown while the app starts. Give it to App.splash; it stays up for duration seconds at least, then the main window opens and the splash closes. See Splash screen.

Parameter	Description
image	Path to the picture (PNG, JPEG…) or its bytes.
duration	Seconds it stays up, at least.
size	Window size; default: the image’s, scaled down to fit 900 × 600.
text	Text written over the bottom of the image (for example "Loading…").
color	Color of the text.
background	Color behind the image (for pictures with transparency).
title	Window title (the taskbar shows it).
icon	Window icon.

class Shop(pz.App):
    splash = pz.Splash("assets/splash.png", duration=1.5, text="Loading…")

Rendering

@dataclass
class Rendering(renderer='auto', gpu_api='auto', power='auto', vsync='auto')

How the app draws its windows: on the GPU or the CPU, which graphics API, which GPU and vsync. Each field is "auto" by default (Pyzed decides). Give it to App.rendering, or set the same keys in [tool.pyzed.rendering] of the project’s pyproject.toml, which pz.run, the designer and pyzed build read. See Rendering.

Parameter	Description
renderer	"auto", "gpu" (needed by shaders) or "cpu" (tiny-skia: starts faster, less memory, works everywhere).
gpu_api	"auto", "vulkan", "metal", "dx12" or "gl".
power	"auto", "high" (the dedicated GPU) or "low" (the integrated one, saves battery).
vsync	"auto", "on" (no tearing) or "off" (draws as fast as it can).

class Game(pz.App):
    rendering = pz.Rendering(renderer="gpu", vsync="off")

Methods and properties

Rendering.from_table

@classmethod
Rendering.from_table(table)

Builds the settings from a [tool.pyzed.rendering] table, ignoring unknown keys and values.

Rendering.to_table

Rendering.to_table()

The settings that are not "auto", as written to pyproject.toml.

Rendering.custom

Rendering.custom  # property

Whether any setting is not "auto".

Rendering.env

Rendering.env()

The environment variables that carry these settings to Iced and wgpu.

Rendering.apply

Rendering.apply(environ=None)

Sets the variables of env() that are not set yet (yours win); returns the ones it set.

Async and subscriptions

every

every(seconds, message, *, key=None)

A subscription that sends message to update every seconds seconds (like Iced’s time::every). If message is a callable, it is called. Return it from subscriptions().

Parameter	Description
seconds	Interval in seconds (greater than 0).
message	Any Python value, or a callable.
key	Key that identifies the subscription (defaults to the message or the function).

def subscriptions(self):
    return [pz.every(1, "tick")] if self.running else []

listen

listen(function, *, key=None)

A subscription that runs function() (a generator or async generator) while it is active and sends every value it yields to update. Ideal for websockets and streams.

Parameter	Description
function	Generator function (regular or async def).
key	Key that identifies the subscription (defaults to the message or the function).

async def feed():
    async for message in websocket:
        yield message

def subscriptions(self):
    return [pz.listen(feed)]

frames

frames(callback, *, key=None, max_fps=240.0)

A subscription that calls callback(dt) once per displayed frame (in sync with the screen, usually 60 times a second), with dt the seconds since the previous frame (at most 0.25). Made for games and simulations: move things by speed * dt. See Making games.

Parameter	Description
callback	Callable that receives dt (a float).
key	Key that identifies the subscription (defaults to the message or the function).
max_fps	Highest rate where the display does not wait for vsync (software rendering). Default 240.

def subscriptions(self):
    return [] if self.paused else [pz.frames(self.tick)]

def tick(self, dt):
    self.x += game.axis("left", "right") * 300 * dt

pressed

pressed()

The keys held down right now, as a frozenset of names without modifiers ("left", "space", "a"…). Empty when no window is open. Poll it every frame for continuous movement; on_key is for one-off presses.

is_pressed

is_pressed(*keys, held=None)

Whether any of keys is held down. held replaces pressed() (handy in tests).

Parameter	Description
keys	Key names, such as "left", "a".
held	Optional set of keys to use instead of pressed().

if pz.is_pressed("space") and self.cooldown <= 0:
    self.fire()

Subscription

What every and listen return. It is identified by its key: as long as subscriptions() keeps returning one with the same key, it keeps running; when it disappears, it stops.

spawn

spawn(awaitable)

Schedules a coroutine on Pyzed’s asyncio loop without waiting for its result and returns a concurrent.futures.Future. To receive the result in the UI, return the coroutine from update or use Command.perform.

Parameter	Description
awaitable	The coroutine.

asyncio_loop

asyncio_loop()

The asyncio loop (on a background thread) where Pyzed runs every coroutine. It starts the first time it is used.

Events and components

on

on(widget, *, cursor=None, **handlers)

Attaches common event handlers to a widget; same as widget.on(...). Events: click, double_click, right_click, middle_click, mouse_down, mouse_up, mouse_enter, mouse_leave, mouse_move, scroll, drag_start, drag, drag_end, focus, blur, key_down, key_up, resize. See Events.

Parameter	Description
widget	The widget (a string is wrapped in a container).
cursor	Mouse cursor over the widget, such as "pointer" or "grab".
handlers	event=handler pairs. A handler that takes an argument gets a pz.Event; a non-callable value is a message for update; None removes it.

pz.container(card, padding=12).on(click=self.select, drag=lambda e: self.move(e.dx, e.dy))

Event

class Event

What happened, passed to event handlers: type, x, y (relative to the widget), dx, dy (scroll or drag movement), width, height, button, key, shift, ctrl, alt, logo, window_x, window_y, screen_x, screen_y (the pointer in the window and on the screen), and value/source for custom events.

Parameter	Description
type	Event name.
x	Pointer x, relative to the widget.
y	Pointer y, relative to the widget.
dx	Horizontal scroll (lines) or drag movement.
dy	Vertical scroll (lines) or drag movement.
width	Widget width.
height	Widget height.
button	"left", "right", "middle"…
key	Key combo, such as "ctrl-s".
shift	Shift held.
ctrl	Control held.
alt	Alt held.
logo	Cmd/Windows key held.
value	Value of a custom event.
source	Component that emitted it.
window_x	Pointer x in the window (outside it when a drag is released outside).
window_y	Pointer y in the window.
screen_x	Pointer x on the screen, or None where the platform does not say where windows are (Wayland). event.screen gives (screen_x, screen_y).
screen_y	Pointer y on the screen, or None.

Methods and properties

Event.position

Event.position  # property

(x, y).

Event.size

Event.size  # property

(width, height).

Event.screen

Event.screen  # property

(screen_x, screen_y), or None when the platform does not report window positions.

Dock

class Dock

An editor-style workspace: a center with pz.DockPanels docked left, right, bottom or top. Users resize a side by dragging its inner edge and move a panel by dragging its tab onto a drop zone (or from the tab’s right-click menu). on_layout receives the layout as a dict to save; pass it back as layout=. See Layout.

Parameter	Description
args	Props by position: center, panels, layout.
key	Key that identifies the subscription (defaults to the message or the function).
kwargs	Props and handlers by name, plus key=.

pz.Dock(center=editor, panels=[
    pz.DockPanel("project", "Project", tree, icon="folder", side="left"),
    pz.DockPanel("terminal", "Terminal", terminal, icon="terminal", side="bottom"),
], layout=self.layout, on_layout=lambda e: setattr(self, "layout", e.value))

Methods and properties

Dock.side_of

Dock.side_of(panel)

Returns the side a panel is docked on: its saved position if valid, else panel.side.

Dock.groups

Dock.groups()

Returns the panels grouped by side (every side present, possibly with an empty list).

Dock.snapshot

Dock.snapshot()

Returns the layout as a plain dict (positions, sizes, active, hidden).

Dock.changed

Dock.changed()

Emits layout with the current snapshot.

Dock.move

Dock.move(panel_id, side)

Docks a panel on another side and makes it the active tab there.

Dock.select

Dock.select(side, panel_id)

Makes panel_id the active tab on side (a tab click) and emits layout.

Dock.toggle

Dock.toggle(side)

Shows or hides a whole side.

Dock.resized

Dock.resized(side, size)

Records the new size (pixels) of side after its edge is dragged and emits layout.

Dock.start_drag

Dock.start_drag(panel_id)

Starts dragging a panel’s tab: the drop zones show and the tab menu closes.

Dock.end_drag

Dock.end_drag()

Ends a tab drag and hides the drop zones, remembering the panel for a late drop.

Dock.drop

Dock.drop(side)

Moves the dragged panel to side when released on that drop zone; no-op without one.

Dock.tab

Dock.tab(panel, side, active, t)

Builds a panel’s tab in a side’s header.

Dock.move_menu

Dock.move_menu(panel, side, t)

Builds the right-click menu that moves panel to any side other than side.

Dock.side_view

Dock.side_view(side, panels, t)

Builds one side: a header with the panels’ tabs above the active panel’s content.

Dock.drop_zones

Dock.drop_zones(t)

Builds the four drop zones (one per side) shown over the dock while a tab is dragged.

DockPanel

class DockPanel

A panel for pz.Dock.

Parameter	Description
id	Stable id (used in the saved layout).
title	Tab title.
content	The panel’s widget.
icon	Lucide icon for the tab.
side	Starting side: "left", "right", "bottom" or "top".

Component

class Component

Base class for custom components, like React components: annotated class attributes are props, other attributes are state kept between renders, render() returns widgets and events declares custom events raised with self.emit(name, value). Calling the class returns a widget. Components appear in the designer’s toolbox. See Custom components.

Parameter	Description
args	Props, in declaration order (or the children, when the class has a children prop).
key	Key that identifies the subscription (defaults to the message or the function).
kwargs	Props by name, on_<event>= handlers (custom, lifecycle or common events), key= to keep state when items move, and style=, class_=, id= and animate=.

class Rating(pz.Component):
    value: int = 0
    events = {"change": "A star was picked."}

    def render(self):
        return pz.row([pz.text("★").on(click=lambda i=i: self.emit("change", i)) for i in range(1, 6)])

Rating(value=3, on_change=lambda e: print(e.value))

Methods and properties

Component.refresh

Component.refresh()

Draws the component again on the next view(), even if its props and state are the same.

Component.create

@classmethod
Component.create(*args, **kwargs)

A standalone instance (not rendered, no lifecycle), handy in tests: c.render().

Component.setup

Component.setup()

Called once before the first render (props are already set): initialize state here.

Component.render

Component.render()

Returns the widgets of this component (called on every render).

Component.provide

Component.provide()

Values to share with every component this one renders (read with pz.use_context).

Component.context

Component.context(name, default=None)

The closest shared value called name (see pz.provide).

Component.on_mount

Component.on_mount()

Called after the first render; may return a Command or a message.

Component.on_unmount

Component.on_unmount()

Called when the component is no longer rendered.

Component.emit

Component.emit(name, value=None)

Raises the custom event name: calls the handler the parent passed as on_<name>.

Component.handles

Component.handles(name)

Whether the parent passed a handler for the custom event name.

Component.describe

@classmethod
Component.describe()

The first paragraph of the docstring on one line, in Markdown (shown in the designer).

Component.designer_spec

@classmethod
Component.designer_spec()

This component as an entry of the designer’s toolbox (pyzed.designer.Component).

Color

class Color

Type hint for a component prop that holds a color (a theme token or "#rrggbb"): the designer shows a color picker for it. A plain str at run time.

tint: pz.Color = "accent"

Icon

class Icon

Type hint for a component prop that holds a Lucide icon name: the designer shows an icon picker for it. A plain str at run time.

mark: pz.Icon = "star"

Multiline

class Multiline

Type hint for a component prop that holds long text: the designer shows a text area for it. A plain str at run time.

notes: pz.Multiline = ""

FilePath

class FilePath

Type hint for a component prop that holds a file path: the designer shows the path with a button that opens the system’s file dialog (a pathlib.Path annotation does the same). A plain str at run time.

logo: pz.FilePath = ""

FolderPath

class FolderPath

Type hint for a component prop that holds a folder: the designer shows the path with a button that opens the system’s folder dialog. A plain str at run time.

output: pz.FolderPath = ""

Range

@dataclass
class Range(min, max, step=1)

Limits of a number prop, used with typing.Annotated: the designer shows a number box limited to them. See Custom components.

Parameter	Description
min	Lowest value.
max	Highest value.
step	Step of the + and - buttons.

level: Annotated[int, pz.Range(0, 10)] = 3

provide

provide(**values)

A context manager that shares values with every component rendered inside, like React’s context. Read them with pz.use_context(name) or self.context(name). A component’s provide() method does the same for what it renders. See Children, context and styles.

Parameter	Description
values	The values, by name.

with pz.provide(user=self.user):
    page = Dashboard()

use_context

use_context(name, default=None)

The closest value shared as name with pz.provide or a component’s provide().

Parameter	Description
name	The value’s name.
default	Returned when nothing shares it.

state

state(default=None, *, doc='')

Declares a private state variable on a component class: the parent cannot pass it, and every instance starts with its own copy of the default (lists and dicts are safe). The designer lists it next to the props. See Custom components.

Parameter	Description
default	Initial value, copied for each instance.
doc	Description shown in the designer.

class Counter(pz.Component):
    step: int = 1
    count: int = pz.state(0)

State

class State

The default of a state variable declared on the class (see state).

StateInfo

class StateInfo

A state variable declared with pz.state: its name, annotation, default and description.

PropInfo

class PropInfo

A prop: its name, type annotation (may be a string) and default.

Methods and properties

PropInfo.required

PropInfo.required  # property

Whether the prop has no default and must be passed.

find

find(type_name)

The component class registered as type_name (see Component.type_name).

registered

registered()

Every Component subclass defined so far that should appear in the designer.

render_pass

render_pass(owner)

Tracks the components rendered while owner (a window) runs its view().

Components not rendered again are unmounted at the end. The runtime does this for every window; use it yourself only to render components outside a window.

EventInfo

class EventInfo

Documentation of one event: its group and what it reports.

accepts_argument

accepts_argument(handler)

Whether handler takes the event: it has a required positional parameter or *args.

Parameters with defaults do not count, so lambda i=i: ... is called with nothing. The answer is cached per function.

LIFECYCLE_EVENTS

Names of the lifecycle events every component raises (mount, unmount…).

CATALOG

Every event name Pyzed knows, mapped to its EventInfo (what raises it and what event.value holds).

COMMON

The events every widget accepts through widget.on(...) (click, hover, focus, keys…).

Hot reload

enable

enable(app, paths=(), *, interval=0.25)

Starts hot reload for app (a running App instance) and returns the reloader.

current

current()

The active Reloader, or None when hot reload is off.

is_reloading

is_reloading()

True while modules are being re-executed by a reload.

enabled_by_env

enabled_by_env()

Whether PYZED_RELOAD asks for hot reload (1, true, yes or on).

Reloader

class Reloader

Watches the project’s files and reloads changed code into a running app.

app is the running App instance. paths are extra folders or files to watch; by default the folder of the module that defines the app’s class is watched. interval is how often, in seconds, files are checked for changes.

Most programs never create one directly: pz.run(app, reload=True) does it.

Methods and properties

Reloader.watch

Reloader.watch(path, callback)

Calls callback(path) on the UI thread whenever path changes.

Reloader.project_modules

Reloader.project_modules()

The loaded modules whose files belong to the project, by file path.

Reloader.scan

Reloader.scan()

Checks every watched file once and returns the ones that changed.

Reloader.start

Reloader.start()

Starts the watcher thread and makes this the current reloader.

Reloader.stop

Reloader.stop()

Stops watching files.

Reloader.reload

Reloader.reload(changed)

Reloads the code in changed files now (call it on the UI thread).

ReloadError

class ReloadError

Raised by view() while the last reload failed; the window shows its message.

Change

@dataclass
class Change(name, changed=[], added=[], removed=[], new_state=[], updated_state=[])

What one reload changed in a class (see Reloader.changes).

remember

remember(obj)

Records the initial plain values of obj (once), so a reload can tell what the app changed.

The runtime calls it for the app, each window and each component; call it for other objects created after hot reload started only if you need their defaults updated too.

Languages

t

t(key, *, language=None, default=None, **values)

The text for key in the current language, formatted with values. Falls back from "es_AR" to "es", then to the fallback language, then to the key. See Languages.

Parameter	Description
key	Dotted key, like "menu.open".
language	Look it up in another language.
default	Returned when the key is missing (default: the key).
values	Values for {name} placeholders; count= also picks the plural form.

i18n.add("es", {"greeting": "¡Hola, {name}!", "files": {"one": "{count} archivo", "other": "{count} archivos"}})
i18n.set_language("es")
pz.t("greeting", name="Kev"), pz.t("files", count=3)

add

add(language, catalog)

Adds or overrides texts for a language. Nested tables become dotted keys; {"one": ..., "other": ...} tables are plural forms.

Parameter	Description
language	Language code, like "es" or "pt_BR".
catalog	Dict of texts.

load

load(folder)

Loads every <language>.json and <language>.toml in folder; returns the languages found.

Parameter	Description
folder	Folder with the catalog files.

set_language

set_language(language)

Switches the language. The app shows it on its next render, so call it from a handler.

Parameter	Description
language	Language code, like "es".

language

language()

The current language, normalized ("es_ar").

languages

languages()

The languages with a catalog.

set_fallback

set_fallback(language)

The language used when a text is missing (default "en").

Parameter	Description
language	Language code.

on_change

on_change(listener)

Calls listener(language) after every switch; returns a function that removes it.

Parameter	Description
listener	Callable that receives the new language.

system_language

system_language(default='en')

The operating system’s language (LANG, LC_ALL or the locale).

Parameter	Description
default	Returned when the system reports none.

has

has(key, *, language=None)

Whether key has a text in the language or its fallbacks.

Parameter	Description
key	Dotted key.
language	Language to check (default: the current one).

normalize

normalize(language)

"es-AR", "es_AR.UTF-8" -> "es_ar".

Built-in reference

Browser

class Browser

What a reference viewer shows: the search text, the page open and the back/forward history.

ui.reference_browser(browser) draws it; its buttons and links call the methods below.

Methods and properties

Browser.open

Browser.open(id)

Shows the page id (returns False when there is no such page).

Browser.open_symbol

Browser.open_symbol(symbol)

Shows the page about a name written in code; returns whether one was found.

Browser.back

Browser.back()

Goes to the previous page.

Browser.forward

Browser.forward()

Goes to the next page after going back.

Browser.set_query

Browser.set_query(query)

Changes the search text.

Browser.toggle

Browser.toggle(section)

Folds or unfolds a section of the class list.

Browser.results

Browser.results()

The entries matching the search text.

Browser.page

Browser.page()

The page shown (None before one is opened).

Browser.follow

Browser.follow(url)

Handles a link of a page: internal links open their page; returns the URL to open otherwise.

Entry

@dataclass
class Entry(id, title, section, group='', summary='', icon='book-open', kind='function')

One page of the reference, as search results and the class list show it.

Page

@dataclass
class Page(entry, body, url=None)

A full page: the entry it belongs to and its body in Markdown.

Methods and properties

Page.id

Page.id  # property

The entry’s id.

Page.title

Page.title  # property

The entry’s title.

Provider

@dataclass
class Provider(name, entries, page, lookup=None)

A section of the reference that comes from somewhere else than the library’s API pages.

entries(lang) lists its pages, page(id, lang) builds one (None when the id is not its own) and lookup(symbol) turns a name written in code into one of its ids.

register

register(provider)

Adds a section to the reference (it replaces one with the same name).

entries

entries(lang=None)

Every page of the reference, in class-list order (designer controls first, then the library).

sections

sections(lang=None)

The class list: [(section, [(group, [entries]), ...]), ...] in order.

search

search(query, lang=None, limit=60)

Entries matching query: exact names first, then names that start with it, then the rest.

Every word must appear in the title, group or summary ("tab bar" finds ui.tab_bar).

page

page(id, lang=None)

The page with id (KeyError when there is none).

lookup

lookup(symbol)

The id of the page about a name written in code ("pz.text", "ui.button", "Theme"…).

languages

languages()

The languages the API descriptions are available in.

tables_as_lists

tables_as_lists(markdown)

Markdown tables turned into bullet lists (- first cell: the other cells).

For viewers whose tables don’t wrap long cells, such as ui.reference_browser in a narrow tab. Code blocks are left alone.

display_name

display_name(name)

"pyzed.text" -> "pz.text", "pyzed.ui.button" -> "ui.button".

summary

summary(markdown)

The first sentence of a Markdown text, without formatting (for lists and search results).

Forms and validation

validation_errors

validation_errors(error)

Turns a validation error into {field: message}, ready for ui.field(..., error=). Accepts a Pydantic or SQLModel ValidationError, a Django ValidationError, the JSON of a FastAPI 422 response ({"detail": [...]}) or its detail list. Nested fields are joined with dots and errors that belong to no field use the key "". Only the first message of each field is kept. See Integrations.

Parameter	Description
error	The error, or the JSON of the response.

try:
    item = ItemIn.model_validate(self.draft)
except ValidationError as error:
    self.errors = pz.validation_errors(error)

ui.field("Price", ui.input(self.draft["price"], self.set_price), error=self.errors.get("price"))