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

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

send_to¶

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

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

send_to_one¶

Send data to a single player.

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

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)

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¶

Manually mark a player as a dropout.

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

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.