Input Elements API¶

Available input elements for OneCode projects:

checkbox
csv_reader
dropdown
file_input
number_input
radio_button
slider
text_input

checkbox¶

def checkbox(
    key: str,
    value: Optional[Union[bool, List[bool]]],
    label: Optional[str] = None,
    count: Optional[Union[int, str]] = None,
    optional: Union[bool, str] = False,
    hide_when_disabled: bool = False
)

A simple checkbox with a label. Value is either True, False or None.

Parameters:

Name	Type	Description	Default
`key`	`str`	ID of the element. It must be unique as it is the key used to story data in Project(), otherwise it will lead to conflicts at runtime in execution mode. The key will be transformed into snake case and slugified to avoid any special character or whitespace. Note that an ID cannot start with `_`. Try to choose a key that is meaningful for your context (see examples projects).	required
`value`	`Optional[Union[bool, List[bool]]]`	Initial check status: True, False or None.	required
`label`	`Optional[str]`	Label to display next to the checkbox.	`None`
`count`	`Optional[Union[int, str]]`	Placeholder, ignore until we activate this feature.	`None`
`optional`	`Union[bool, str]`	Specify whether the `value` may be None.	`False`
`hide_when_disabled`	`bool`	Placeholder, ignore until we activate this feature.	`False`
`**kwargs`	`Any`	Extra user meta-data to attach to the element. Argument names cannot overwrite existing attributes or methods name such as `_validate`, `_value`, etc.	`{}`

Raises:

Type	Description
`ValueError`	if the `key` is empty or starts with `_`.
`AttributeError`	if one the `kwargs` conflicts with an existing attribute or method.

Example

from onecode import checkbox, Mode, Project

Project().mode = Mode.EXECUTE
widget = checkbox(
    key="Checkbox",
    value=True,
    label="My Checkbox"
)
print(widget)

Output

True

csv_reader¶

def csv_reader(
    key: str,
    value: Optional[Union[str, List[str]]],
    label: Optional[str] = None,
    count: Optional[Union[int, str]] = None,
    optional: Union[bool, str] = False,
    hide_when_disabled: bool = False,
    tags: Optional[List[str]] = None
)

A CSV-file reader returning a Pandas DataFrame.

Parameters:

Name	Type	Description	Default
`key`	`str`	ID of the element. It must be unique as it is the key used to story data in Project(), otherwise it will lead to conflicts at runtime in execution mode. The key will be transformed into snake case and slugified to avoid any special character or whitespace. Note that an ID cannot start with `_`. Try to choose a key that is meaningful for your context (see examples projects).	required
`value`	`Optional[Union[str, List[str]]]`	Path to the CSV file. CSV file must exists.	required
`label`	`Optional[str]`	Label to display on top of the table.	`None`
`count`	`Optional[Union[int, str]]`	Placeholder, ignore until we activate this feature.	`None`
`optional`	`Union[bool, str]`	Specify whether the `value` may be None.	`False`
`hide_when_disabled`	`bool`	Placeholder, ignore until we activate this feature.	`False`
`tags`	`Optional[List[str]]`	Optional meta-data information about the expected file. This information is only used by the `Mode.EXTRACT_ALL` when dumping attributes to JSON.	`None`
`**kwargs`	`Any`	Extra user meta-data to attach to the element. Argument names cannot overwrite existing attributes or methods name such as `_validate`, `_value`, etc.	`{}`

Raises:

Type	Description
`ValueError`	if the `key` is empty or starts with `_`.
`AttributeError`	if one the `kwargs` conflicts with an existing attribute or method.

Example

import pandas as pd
from onecode import csv_reader, Mode, Project

Project().mode = Mode.EXECUTE
widget = csv_reader(
    key="CsvReader",
    value="/path/to/file.csv",
    label="My CSV Reader",
    tags=['CSV']
)

pd.testing.assert_frame_equal(widget, pd.read_csv("/path/to/file.csv"))

def dropdown(
    key: str,
    value: Optional[Union[str, List[str], List[List[str]]]],
    label: Optional[str] = None,
    count: Optional[Union[int, str]] = None,
    optional: Union[bool, str] = False,
    hide_when_disabled: bool = False,
    options: Union[List, str] = [],
    multiple: bool = False
)

A single or multipe choice dropdown menu.

Parameters:

