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
andvalidate
callbacks, and therequired
parameter. (There is apin_on_change()
function as an alternative toon_change
)Pin functions have additional
scope
andposition
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()
, whenmultiple=True
and the user is using PC/macOS,put_select()
will use bootstrap-select by default. Settingnative=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 returnsNone
instead of throwing an exception. You can enable the error raising bypin.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
(orawait pin['name']
) syntax to get pin widget value.Use
pin.pin.use_strict()
to enable strict mode for getting pin widget value. AnAssertionError
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 mosttimeout
seconds and returnsNone
if no changes to the widgets within that time. Set toNone
(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, returnNone
.
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 orpin_update()
does not triggerpin_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 byclear
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 thecallback_options
parameter ofput_buttons()
New in version 1.6.