BROWSE / PYTHON REFERENCE

Events and navigation

React to browser events and decide what happens before matching pages load.

Developer preview · macOS · Python SDK 1.1

Event decorators

Decorator	Handler and permission
@on.request(match, frames="main")	fn(request) → decision or None. Needs requests:<pattern>.
@on.page_load(match="*")	fn(page), after a page loads. Needs pages:<pattern>.
@on.message(match="*")	fn(message, page), from your page script. Needs pages:<pattern>.
@on.tab_opened / tab_closed / tab_selected / tab_updated	fn(tab). Needs tabs. An optional match= filters by the tab URL.
@on.startup	fn(), once the extension has loaded.
@on.shutdown	fn(), with up to one second before stopping.

Import on from browse. Handlers can be ordinary or async functions. Keep request handlers quick and avoid waiting for network work in them.

Redirect a page

id = "dev.yourname.no-shorts"
name = "No Shorts"
version = "1.0.0"
permissions = ["requests:*.youtube.com"]

from browse import on

@on.request(match="*://*.youtube.com/*")
def strip_shorts(req):
    if "/shorts/" in req.url:
        return req.redirect(req.url.replace("/shorts/", "/watch?v="))

Returning None lets the navigation continue. req.block() blocks it. req.redirect(url) redirects it when the destination is also permitted. req.with_headers({"Header": "value"}) changes headers for a main-frame load; a None value removes a header.

The request object

Property	Value
url / method	The requested address and HTTP method.
frame	main or sub.
navigation	link, form, back_forward, reload or other.
tab_id / container_id	The tab and container identifiers.

Schedules and messages

from browse import every, notify

@every("15m", now=False)
async def take_a_break():
    await notify("A moment away", "Stretch or rest your eyes.")

Add notifications to permissions for this example.

Schedules run while the extension is enabled and Browse is running. The minimum interval is 10 seconds; now=True also runs the callback at startup. Notifications are limited to one per second. These are in-window messages, not guaranteed background reminders.

← All documentation