Name	Type	Description	Default
`key`	`str`	ID of the element. It must be unique as it is the key used to story data in Project(), otherwise it will lead to conflicts at runtime in execution mode. The key will be transformed into snake case and slugified to avoid any special character or whitespace. Note that an ID cannot start with `_`. Try to choose a key that is meaningful for your context (see examples projects).	required
`value`	`Optional[Union[Union[str, int, float], List[Union[str, int, float]], List[List[Union[str, int, float]]]]]`	Pre-selected value(s) among the options.	required
`label`	`Optional[str]`	Label to display left of the dropdown menu.	`None`
`count`	`Optional[Union[int, str]]`	Placeholder, ignore until we activate this feature.	`None`
`optional`	`Union[bool, str]`	Specify whether the `value` may be None.	`False`
`hide_when_disabled`	`bool`	Placeholder, ignore until we activate this feature.	`False`
`options`	`Union[List, str]`	List all possible options available in the dropdown menu.	`[]`
`multiple`	`bool`	Set to True if multiple choice is allowed, otherwise only a single element can be selected.	`False`
`**kwargs`	`Any`	Extra user meta-data to attach to the element. Argument names cannot overwrite existing attributes or methods name such as `_validate`, `_value`, etc.	`{}`

Raises:

Type	Description
`ValueError`	if the `key` is empty or starts with `_`.
`AttributeError`	if one the `kwargs` conflicts with an existing attribute or method.

Example

Fixed options:

from onecode import dropdown, Mode, Project

Project().mode = Mode.EXECUTE
widget = dropdown(
    key="Dropdown",
    value=["A", "C"],
    options=["A", "B", "C"],
    multiple=True
)
print(widget)

Output

["A", "C"]

Dynamic options:

from onecode import csv_reader, dropdown, Mode, Project

Project().mode = Mode.EXECUTE

df = csv_reader("csv", "/path/to/file.csv")

widget = dropdown(
    key="Dynamic Dropdown",
    value=None,
    options='$csv$.columns',
    optional=True
)
print(widget)

Output

None

file_input¶

def file_input(
    key: str,
    value: Optional[Union[str, List[str], List[List[str]]]],
    label: Optional[str] = None,
    count: Optional[Union[int, str]] = None,
    optional: Union[bool, str] = False,
    hide_when_disabled: bool = False,
    types: List[Tuple[str, str]] = None,
    multiple: bool = False,
    tags: Optional[List[str]] = None
)

A single or multiple file selector.

Parameters:

Name	Type	Description	Default
`key`	`str`	ID of the element. It must be unique as it is the key used to story data in Project(), otherwise it will lead to conflicts at runtime in execution mode. The key will be transformed into snake case and slugified to avoid any special character or whitespace. Note that an ID cannot start with `_`. Try to choose a key that is meaningful for your context (see examples projects).	required
`value`	`Optional[Union[str, List[str], List[List[str]]]]`	Path to file(s). Files' existence will be checked at execution time. If paths are not absolute, then they are considered relative to the data root folder. See Organizing Data for more information.	required
`label`	`Optional[str]`	Label to display left of the file selector.	`None`
`count`	`Optional[Union[int, str]]`	Placeholder, ignore until we activate this feature.	`None`
`optional`	`Union[bool, str]`	Specify whether the `value` may be None.	`False`
`hide_when_disabled`	`bool`	Placeholder, ignore until we activate this feature.	`False`
`types`	`List[Tuple[str, str]]`	List of filters allowing to narrow file selection in the UI mode. Each filter must be a pair of (name, list of allowed extensions), e.g. `("Image", ".jpg .png .jpeg")`. You may use the FileFilter enums for convenience.	`None`
`multiple`	`bool`	Set to True if multiple choice is allowed, otherwise only a single element can be selected.	`False`
`tags`	`Optional[List[str]]`	Optional meta-data information about the expected file. This information is only used by the `Mode.EXTRACT_ALL` when dumping attributes to JSON.	`None`
`**kwargs`	`Any`	Extra user meta-data to attach to the element. Argument names cannot overwrite existing attributes or methods name such as `_validate`, `_value`, etc.	`{}`

Raises:

Type	Description
`ValueError`	if the `key` is empty or starts with `_`.
`AttributeError`	if one the `kwargs` conflicts with an existing attribute or method.

Example

from onecode import file_input, Mode, Project

