pywebio.pin — Persistent input

pin == Persistent input == Pinning input widget to the page

Overview

As you already know, the input function of PyWebIO is blocking and the input form will be destroyed after successful submission. In most cases, it enough to use this way to get input. However in some cases, you may want to make the input form not disappear after submission, and can continue to receive input.

So PyWebIO provides the pin module to achieve persistent input by pinning input widgets to the page.

The pin module achieves persistent input in 3 parts:

First, this module provides some pin widgets. Pin widgets are not different from output widgets in pywebio.output module, besides that they can also receive input.

This code outputs an text input pin widget:

put_input('input', label='This is a input widget')

In fact, the usage of pin widget function is same as the output function. You can use it as part of the combined output, or you can output pin widget to a scope:

put_row([
    put_input('input'),
    put_select('select', options=['A', 'B', 'C'])
])

with use_scope('search-area'):
    put_input('search', placeholder='Search')

Then, you can use the pin object to get the value of pin widget:

put_input('pin_name')
put_buttons(['Get Pin Value'], lambda _: put_text(pin.pin_name))

The first parameter that the pin widget function receives is the name of the pin widget. You can get the current value of the pin widget via the attribute of the same name of the pin object.

In addition, the pin object also supports getting the value of the pin widget by index, that is to say:

pin['pin_name'] == pin.pin_name

There are also two useful functions when you use the pin module: pin_wait_change() and pin_update().

Since the pin widget functions is not blocking, pin_wait_change() is used to wait for the value of one of a list of pin widget to change, it ‘s a blocking function.

pin_update() can be used to update attributes of pin widgets.

Pin widgets

Each pin widget function corresponds to an input function of input module.

The function of pin widget supports most of the parameters of the corresponding input function. Here lists the difference between the two in parameters:

  • The first parameter of pin widget function is always the name of the widget, and if you output two pin widgets with the same name, the previous one will expire.

  • Pin functions don’t support the on_change and validate callbacks, and the required parameter. (There is a pin_on_change() function as an alternative to on_change)

  • Pin functions have additional scope and position parameters for output control.

pywebio.pin.put_input(name: str, type: str = 'text', *, label: str = '', value: Optional[str] = None, placeholder: Optional[str] = None, readonly: Optional[bool] = None, datalist: Optional[List[str]] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1)pywebio.io_ctrl.Output[source]

Output an input widget. Refer to: pywebio.input.input()

pywebio.pin.put_textarea(name: str, *, label: str = '', rows: int = 6, code: Optional[Union[bool, Dict]] = None, maxlength: Optional[int] = None, minlength: Optional[int] = None, value: Optional[str] = None, placeholder: Optional[str] = None, readonly: Optional[bool] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1)pywebio.io_ctrl.Output[source]

Output a textarea widget. Refer to: pywebio.input.textarea()

pywebio.pin.put_select(name: str, options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, label: str = '', multiple: Optional[bool] = None, value: Optional[Union[List, str]] = None, native: Optional[bool] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1)pywebio.io_ctrl.Output[source]

Output a select widget. Refer to: pywebio.input.select()

Note

Unlike pywebio.input.select(), when multiple=True and the user is using PC/macOS, put_select() will use bootstrap-select by default. Setting native=True will force PyWebIO to use native select component on all platforms and vice versa.

pywebio.pin.put_checkbox(name: str, options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, label: str = '', inline: Optional[bool] = None, value: Optional[List] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1)pywebio.io_ctrl.Output[source]

Output a checkbox widget. Refer to: pywebio.input.checkbox()

pywebio.pin.put_radio(name: str, options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, label: str = '', inline: Optional[bool] = None, value: Optional[str] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1)pywebio.io_ctrl.Output[source]

Output a radio widget. Refer to: pywebio.input.radio()

pywebio.pin.put_slider(name: str, *, label: str = '', value: Union[int, float] = 0, min_value: Union[int, float] = 0, max_value: Union[int, float] = 100, step: int = 1, required: Optional[bool] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1)pywebio.io_ctrl.Output[source]

