API reference¶

This page documents the key functions and classes available when building uproot experiments. All of these are available automatically in app modules via from uproot.smithereens import * and from uproot.fields import *.

Page types¶

Page¶

The standard page type. Displays a template and optionally collects form data.

class MyPage(Page):
    fields = dict(participant_name=StringField(label="Your name"))

    @classmethod
    def templatevars(page, player):
        return dict(greeting="Hello")

See Page methods for all available methods.

NoshowPage¶

A page that runs logic without displaying anything to the participant.

class Calculate(NoshowPage):
    @classmethod
    def after_always_once(page, player):
        player.payoff = player.correct * 10

GroupCreatingWait¶

A wait page that forms groups of participants.

class GroupPlease(GroupCreatingWait):
    group_size = 2

    @classmethod
    def after_grouping(page, group):
        for player, role in zip(group.players, ["proposer", "responder"]):
            player.role = role

SynchronizingWait¶

A wait page that synchronizes group or session members.

class Sync(SynchronizingWait):
    @classmethod
    def all_here(page, group):
        for player in group.players:
            set_payoff(player)

Set synchronize = "session" to synchronize across the entire session.

SmoothOperators¶

Random¶

Shuffles pages into a random order per participant.

page_order = [Random(TaskA, TaskB, TaskC)]

Bracket¶

Groups pages as an atomic unit within Random.

page_order = [Random(Bracket(Intro1, Task1), Bracket(Intro2, Task2))]

Rounds¶

Repeats pages a fixed number of times. Sets player.round (1-indexed).

page_order = [Rounds(Decision, Feedback, n=5)]

Repeat¶

Repeats pages indefinitely until player.add_round = False.

page_order = [Repeat(Trial, Check), Done]

Between¶

Randomly selects one option per participant. Records selection in player.between_showed.

page_order = [Between(Treatment, Control)]

PlayerContext¶

Base class for computed properties available in templates as player.context.*.

class Context(PlayerContext):
    @property
    def earnings(self):
        return self.player.payoff * C.EXCHANGE_RATE

Real-time functions¶

notify¶

Send data from one player to one or more recipients.

notify(sender, recipients, data, event="EventName", where=...)

Parameter	Description
`sender`	The sending player (determines page context)
`recipients`	Player, `StorageBunch`, or list of players
`data`	Any JSON-serializable data
`event`	Custom event name (default: `"_uproot_Received"`)
`where`	Recipient page index; `...` delivers regardless of page

send_to¶

Send data to one or more players without a sender context.

send_to(recipients, data, event="EventName", where=...)

send_to_one¶

Send data to a single player.

send_to_one(player, data, event="EventName", where=...)

reload¶

Force a player's browser to reload the current page.

reload(player)

move_to_page¶

Move a player to a specific page.

move_to_page(player, TargetPage, reload_=True)

move_to_end¶

Move a player past all remaining pages.

move_to_end(player, reload_=True)

spawn¶

Run an async function as a supervised background task. The task keeps running after the calling method returns. Exceptions are logged, and all spawned tasks are cancelled at server shutdown. Tasks do not survive server restarts.

spawn(my_coroutine(player))

Because spawned tasks run outside a page method, wrap data mutations in a context manager (with player as p:). See Background tasks for examples.

Dropout functions¶

watch_for_dropout¶

Monitor a player for disconnection and call a handler when they go offline.

watch_for_dropout(player, handler, tolerance=30.0)

mark_dropout¶

Add a player to the manual dropout set used by the dropout watcher.

mark_dropout(player_pid)

Group functions¶

create_group¶

Create a group from a list of players.

gid = create_group(session, [player1, player2], gname="custom_name", overwrite=False)

create_groups¶

Create multiple groups at once.

gids = create_groups(session, [[p1, p2], [p3, p4]])

add_to_group¶

Add players to an existing group.

add_to_group(group, player)
add_to_group(group, [player1, player2])
add_to_group(group, player, overwrite=True)  # reassign players already in a group

The @live decorator¶

Makes a page method callable from JavaScript via WebSocket.

class MyPage(Page):
    @live
    async def my_method(page, player, arg: str):
        return {"result": arg.upper()}

Called from JavaScript:

uproot.invoke("my_method", "hello").then(data => console.log(data.result));

App HTTP APIs¶

Apps may expose HTTP endpoints by defining api(request, session) or api2(request, session).

api is served at /api/{appname}/{sname}/ and requires an Authorization: Bearer ... header matching one of the server API keys in upd.API_KEYS. Use it for programmatic access that should be limited to trusted operators or scripts.

api2 is served at /api2/{appname}/{sname}/ and is intentionally unauthenticated. It is for participant-browser assets and callbacks, such as loading a captcha image. Anyone who knows the app name and session name can call it.

Trust boundary

Treat every api2 request as public, untrusted input. Do not expose secrets, admin-only data, participant answers from other players, or state-changing operations that should require an API key. If a route needs authentication, implement it with api, not api2.

Utility functions¶

cu¶

Create a Decimal from a string. Shorthand for Decimal(value).

endowment = cu("10.00")

safe¶

Mark a string as HTML-safe (won't be escaped in templates).

label=StringField(label=safe("Enter a value <b>in euros</b>"))

data_uri¶

Convert binary data to a data URI string for embedding in HTML.

player.image_uri = data_uri(image_bytes)

The MIME type is inferred from common file signatures such as JPEG, PNG, GIF, PDF, ZIP, and MP4. Unknown data is emitted as application/octet-stream.

Identifier types¶

Type	Description
`PlayerIdentifier`	Uniquely identifies a player
`SessionIdentifier`	Uniquely identifies a session
`GroupIdentifier`	Uniquely identifies a group
`ModelIdentifier`	Uniquely identifies a model

These are used internally and in custom data models.

StorageBunch¶

A collection of storage objects (players, groups) with query methods.

Method	Description
`len(bunch)`	Number of items
`bunch[i]`	Get by index
`item in bunch`	Membership test
`bunch.filter(*.comparisons)`	Filter by field values using `_`
`bunch.find_one(**kwargs)`	Find exactly one match
`bunch.assign(key, values)`	Set a field on all items
`bunch.each(*keys)`	Extract fields from all items
`bunch.apply(fn)`	Apply a function to all items

The `_` field referent¶

_ is a FieldReferent — a placeholder that stands for each item in the collection. It builds lazy comparison objects that are evaluated per item during filter().

# _ is auto-imported via `from uproot.smithereens import *`
cooperators = group.players.filter(_.cooperate == True)
high_earners = session.players.filter(_.payoff > 10)

# Multiple conditions (all must match)
eligible = session.players.filter(_.present == True, _.age >= 18)

# Chained attribute access
same_round = session.players.filter(_.group.round == 3)

Supported operators: ==, !=, >, >=, <, <=. Bare _.field (without an operator) tests for truthiness.

See Filtering with _ for more examples.