Project().mode = Mode.EXECUTE
widget = file_input(
    key="FileInput",
    value=["/path/to/file1.txt", "/path/to/file2.csv"],
    multiple=True,
    tags=['MyTags']
)
print(widget)

Output

["/path/to/file1.txt", "/path/to/file2.csv"]

number_input¶

def number_input(
    key: str,
    value: Optional[Union[float, List[float]]],
    label: Optional[str] = None,
    count: Optional[Union[int, str]] = None,
    optional: Union[bool, str] = False,
    hide_when_disabled: bool = False,
    min: float = None,
    max: float = None,
    step: float = None
)

A field for numerical values.

Parameters:

Name	Type	Description	Default
`key`	`str`	ID of the element. It must be unique as it is the key used to story data in Project(), otherwise it will lead to conflicts at runtime in execution mode. The key will be transformed into snake case and slugified to avoid any special character or whitespace. Note that an ID cannot start with `_`. Try to choose a key that is meaningful for your context (see examples projects).	required
`value`	`Optional[Union[float, List[float]]]`	Initial numerical value.	required
`label`	`Optional[str]`	Label to display on top of the field.	`None`
`count`	`Optional[Union[int, str]]`	Placeholder, ignore until we activate this feature.	`None`
`optional`	`Union[bool, str]`	Specify whether the `value` may be None.	`False`
`hide_when_disabled`	`bool`	Placeholder, ignore until we activate this feature.	`False`
`min`	`float`	Optionally limit the possible values with a lower bound.	`None`
`max`	`float`	Optionally limit the possible values with an upper bound.	`None`
`step`	`float`	Optionally set a step used when increment/decrement button are used.	`None`
`**kwargs`	`Any`	Extra user meta-data to attach to the element. Argument names cannot overwrite existing attributes or methods name such as `_validate`, `_value`, etc.	`{}`

Raises:

Type	Description
`ValueError`	if the `key` is empty or starts with `_`.
`AttributeError`	if one the `kwargs` conflicts with an existing attribute or method.

Example

from onecode import number_input, Mode, Project

Project().mode = Mode.EXECUTE
widget = number_input(
    key="Number Input",
    value=5.1,
    min=5,
    max=6
)
print(widget)

Output

5.1

radio_button¶

def radio_button(
    key: str,
    value: Optional[Union[str, List[str]]],
    label: Optional[str] = None,
    count: Optional[Union[int, str]] = None,
    optional: Union[bool, str] = False,
    hide_when_disabled: bool = False,
    options: List[str] = [],
    horizontal: bool = False
)

A single choice represented as a group of exclusive radio buttons.

Parameters:

Name	Type	Description	Default
`key`	`str`	ID of the element. It must be unique as it is the key used to story data in Project(), otherwise it will lead to conflicts at runtime in execution mode. The key will be transformed into snake case and slugified to avoid any special character or whitespace. Note that an ID cannot start with `_`. Try to choose a key that is meaningful for your context (see examples projects).	required
`value`	`Optional[Union[str, List[str]]]`	Radio button initially selected.	required
`label`	`Optional[str]`	Label to display on top of the field.	`None`
`count`	`Optional[Union[int, str]]`	Placeholder, ignore until we activate this feature.	`None`
`optional`	`Union[bool, str]`	Specify whether the `value` may be None.	`False`
`hide_when_disabled`	`bool`	Placeholder, ignore until we activate this feature.	`False`
`options`	`List[str]`	List all possible options available.	`[]`
`horizontal`	`bool`	Set to True to have radio buttons displayed horizontally, otherwise radio buttons will be displayed vertically.	`False`
`**kwargs`	`Any`	Extra user meta-data to attach to the element. Argument names cannot overwrite existing attributes or methods name such as `_validate`, `_value`, etc.	`{}`

Raises:

Type	Description
`ValueError`	if the `key` is empty or starts with `_`.
`AttributeError`	if one the `kwargs` conflicts with an existing attribute or method.

Example

Fixed options:

from onecode import radio_button, Mode, Project

Project().mode = Mode.EXECUTE
widget = radio_button(
    key="RadioButton",
    value="A",
    options=["A", "B", "C"]
)
print(widget)

Output

"A"

Dynamic options:

from onecode import csv_reader, radio_button, Mode, Project

Project().mode = Mode.EXECUTE