Output a slide widget. Refer to: pywebio.input.slider()

pywebio.pin.put_actions(name: str, *, label: str = '', buttons: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1)pywebio.io_ctrl.Output[source]

Output a group of action button. Refer to: pywebio.input.actions()

Unlike the actions(), put_actions() won’t submit any form, it will only set the value of the pin widget. Only ‘submit’ type button is available in pin widget version.

New in version 1.4.

pywebio.pin.put_file_upload(name: str, *, label: str = '', accept: Optional[Union[List, str]] = None, placeholder: str = 'Choose file', multiple: bool = False, max_size: Union[int, str] = 0, max_total_size: Union[int, str] = 0, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1)pywebio.io_ctrl.Output[source]

Output a file uploading widget. Refer to: pywebio.input.file_upload()

Pin utils

pywebio.pin.pin

Pin widgets value getter and setter.

You can use attribute or key index of pin object to get the current value of a pin widget. By default, when accessing the value of a widget that does not exist, it returns None instead of throwing an exception. You can enable the error raising by pin.use_strict() method.

You can also use the pin object to set the value of pin widget:

put_input('counter', type='number', value=0)

while True:
    pin.counter = pin.counter + 1  # Equivalent to: pin['counter'] = pin['counter'] + 1
    time.sleep(1)

Note: When using coroutine-based session, you need to use the await pin.name (or await pin['name']) syntax to get pin widget value.

Use pin.pin.use_strict() to enable strict mode for getting pin widget value. An AssertionError will be raised when try to get value of pin widgets that are currently not in the page.

pywebio.pin.pin_wait_change(*names, timeout: Optional[int] = None)[source]

pin_wait_change() listens to a list of pin widgets, when the value of any widgets changes, the function returns with the name and value of the changed widget.

Parameters
  • names (str) – List of names of pin widget

  • timeout (int/None) – If timeout is a positive number, pin_wait_change() blocks at most timeout seconds and returns None if no changes to the widgets within that time. Set to None (the default) to disable timeout.

Return dict/None

{"name": name of the changed widget, "value": current value of the changed widget } , when a timeout occurs, return None.

Example:

put_input('a', type='number', value=0)
put_input('b', type='number', value=0)

while True:
    changed = pin_wait_change('a', 'b')
    with use_scope('res', clear=True):
        put_code(changed)
        put_text("a + b = %s" % (pin.a + pin.b))

Here is an demo of using pin_wait_change() to make a markdown previewer.

Note that: updating value with the pin object or pin_update() does not trigger pin_wait_change() to return.

When using coroutine-based session, you need to use the await pin_wait_change() syntax to invoke this function.

pywebio.pin.pin_update(name: str, **spec)[source]

Update attributes of pin widgets.

Parameters
  • name (str) – The name of the target input widget.

  • spec – The pin widget parameters need to be updated. Note that those parameters can not be updated: type, name, code, multiple

pywebio.pin.pin_on_change(name: str, onchange: Optional[Callable[[Any], None]] = None, clear: bool = False, init_run: bool = False, **callback_options)[source]

Bind a callback function to pin widget, the function will be called when user change the value of the pin widget.

The onchange callback is invoked with one argument, the changed value of the pin widget. You can bind multiple functions to one pin widget, those functions will be invoked sequentially (default behavior, can be changed by clear parameter).

Parameters
  • name (str) – pin widget name

  • onchange (callable) – callback function

  • clear (bool) – whether to clear the previous callbacks bound to this pin widget. If you just want to clear callbacks and not set new callback, use pin_on_change(name, clear=True).

  • init_run (bool) – whether to run the onchange callback once immediately before the pin widget changed. This parameter can be used to initialize the output.

  • callback_options – Other options of the onclick callback. Refer to the callback_options parameter of put_buttons()

New in version 1.6.