df = csv_reader("csv", "/path/to/file.csv")

widget = radio_button(
    key="Dynamic RadioButton",
    value=None,
    options='$csv$.columns',
    optional=True
)

assert widget is None

slider¶

def slider(
    key: str,
    value: Optional[Union[float, List[float]]],
    label: Optional[str] = None,
    count: Optional[Union[int, str]] = None,
    optional: Union[bool, str] = False,
    hide_when_disabled: bool = False,
    min: float = 0.,
    max: float = 1.,
    step: float = 0.1
)

A slider for numerical values.

Parameters:

Name	Type	Description	Default
`key`	`str`	ID of the element. It must be unique as it is the key used to story data in Project(), otherwise it will lead to conflicts at runtime in execution mode. The key will be transformed into snake case and slugified to avoid any special character or whitespace. Note that an ID cannot start with `_`. Try to choose a key that is meaningful for your context (see examples projects).	required
`value`	`Optional[Union[float, List[float]]]`	Initial numerical value.	required
`label`	`Optional[str]`	Label to display on top of the field.	`None`
`count`	`Optional[Union[int, str]]`	Placeholder, ignore until we activate this feature.	`None`
`optional`	`Union[bool, str]`	Specify whether the `value` may be None.	`False`
`hide_when_disabled`	`bool`	Placeholder, ignore until we activate this feature.	`False`
`min`	`float`	Mandatory lower bound, defaults to 0.	`0.0`
`max`	`float`	Mandatory upper bound, defaults to 1.	`1.0`
`step`	`float`	Mandatory step used when incrementing/decrementing the slider, defaults to 0.1.	`0.1`
`**kwargs`	`Any`	Extra user meta-data to attach to the element. Argument names cannot overwrite existing attributes or methods name such as `_validate`, `_value`, etc.	`{}`

Raises:

Type	Description
`ValueError`	if the `key` is empty or starts with `_`.
`AttributeError`	if one the `kwargs` conflicts with an existing attribute or method.

Example

from onecode import slider, Mode, Project

Project().mode = Mode.EXECUTE
widget = slider(
    key="Slider",
    value=5.1,
    min=5,
    max=6
)
print(widget)

Output

5.1

text_input¶

def text_input(
    key: str,
    value: Optional[Union[str, List[str]]],
    label: Optional[str] = None,
    count: Optional[Union[int, str]] = None,
    optional: Union[bool, str] = False,
    hide_when_disabled: bool = False,
    max_chars: int = None,
    placeholder: str = None
)

A simple text field.

Parameters:

Name	Type	Description	Default
`key`	`str`	ID of the element. It must be unique as it is the key used to story data in Project(), otherwise it will lead to conflicts at runtime in execution mode. The key will be transformed into snake case and slugified to avoid any special character or whitespace. Note that an ID cannot start with `_`. Try to choose a key that is meaningful for your context (see examples projects).	required
`value`	`Optional[Union[str, List[str]]]`	Initial text value.	required
`label`	`Optional[str]`	Label to display on top of the text area.	`None`
`count`	`Optional[Union[int, str]]`	Placeholder, ignore until we activate this feature.	`None`
`optional`	`Union[bool, str]`	Specify whether the `value` may be None.	`False`
`hide_when_disabled`	`bool`	Placeholder, ignore until we activate this feature.	`False`
`max_chars`	`int`	Maximum number of characters allowed for this text field.	`None`
`placeholder`	`str`	Placeholder text shown whenever there is no value.	`None`
`multiline`	`Union[bool, int]`	Set to True or a height in pixels to make it multiline text area.	`False`
`**kwargs`	`Any`	Extra user meta-data to attach to the element. Argument names cannot overwrite existing attributes or methods name such as `_validate`, `_value`, etc.	`{}`

Raises:

Type	Description
`ValueError`	if the `key` is empty or starts with `_`.
`AttributeError`	if one the `kwargs` conflicts with an existing attribute or method.

Example

from onecode import text_input, Mode, Project

Project().mode = Mode.EXECUTE
widget = text_input(
    key="TextInput",
    value="OneCode rocks!",
    label="My TextInput"
)
print(widget)

Output

"OneCode rocks!"

Input Elements API¶

checkbox¶

csv_reader¶

dropdown¶

file_input¶

number_input¶

radio_button¶

slider¶

text_input¶