ipywidgets

Traits

Extra traitlets for custom effects

Trait types for html widgets.

class ipywidgets.widgets.trait_types.ByteMemoryView(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, config=None, **kwargs)

Bases: TraitType

A trait for memory views of bytes.

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

class ipywidgets.widgets.trait_types.CByteMemoryView(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, config=None, **kwargs)

Bases: ByteMemoryView

A casting version of the byte memory view trait.

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

class ipywidgets.widgets.trait_types.Color(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, config=None, **kwargs)

Bases: Unicode

A string holding a valid HTML color such as ‘blue’, ‘#060482’, ‘#A80’

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

default_value = traitlets.Undefined

class ipywidgets.widgets.trait_types.Date(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, config=None, **kwargs)

Bases: TraitType

A trait type holding a Python date object

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

klass

alias of date

class ipywidgets.widgets.trait_types.Datetime(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, config=None, **kwargs)

Bases: TraitType

A trait type holding a Python datetime object

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

klass

alias of datetime

class ipywidgets.widgets.trait_types.InstanceDict(klass=None, args=None, kw=None, allow_none=False, read_only=None, help=None, **kwargs)

Bases: Instance

An instance trait which coerces a dict to an instance.

This lets the instance be specified as a dict, which is used to initialize the instance.

Also, we default to a trivial instance, even if args and kwargs is not specified.

Construct an Instance trait.

This trait allows values that are instances of a particular class or its subclasses. Our implementation is quite different from that of enthough.traits as we don’t allow instances to be used for klass and we handle the args and kw arguments differently.

Parameters

klassclass, str

The class that forms the basis for the trait. Class names can also be specified as strings, like ‘foo.bar.Bar’.

argstuple

Positional arguments for generating the default value.

kwdict

Keyword arguments for generating the default value.

allow_nonebool [ default False ]

Indicates whether None is allowed as a value.

**kwargs

Extra kwargs passed to ClassBasedTraitType

Notes

If both args and kw are None, then the default value is None. If args is a tuple and kw is a dict, then the default is created as klass(*args, **kw). If exactly one of args or kw is None, the None is replaced by () or {}, respectively.

class ipywidgets.widgets.trait_types.NumberFormat(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, config=None, **kwargs)

Bases: Unicode

A string holding a number format specifier, e.g. ‘.3f’

This traitlet holds a string that can be passed to the d3-format JavaScript library. The format allowed is similar to the Python format specifier (PEP 3101).

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

default_value = traitlets.Undefined

class ipywidgets.widgets.trait_types.Time(default_value=traitlets.Undefined, allow_none=False, read_only=None, help=None, config=None, **kwargs)

Bases: TraitType

A trait type holding a Python time object

Declare a traitlet.

If allow_none is True, None is a valid value in addition to any values that are normally valid. The default is up to the subclass. For most trait types, the default value for allow_none is False.

If read_only is True, attempts to directly modify a trait attribute raises a TraitError.

If help is a string, it documents the attribute’s purpose.

Extra metadata can be associated with the traitlet using the .tag() convenience method or by using the traitlet instance’s .metadata dictionary.

klass

alias of date

class ipywidgets.widgets.trait_types.TypedTuple(trait=None, default_value=traitlets.Undefined, **kwargs)

Bases: Container

A trait for a tuple of any length with type-checked elements.

Create a container trait type from a list, set, or tuple.

The default value is created by doing List(default_value), which creates a copy of the default_value.

trait can be specified, which restricts the type of elements in the container to that TraitType.

If only one arg is given and it is not a Trait, it is taken as default_value:

c = List([1, 2, 3])

Parameters

traitTraitType [ optional ]

the type for restricting the contents of the Container. If unspecified, types are not checked.

default_valueSequenceType [ optional ]

The default value for the Trait. Must be list/tuple/set, and will be cast to the container type.

allow_nonebool [ default False ]

Whether to allow the value to be None

**kwargsany

further keys for extensions to the Trait (e.g. config)

klass

alias of tuple

ipywidgets.widgets.trait_types.date_from_json(js, manager)

Deserialize a Javascript date.

ipywidgets.widgets.trait_types.date_to_json(pydate, manager)

Serialize a Python date object.

Attributes of this dictionary are to be passed to the JavaScript Date constructor.

ipywidgets.widgets.trait_types.datetime_from_json(js, manager)

Deserialize a Python datetime object from json.

ipywidgets.widgets.trait_types.datetime_to_json(pydt, manager)

Serialize a Python datetime object to json.

Instantiating a JavaScript Date object with a string assumes that the string is a UTC string, while instantiating it with constructor arguments assumes that it’s in local time:

>>> cdate = new Date('2015-05-12')
Mon May 11 2015 20:00:00 GMT-0400 (Eastern Daylight Time)
>>> cdate = new Date(2015, 4, 12) // Months are 0-based indices in JS
Tue May 12 2015 00:00:00 GMT-0400 (Eastern Daylight Time)

Attributes of this dictionary are to be passed to the JavaScript Date constructor.

ipywidgets.widgets.trait_types.naive_from_json(js, manager)

Deserialize a naive Python datetime object from json.

ipywidgets.widgets.trait_types.naive_to_json(pydt, manager)

Serialize a naive Python datetime object to json.

Instantiating a JavaScript Date object with a string assumes that the string is a UTC string, while instantiating it with constructor arguments assumes that it’s in local time:

>>> cdate = new Date('2015-05-12')
Mon May 11 2015 20:00:00 GMT-0400 (Eastern Daylight Time)
>>> cdate = new Date(2015, 4, 12) // Months are 0-based indices in JS
Tue May 12 2015 00:00:00 GMT-0400 (Eastern Daylight Time)

Attributes of this dictionary are to be passed to the JavaScript Date constructor.

ipywidgets.widgets.trait_types.time_from_json(js, manager)

Deserialize a Python time object from json.

ipywidgets.widgets.trait_types.time_to_json(pyt, manager)

Serialize a Python time object to json.

Widget Base Classes

Key base classes for Widgets

Base Widget class. Allows user to create widgets in the back-end that render in the Jupyter notebook front-end.

class ipywidgets.widgets.widget.CallbackDispatcher(**kwargs)

Bases: LoggingHasTraits

A structure for registering and running callbacks

__call__(*args, **kwargs)

Call all of the registered callbacks.

register_callback(callback, remove=False)

(Un)Register a callback

Parameters

callback: method handle

Method to be registered or unregistered.

remove=False: bool

Whether to unregister the callback.

class ipywidgets.widgets.widget.LoggingHasTraits(**kwargs)

Bases: HasTraits

A parent class for HasTraits that log. Subclasses have a log trait, and the default behavior is to get the logger from the currently running Application.

class ipywidgets.widgets.widget.Widget(**kwargs)

Bases: LoggingHasTraits

Public constructor

__del__()

Object disposal

__init__(**kwargs)

Public constructor

__repr__()

Return repr(self).

add_traits(**traits)

Dynamically add trait attributes to the Widget.

close()

Close method.

Closes the underlying comm. When the comm is closed, all of the widget views are automatically removed from the front-end.

static get_manager_state(drop_defaults=False, widgets=None)

Returns the full state for a widget manager for embedding

Parameters:

• drop_defaults – when True, it will not include default value

• widgets – list with widgets to include in the state (or all widgets when None)

Returns:

get_state(key=None, drop_defaults=False)

Gets the widget state, or a piece of it.

Parameters

keyunicode or iterable (optional)

A single property’s name or iterable of property names to get.

Returns

state : dict of states metadata : dict

metadata for each field: {key: metadata}

static handle_comm_opened(comm, msg)

Static method, called when a widget is constructed.

classmethod handle_control_comm_opened(comm, msg)

Class method, called when the comm-open message on the “jupyter.widget.control” comm channel is received

hold_sync()

Hold syncing any state until the outermost context manager exits

property model_id

Gets the model id of this widget.

If a Comm doesn’t exist yet, a Comm will be created automagically.

notify_change(change)

Called when a property has changed.

on_msg(callback, remove=False)

(Un)Register a custom msg receive callback.

Parameters

callback: callable

callback will be passed three arguments when a message arrives:

callback(widget, content, buffers)

remove: bool

True if the callback should be unregistered.

static on_widget_constructed(callback)

Registers a callback to be called when a widget is constructed.

The callback must have the following signature: callback(widget)

open()

Open a comm to the frontend if one isn’t already open.

send(content, buffers=None)

Sends a custom msg to the widget model in the front-end.

Parameters

contentdict

Content of the message to send.

bufferslist of binary buffers

Binary buffers to send with message

send_state(key=None)

Sends the widget state, or a piece of it, to the front-end, if it exists.

Parameters

keyunicode, or iterable (optional)

A single property’s name or iterable of property names to sync with the front-end.

set_state(sync_data)

Called when a state is received from the front-end.

ipywidgets.widgets.widget.envset(name, default)

Return True if the given environment variable is turned on, otherwise False If the environment variable is set, True will be returned if it is assigned to a value other than ‘no’, ‘n’, ‘false’, ‘off’, ‘0’, or ‘0.0’ (case insensitive). If the environment variable is not set, the default value is returned.

ipywidgets.widgets.widget.register(widget)

A decorator registering a widget class in the widget registry.

Contains the ValueWidget class

class ipywidgets.widgets.valuewidget.ValueWidget(**kwargs)

Bases: Widget

Widget that can be used for the input of an interactive function

Public constructor

get_interact_value()

Return the value for this widget which should be passed to interactive functions. Custom widgets can change this method to process the raw value self.value.

value

The value of the widget.

Contains the DOMWidget class

class ipywidgets.widgets.domwidget.DOMWidget(**kwargs)

Bases: Widget

Widget that can be inserted into the DOM

Parameters

tooltip: str

tooltip caption

layout: InstanceDict(Layout)

widget layout

Public constructor

add_class(className)

Adds a class to the top level element of the widget.

Doesn’t add the class if it already exists.

blur()

Blur the widget.

focus()

Focus on the widget.

remove_class(className)

Removes a class from the top level element of the widget.

Doesn’t remove the class if it doesn’t exist.

tabbable

Is widget tabbable?

tooltip

A tooltip caption.

Interactive

Opinions for auto-generating Widget user experiences

Interact with functions using widgets.

class ipywidgets.widgets.interaction.fixed(**kwargs)

Bases: HasTraits

A pseudo-widget whose value is fixed and never synced to the client.

__init__(value, **kwargs)

description

Any Python object

get_interact_value()

Return the value for this widget which should be passed to interactive functions. Custom widgets can change this method to process the raw value self.value.

value

Any Python object

class ipywidgets.widgets.interaction.interactive(**kwargs)

Bases: VBox

A VBox container containing a group of interactive widgets tied to a function.

Parameters

__interact_ffunction

The function to which the interactive widgets are tied. The **kwargs should match the function signature.

__optionsdict

A dict of options. Currently, the only supported keys are "manual" (defaults to False), "manual_name" (defaults to "Run Interact") and "auto_display" (defaults to False).

**kwargsvarious, optional

An interactive widget is created for each keyword argument that is a valid widget abbreviation.

Note that the first two parameters intentionally start with a double underscore to avoid being mixed up with keyword arguments passed by **kwargs.

Public constructor

__init__(_interactive__interact_f, _interactive__options={}, **kwargs)

Public constructor

find_abbreviations(kwargs)

Find the abbreviations for the given function and kwargs. Return (name, abbrev, default) tuples.

update(*args)

Call the interact function and update the output widget with the result of the function call.

Parameters

*argsignored

Required for this method to be used as traitlets callback.

classmethod widget_from_abbrev(abbrev, default)

Build a ValueWidget instance given an abbreviation or Widget.

static widget_from_iterable(o)

Make widgets from an iterable. This should not be done for a string or tuple.

static widget_from_single_value(o)

Make widgets from single values, which can be used as parameter defaults.

static widget_from_tuple(o)

Make widgets from a tuple abbreviation.

widgets_from_abbreviations(seq)

Given a sequence of (name, abbrev, default) tuples, return a sequence of Widgets.

ipywidgets.widgets.interaction.interactive_output(f, controls)

Connect widget controls to a function.

This function does not generate a user interface for the widgets (unlike interact). This enables customisation of the widget user interface layout. The user interface layout must be defined and displayed manually.

ipywidgets.widgets.interaction.show_inline_matplotlib_plots()

Show matplotlib plots immediately if using the inline backend.

With ipywidgets 6.0, matplotlib plots don’t work well with interact when using the inline backend that comes with ipykernel. Basically, the inline backend only shows the plot after the entire cell executes, which does not play well with drawing plots inside of an interact function. See jupyter-widgets/ipywidgets# and ipython/ipython#10376 for more details. This function displays any matplotlib plots if the backend is the inline backend.

Core Widgets

The core Widgets

Bool class.

Represents a boolean using a widget.

class ipywidgets.widgets.widget_bool.Checkbox(**kwargs)

Bases: _Bool

Displays a boolean value in the form of a checkbox.

Parameters

value{True,False}

value of the checkbox: True-checked, False-unchecked

descriptionstr

description displayed next to the checkbox

indent{True,False}

indent the control to align with other controls with a description. The style.description_width attribute controls this width for consistence with other controls.

Public constructor

indent

Indent the control to align with other controls with a description.

class ipywidgets.widgets.widget_bool.CheckboxStyle(**kwargs)

Bases: DescriptionStyle, CoreWidget

Checkbox widget style.

Public constructor

background

Background specifications.

class ipywidgets.widgets.widget_bool.ToggleButton(**kwargs)

Bases: _Bool

Displays a boolean value in the form of a toggle button.

Parameters

value{True,False}

value of the toggle button: True-pressed, False-unpressed

descriptionstr

description displayed on the button

icon: str

font-awesome icon name

style: instance of DescriptionStyle

styling customizations

button_style: enum

button predefined styling

Public constructor

button_style

Use a predefined styling for the button.

icon

Font-awesome icon.

class ipywidgets.widgets.widget_bool.ToggleButtonStyle(**kwargs)

Bases: DescriptionStyle, CoreWidget

ToggleButton widget style.

Public constructor

font_family

Toggle button text font family.

font_size

Toggle button text font size.

font_style

Toggle button text font style.

font_variant

Toggle button text font variant.

font_weight

Toggle button text font weight.

text_color

Toggle button text color

text_decoration

Toggle button text decoration.

class ipywidgets.widgets.widget_bool.Valid(**kwargs)

Bases: _Bool

Displays a boolean value in the form of a green check (True / valid) or a red cross (False / invalid).

Parameters

value: {True,False}

value of the Valid widget

Public constructor

readout

Message displayed when the value is False

Box widgets.

These widgets are containers that can be used to group other widgets together and control their relative layouts.

class ipywidgets.widgets.widget_box.Box(**kwargs)

Bases: DOMWidget, CoreWidget

Displays multiple widgets in a group.

The widgets are laid out horizontally.

Parameters

children: iterable of Widget instances

list of widgets to display

box_style: str

one of ‘success’, ‘info’, ‘warning’ or ‘danger’, or ‘’. Applies a predefined style to the box. Defaults to ‘’, which applies no pre-defined style.

Examples

>>> import ipywidgets as widgets
>>> title_widget = widgets.HTML('<em>Box Example</em>')
>>> slider = widgets.IntSlider()
>>> widgets.Box([title_widget, slider])

Public constructor

__init__(children=(), **kwargs)

Public constructor

box_style

Use a predefined styling for the box.

class ipywidgets.widgets.widget_box.GridBox(**kwargs)

Bases: Box

Displays multiple widgets in rows and columns using the grid box model.

Parameters

{box_params}

Examples

>>> import ipywidgets as widgets
>>> title_widget = widgets.HTML('<em>Grid Box Example</em>')
>>> slider = widgets.IntSlider()
>>> button1 = widgets.Button(description='1')
>>> button2 = widgets.Button(description='2')
>>> # Create a grid with two columns, splitting space equally
>>> layout = widgets.Layout(grid_template_columns='1fr 1fr')
>>> widgets.GridBox([title_widget, slider, button1, button2], layout=layout)

Public constructor

class ipywidgets.widgets.widget_box.HBox(**kwargs)

Bases: Box

Displays multiple widgets horizontally using the flexible box model.

Parameters

children: iterable of Widget instances

list of widgets to display

box_style: str

one of ‘success’, ‘info’, ‘warning’ or ‘danger’, or ‘’. Applies a predefined style to the box. Defaults to ‘’, which applies no pre-defined style.

Examples

>>> import ipywidgets as widgets
>>> title_widget = widgets.HTML('<em>Horizontal Box Example</em>')
>>> slider = widgets.IntSlider()
>>> widgets.HBox([title_widget, slider])

Public constructor

class ipywidgets.widgets.widget_box.VBox(**kwargs)

Bases: Box

Displays multiple widgets vertically using the flexible box model.

Parameters

children: iterable of Widget instances

list of widgets to display

box_style: str

one of ‘success’, ‘info’, ‘warning’ or ‘danger’, or ‘’. Applies a predefined style to the box. Defaults to ‘’, which applies no pre-defined style.

Examples

>>> import ipywidgets as widgets
>>> title_widget = widgets.HTML('<em>Vertical Box Example</em>')
>>> slider = widgets.IntSlider()
>>> widgets.VBox([title_widget, slider])

Public constructor

Button class.

Represents a button in the frontend using a widget. Allows user to listen for click events on the button and trigger backend code when the clicks are fired.

class ipywidgets.widgets.widget_button.Button(**kwargs)

Bases: DOMWidget, CoreWidget

Button widget.

This widget has an on_click method that allows you to listen for the user clicking on the button. The click event itself is stateless.

Parameters

description: str

description displayed on the button

icon: str

font-awesome icon names, without the ‘fa-’ prefix

disabled: bool

whether user interaction is enabled

Public constructor

__init__(**kwargs)

Public constructor

button_style

Use a predefined styling for the button.

click()

Programmatically trigger a click event.

This will call the callbacks registered to the clicked button widget instance.

description

Button label.

disabled

Enable or disable user changes.

icon

Font-awesome icon names, without the ‘fa-’ prefix.

on_click(callback, remove=False)

Register a callback to execute when the button is clicked.

The callback will be called with one argument, the clicked button widget instance.

Parameters

remove: bool (optional)

Set to true to remove the callback from the list of callbacks.

class ipywidgets.widgets.widget_button.ButtonStyle(**kwargs)

Bases: Style, CoreWidget

Button style widget.

Public constructor

button_color

Color of the button

font_family

Button text font family.

font_size

Button text font size.

font_style

Button text font style.

font_variant

Button text font variant.

font_weight

Button text font weight.

text_color

Button text color.

text_decoration

Button text decoration.

Color class.

Represents an HTML Color .

class ipywidgets.widgets.widget_color.ColorPicker(**kwargs)

Bases: DescriptionWidget, ValueWidget, CoreWidget

Public constructor

concise

Display short version with just a color selector.

disabled

Enable or disable user changes.

value

The color value.

Controller class.

Represents a Gamepad or Joystick controller.

class ipywidgets.widgets.widget_controller.Axis(**kwargs)

Bases: DOMWidget, ValueWidget, CoreWidget

Represents a gamepad or joystick axis.

Public constructor

value

The value of the axis.

class ipywidgets.widgets.widget_controller.Button(**kwargs)

Bases: DOMWidget, ValueWidget, CoreWidget

Represents a gamepad or joystick button.

Public constructor

pressed

Whether the button is pressed.

value

The value of the button.

class ipywidgets.widgets.widget_controller.Controller(**kwargs)

Bases: DOMWidget, CoreWidget

Represents a game controller.

Public constructor

connected

Whether the gamepad is connected.

index

The id number of the controller.

mapping

The name of the control mapping.

name

The name of the controller.

timestamp

The last time the data from this gamepad was updated.

Base widget class for widgets provided in Core

class ipywidgets.widgets.widget_core.CoreWidget(**kwargs)

Bases: Widget

Public constructor

Color class.

Represents an HTML Color .

class ipywidgets.widgets.widget_date.DatePicker(**kwargs)

Bases: DescriptionWidget, ValueWidget, CoreWidget

Display a widget for picking dates.

Parameters

value: datetime.date

The current value of the widget.

disabled: bool

Whether to disable user changes.

Examples

>>> import datetime
>>> import ipywidgets as widgets
>>> date_pick = widgets.DatePicker()
>>> date_pick.value = datetime.date(2019, 7, 9)

Public constructor

disabled

Enable or disable user changes.

step

The date step to use for the picker, in days, or “any”.

Time and datetime picker widgets

class ipywidgets.widgets.widget_datetime.DatetimePicker(**kwargs)

Bases: DescriptionWidget, ValueWidget, CoreWidget

Display a widget for picking datetimes.

Parameters

value: datetime.datetime

The current value of the widget.

disabled: bool

Whether to disable user changes.

min: datetime.datetime

The lower allowed datetime bound

max: datetime.datetime

The upper allowed datetime bound

Examples

>>> import datetime
>>> import ipydatetime
>>> datetime_pick = ipydatetime.DatetimePicker()
>>> datetime_pick.value = datetime.datetime(2018, 09, 5, 12, 34, 3)

Public constructor

disabled

Enable or disable user changes.

class ipywidgets.widgets.widget_datetime.NaiveDatetimePicker(**kwargs)

Bases: DatetimePicker

Display a widget for picking naive datetimes (i.e. timezone unaware).

Parameters

value: datetime.datetime

The current value of the widget.

disabled: bool

Whether to disable user changes.

min: datetime.datetime

The lower allowed datetime bound

max: datetime.datetime

The upper allowed datetime bound

Examples

>>> import datetime
>>> import ipydatetime
>>> datetime_pick = ipydatetime.NaiveDatetimePicker()
>>> datetime_pick.value = datetime.datetime(2018, 09, 5, 12, 34, 3)

Public constructor

Contains the DOMWidget class

class ipywidgets.widgets.widget_description.DescriptionStyle(**kwargs)

Bases: Style, CoreWidget, Widget

Description style widget.

Public constructor

description_width

Width of the description to the side of the control.

class ipywidgets.widgets.widget_description.DescriptionWidget(**kwargs)

Bases: DOMWidget, CoreWidget

Widget that has a description label to the side.

Public constructor

__init__(*args, **kwargs)

Public constructor

description

Description of the control.

description_allow_html

Accept HTML in the description.

property description_tooltip

The tooltip information. .. deprecated :: 8.0.0

Use tooltip attribute instead.

Float class.

Represents an unbounded float using a widget.

class ipywidgets.widgets.widget_float.BoundedFloatText(**kwargs)

Bases: _BoundedFloat

Displays a float value within a textbox. Value must be within the range specified.

For a textbox in which the value doesn’t need to be within a specific range, use FloatText.

Parameters

valuefloat

value displayed

minfloat

minimal value of the range of possible values displayed

maxfloat

maximal value of the range of possible values displayed

stepfloat

step of the increment (if None, any step is allowed)

descriptionstr

description displayed next to the textbox

Public constructor

continuous_update

Update the value as the user types. If False, update on submission, e.g., pressing Enter or navigating away.

disabled

Enable or disable user changes

step

Minimum step to increment the value

class ipywidgets.widgets.widget_float.FloatLogSlider(**kwargs)

Bases: _BoundedLogFloat

Slider/trackbar of logarithmic floating values with the specified range.

Parameters

valuefloat

position of the slider

basefloat

base of the logarithmic scale. Default is 10

minfloat

minimal position of the slider in log scale, i.e., actual minimum is base ** min

maxfloat

maximal position of the slider in log scale, i.e., actual maximum is base ** max

stepfloat

step of the trackbar, denotes steps for the exponent, not the actual value

descriptionstr

name of the slider

orientation{‘horizontal’, ‘vertical’}

default is ‘horizontal’, orientation of the slider

readout{True, False}

default is True, display the current value of the slider next to it

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

readout_formatstr

default is ‘.3g’, specifier for the format function used to represent slider value for human consumption, modeled after Python 3’s format specification mini-language (PEP 3101).

Public constructor

base

Base for the logarithm

behavior

Slider dragging behavior.

continuous_update

Update the value of the widget as the user is holding the slider.

disabled

Enable or disable user changes

orientation

Vertical or horizontal.

readout

Display the current value of the slider next to it.

readout_format

Format for the readout

step

Minimum step in the exponent to increment the value

class ipywidgets.widgets.widget_float.FloatProgress(**kwargs)

Bases: _BoundedFloat

Displays a progress bar.

Parameters

valuefloat

position within the range of the progress bar

minfloat

minimal position of the slider

maxfloat

maximal position of the slider

descriptionstr

name of the progress bar

orientation{‘horizontal’, ‘vertical’}

default is ‘horizontal’, orientation of the progress bar

bar_style: {‘success’, ‘info’, ‘warning’, ‘danger’, ‘’}

color of the progress bar, default is ‘’ (blue) colors are: ‘success’-green, ‘info’-light blue, ‘warning’-orange, ‘danger’-red

Public constructor

bar_style

Use a predefined styling for the progress bar.

orientation

Vertical or horizontal.

class ipywidgets.widgets.widget_float.FloatRangeSlider(**kwargs)

Bases: _BoundedFloatRange

Slider/trackbar that represents a pair of floats bounded by minimum and maximum value.

Parameters

valuefloat tuple

range of the slider displayed

minfloat

minimal position of the slider

maxfloat

maximal position of the slider

stepfloat

step of the trackbar

descriptionstr

name of the slider

orientation{‘horizontal’, ‘vertical’}

default is ‘horizontal’

readout{True, False}

default is True, display the current value of the slider next to it

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

readout_formatstr

default is ‘.2f’, specifier for the format function used to represent slider value for human consumption, modeled after Python 3’s format specification mini-language (PEP 3101).

Public constructor

behavior

Slider dragging behavior.

continuous_update

Update the value of the widget as the user is sliding the slider.

disabled

Enable or disable user changes

orientation

Vertical or horizontal.

readout

Display the current value of the slider next to it.

readout_format

Format for the readout

step

Minimum step to increment the value

class ipywidgets.widgets.widget_float.FloatSlider(**kwargs)

Bases: _BoundedFloat

Slider/trackbar of floating values with the specified range.

Parameters

valuefloat

position of the slider

minfloat

minimal position of the slider

maxfloat

maximal position of the slider

stepfloat

step of the trackbar

descriptionstr

name of the slider

orientation{‘horizontal’, ‘vertical’}

default is ‘horizontal’, orientation of the slider

readout{True, False}

default is True, display the current value of the slider next to it

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

readout_formatstr

default is ‘.2f’, specifier for the format function used to represent slider value for human consumption, modeled after Python 3’s format specification mini-language (PEP 3101).

Public constructor

behavior

Slider dragging behavior.

continuous_update

Update the value of the widget as the user is holding the slider.

disabled

Enable or disable user changes

orientation

Vertical or horizontal.

readout

Display the current value of the slider next to it.

readout_format

Format for the readout

step

Minimum step to increment the value

class ipywidgets.widgets.widget_float.FloatText(**kwargs)

Bases: _Float

Displays a float value within a textbox. For a textbox in which the value must be within a specific range, use BoundedFloatText.

Parameters

valuefloat

value displayed

stepfloat

step of the increment (if None, any step is allowed)

descriptionstr

description displayed next to the text box

Public constructor

continuous_update

Update the value as the user types. If False, update on submission, e.g., pressing Enter or navigating away.

disabled

Enable or disable user changes

step

Minimum step to increment the value

Int class.

Represents an unbounded int using a widget.

class ipywidgets.widgets.widget_int.BoundedIntText(**kwargs)

Bases: _BoundedInt

Textbox widget that represents an integer bounded from above and below.

Parameters

value: integer

The initial value.

min: integer

The lower limit for the value.

max: integer

The upper limit for the value.

step: integer

The step between allowed values.

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

__init__(value=None, min=None, max=None, step=None, **kwargs)

Parameters

value: integer

The initial value.

min: integer

The lower limit for the value.

max: integer

The upper limit for the value.

step: integer

The step between allowed values.

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

continuous_update

Update the value as the user types. If False, update on submission, e.g., pressing Enter or navigating away.

disabled

Enable or disable user changes

step

Minimum step to increment the value

class ipywidgets.widgets.widget_int.IntProgress(**kwargs)

Bases: _BoundedInt

Progress bar that represents an integer bounded from above and below.

Parameters

value: integer

The initial value.

min: integer

The lower limit for the value.

max: integer

The upper limit for the value.

step: integer

The step between allowed values.

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

__init__(value=None, min=None, max=None, step=None, **kwargs)

Parameters

value: integer

The initial value.

min: integer

The lower limit for the value.

max: integer

The upper limit for the value.

step: integer

The step between allowed values.

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

bar_style

Use a predefined styling for the progress bar.

orientation

Vertical or horizontal.

class ipywidgets.widgets.widget_int.IntRangeSlider(**kwargs)

Bases: _BoundedIntRange

Slider/trackbar that represents a pair of ints bounded by minimum and maximum value.

Parameters

valueint tuple

The pair (lower, upper) of integers

minint

The lowest allowed value for lower

maxint

The highest allowed value for upper

stepint

step of the trackbar

descriptionstr

name of the slider

orientation{‘horizontal’, ‘vertical’}

default is ‘horizontal’

readout{True, False}

default is True, display the current value of the slider next to it

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

readout_formatstr

default is ‘.2f’, specifier for the format function used to represent slider value for human consumption, modeled after Python 3’s format specification mini-language (PEP 3101).

Public constructor

behavior

Slider dragging behavior.

continuous_update

Update the value of the widget as the user is sliding the slider.

disabled

Enable or disable user changes

orientation

Vertical or horizontal.

readout

Display the current value of the slider next to it.

readout_format

Format for the readout

step

Minimum step that the value can take

class ipywidgets.widgets.widget_int.IntSlider(**kwargs)

Bases: _BoundedInt

Slider widget that represents an integer bounded from above and below.

Parameters

value: integer

The initial value.

min: integer

The lower limit for the value.

max: integer

The upper limit for the value.

step: integer

The step between allowed values.

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

__init__(value=None, min=None, max=None, step=None, **kwargs)

Parameters

value: integer

The initial value.

min: integer

The lower limit for the value.

max: integer

The upper limit for the value.

step: integer

The step between allowed values.

behaviorstr

slider handle and connector dragging behavior. Default is ‘drag-tap’.

behavior

Slider dragging behavior.

continuous_update

Update the value of the widget as the user is holding the slider.

disabled

Enable or disable user changes

orientation

Vertical or horizontal.

readout

Display the current value of the slider next to it.

readout_format

Format for the readout

step

Minimum step to increment the value

class ipywidgets.widgets.widget_int.IntText(**kwargs)

Bases: _Int

Textbox widget that represents an integer.

Parameters

value: integer

The initial value.

__init__(value=None, **kwargs)

Parameters

value: integer

The initial value.

continuous_update

Update the value as the user types. If False, update on submission, e.g., pressing Enter or navigating away.

disabled

Enable or disable user changes

step

Minimum step to increment the value

class ipywidgets.widgets.widget_int.Play(**kwargs)

Bases: _BoundedInt

Play/repeat buttons to step through values automatically, and optionally loop.

Public constructor

disabled

Enable or disable user changes

interval

The time between two animation steps (ms).

playing

Whether the control is currently playing.

repeat

Whether the control will repeat in a continuous loop.

show_repeat

Show the repeat toggle button in the widget.

step

Increment step

class ipywidgets.widgets.widget_int.ProgressStyle(**kwargs)

Bases: DescriptionStyle, CoreWidget

Button style widget.

Public constructor

bar_color

Color of the progress bar.

class ipywidgets.widgets.widget_int.SliderStyle(**kwargs)

Bases: DescriptionStyle, CoreWidget

Button style widget.

Public constructor

handle_color

Color of the slider handle.

Contains the Layout class

class ipywidgets.widgets.widget_layout.Layout(**kwargs)

Bases: Widget

Layout specification

Defines a layout that can be expressed using CSS. Supports a subset of https://developer.mozilla.org/en-US/docs/Web/CSS/Reference

When a property is also accessible via a shorthand property, we only expose the shorthand.

For example: - flex-grow, flex-shrink and flex-basis are bound to flex. - flex-wrap and flex-direction are bound to flex-flow. - margin-[top/bottom/left/right] values are bound to margin, etc.

Public constructor

__init__(**kwargs)

Public constructor

align_content

The align-content CSS attribute.

align_items

The align-items CSS attribute.

align_self

The align-self CSS attribute.

property border

border property getter. Return the common value of all side borders if they are identical. Otherwise return None.

border_bottom

The border bottom CSS attribute.

border_left

The border left CSS attribute.

border_right

The border right CSS attribute.

border_top

The border top CSS attribute.

bottom

The bottom CSS attribute.

display

The display CSS attribute.

flex

The flex CSS attribute.

flex_flow

The flex-flow CSS attribute.

grid_area

The grid-area CSS attribute.

grid_auto_columns

The grid-auto-columns CSS attribute.

grid_auto_flow

The grid-auto-flow CSS attribute.

grid_auto_rows

The grid-auto-rows CSS attribute.

grid_column

The grid-column CSS attribute.

grid_gap

The grid-gap CSS attribute.

grid_row

The grid-row CSS attribute.

grid_template_areas

The grid-template-areas CSS attribute.

grid_template_columns

The grid-template-columns CSS attribute.

grid_template_rows

The grid-template-rows CSS attribute.

height

The height CSS attribute.

justify_content

The justify-content CSS attribute.

justify_items

The justify-items CSS attribute.

left

The left CSS attribute.

margin

The margin CSS attribute.

max_height

The max-height CSS attribute.

max_width

The max-width CSS attribute.

min_height

The min-height CSS attribute.

min_width

The min-width CSS attribute.

object_fit

The object-fit CSS attribute.

object_position

The object-position CSS attribute.

order

The order CSS attribute.

overflow

The overflow CSS attribute.

padding

The padding CSS attribute.

right

The right CSS attribute.

top

The top CSS attribute.

visibility

The visibility CSS attribute.

width

The width CSS attribute.

class ipywidgets.widgets.widget_layout.LayoutTraitType(klass=None, args=None, kw=None, allow_none=False, read_only=None, help=None, **kwargs)

Bases: Instance

Construct an Instance trait.

This trait allows values that are instances of a particular class or its subclasses. Our implementation is quite different from that of enthough.traits as we don’t allow instances to be used for klass and we handle the args and kw arguments differently.

Parameters

klassclass, str

The class that forms the basis for the trait. Class names can also be specified as strings, like ‘foo.bar.Bar’.

argstuple

Positional arguments for generating the default value.

kwdict

Keyword arguments for generating the default value.

allow_nonebool [ default False ]

Indicates whether None is allowed as a value.

**kwargs

Extra kwargs passed to ClassBasedTraitType

Notes

If both args and kw are None, then the default value is None. If args is a tuple and kw is a dict, then the default is created as klass(*args, **kw). If exactly one of args or kw is None, the None is replaced by () or {}, respectively.

klass

alias of Layout

Link and DirectionalLink classes.

Propagate changes between widgets on the javascript side.

class ipywidgets.widgets.widget_link.DirectionalLink(**kwargs)

Bases: Link

A directional link

source: a (Widget, ‘trait_name’) tuple for the source trait target: a (Widget, ‘trait_name’) tuple that should be updated when the source trait changes.

Public constructor

class ipywidgets.widgets.widget_link.Link(**kwargs)

Bases: CoreWidget

Link Widget

source: a (Widget, ‘trait_name’) tuple for the source trait target: a (Widget, ‘trait_name’) tuple that should be updated

Public constructor

__init__(source, target, **kwargs)

Public constructor

class ipywidgets.widgets.widget_link.WidgetTraitTuple(**kwargs)

Bases: Tuple

Traitlet for validating a single (Widget, ‘trait_name’) pair

Create a tuple from a list, set, or tuple.

Create a fixed-type tuple with Traits:

t = Tuple(Int(), Str(), CStr())

would be length 3, with Int,Str,CStr for each element.

If only one arg is given and it is not a Trait, it is taken as default_value:

t = Tuple((1, 2, 3))

Otherwise, default_value must be specified by keyword.

Parameters

*traitsTraitTypes [ optional ]

the types for restricting the contents of the Tuple. If unspecified, types are not checked. If specified, then each positional argument corresponds to an element of the tuple. Tuples defined with traits are of fixed length.

default_valueSequenceType [ optional ]

The default value for the Tuple. Must be list/tuple/set, and will be cast to a tuple. If traits are specified, default_value must conform to the shape and type they specify.

**kwargs

Other kwargs passed to Container

__init__(**kwargs)

Create a tuple from a list, set, or tuple.

Create a fixed-type tuple with Traits:

t = Tuple(Int(), Str(), CStr())

would be length 3, with Int,Str,CStr for each element.

If only one arg is given and it is not a Trait, it is taken as default_value:

t = Tuple((1, 2, 3))

Otherwise, default_value must be specified by keyword.

Parameters

*traitsTraitTypes [ optional ]

the types for restricting the contents of the Tuple. If unspecified, types are not checked. If specified, then each positional argument corresponds to an element of the tuple. Tuples defined with traits are of fixed length.

default_valueSequenceType [ optional ]

The default value for the Tuple. Must be list/tuple/set, and will be cast to a tuple. If traits are specified, default_value must conform to the shape and type they specify.

**kwargs

Other kwargs passed to Container

ipywidgets.widgets.widget_link.jsdlink(source, target)

Link a source widget attribute with a target widget attribute.

The link is created in the front-end and does not rely on a roundtrip to the backend.

Parameters

source : a (Widget, ‘trait_name’) tuple for the source trait target : a (Widget, ‘trait_name’) tuple for the target trait

Examples

>>> c = dlink((src_widget, 'value'), (tgt_widget, 'value'))

ipywidgets.widgets.widget_link.jslink(attr1, attr2)

Link two widget attributes on the frontend so they remain in sync.

The link is created in the front-end and does not rely on a roundtrip to the backend.

Parameters

source : a (Widget, ‘trait_name’) tuple for the first trait target : a (Widget, ‘trait_name’) tuple for the second trait

Examples

>>> c = link((widget1, 'value'), (widget2, 'value'))

class ipywidgets.widgets.widget_media.Audio(**kwargs)

Bases: _Media

Displays a audio as a widget.

The value of this widget accepts a byte string. The byte string is the raw audio data that you want the browser to display. You can explicitly define the format of the byte string using the format trait (which defaults to “mp3”).

If you pass “url” to the “format” trait, value will be interpreted as a URL as bytes encoded in UTF-8.

Public constructor

__repr__()

Return repr(self).

autoplay

When true, the audio starts when it’s displayed

controls

Specifies that audio controls should be displayed (such as a play/pause button etc)

format

The format of the audio.

loop

When true, the audio will start from the beginning after finishing

class ipywidgets.widgets.widget_media.Image(**kwargs)

Bases: _Media

Displays an image as a widget.

The value of this widget accepts a byte string. The byte string is the raw image data that you want the browser to display. You can explicitly define the format of the byte string using the format trait (which defaults to “png”).

If you pass “url” to the “format” trait, value will be interpreted as a URL as bytes encoded in UTF-8.

Public constructor

__init__(*args, **kwargs)

Public constructor

__repr__()

Return repr(self).

format

The format of the image.

height

Height of the image in pixels. Use layout.height for styling the widget.

width

Width of the image in pixels. Use layout.width for styling the widget.

class ipywidgets.widgets.widget_media.Video(**kwargs)

Bases: _Media

Displays a video as a widget.

The value of this widget accepts a byte string. The byte string is the raw video data that you want the browser to display. You can explicitly define the format of the byte string using the format trait (which defaults to “mp4”).

If you pass “url” to the “format” trait, value will be interpreted as a URL as bytes encoded in UTF-8.

Public constructor

__repr__()

Return repr(self).

autoplay

When true, the video starts when it’s displayed

controls

Specifies that video controls should be displayed (such as a play/pause button etc)

format

The format of the video.

height

Height of the video in pixels.

loop

When true, the video will start from the beginning after finishing

width

Width of the video in pixels.

Output class.

Represents a widget that can be used to display output within the widget area.

class ipywidgets.widgets.widget_output.Output(**kwargs)

Bases: DOMWidget

Widget used as a context manager to display output.

This widget can capture and display stdout, stderr, and rich output. To use it, create an instance of it and display it.

You can then use the widget as a context manager: any output produced while in the context will be captured and displayed in the widget instead of the standard output area.

You can also use the .capture() method to decorate a function or a method. Any output produced by the function will then go to the output widget. This is useful for debugging widget callbacks, for example.

Example::

import ipywidgets as widgets from IPython.display import display out = widgets.Output() display(out)

print(‘prints to output area’)

with out:

print(‘prints to output widget’)

@out.capture() def func():

print(‘prints to output widget’)

Public constructor

__enter__()

Called upon entering output widget context manager.

__exit__(etype, evalue, tb)

Called upon exiting output widget context manager.

append_display_data(display_object)

Append a display object as an output.

Parameters

display_objectIPython.core.display.DisplayObject

The object to display (e.g., an instance of IPython.display.Markdown or IPython.display.Image).

append_stderr(text)

Append text to the stderr stream.

append_stdout(text)

Append text to the stdout stream.

capture(clear_output=False, *clear_args, **clear_kwargs)

Decorator to capture the stdout and stderr of a function.

Parameters

clear_output: bool

If True, clear the content of the output widget at every new function call. Default: False

wait: bool

If True, wait to clear the output until new output is available to replace it. This is only used if clear_output is also True. Default: False

clear_output(*pargs, **kwargs)

Clear the content of the output widget.

Parameters

wait: bool

If True, wait to clear the output until new output is available to replace it. Default: False

msg_id

Parent message id of messages to capture

Selection classes.

Represents an enumeration using a widget.

class ipywidgets.widgets.widget_selection.Dropdown(**kwargs)

Bases: _Selection

Allows you to select a single item from a dropdown.

Parameters

options: list

The options for the dropdown. This can either be a list of values, e.g. ['Galileo', 'Brahe', 'Hubble'] or [0, 1, 2], a list of (label, value) pairs, e.g. [('Galileo', 0), ('Brahe', 1), ('Hubble', 2)], or a Mapping between labels and values, e.g., {'Galileo': 0, 'Brahe': 1, 'Hubble': 2}.

index: int

The index of the current selection.

value: any

The value of the current selection. When programmatically setting the value, a reverse lookup is performed among the options to check that the value is valid. The reverse lookup uses the equality operator by default, but another predicate may be provided via the equals keyword argument. For example, when dealing with numpy arrays, one may set equals=np.array_equal.

label: str

The label corresponding to the selected value.

disabled: bool

Whether to disable user changes.

description: str

Label for this input group. This should be a string describing the widget.

Public constructor

class ipywidgets.widgets.widget_selection.RadioButtons(**kwargs)

Bases: _Selection

Group of radio buttons that represent an enumeration.

Only one radio button can be toggled at any point in time.

Parameters

options: list

The options for the dropdown. This can either be a list of values, e.g. ['Galileo', 'Brahe', 'Hubble'] or [0, 1, 2], a list of (label, value) pairs, e.g. [('Galileo', 0), ('Brahe', 1), ('Hubble', 2)], or a Mapping between labels and values, e.g., {'Galileo': 0, 'Brahe': 1, 'Hubble': 2}.

index: int

The index of the current selection.

value: any

The value of the current selection. When programmatically setting the value, a reverse lookup is performed among the options to check that the value is valid. The reverse lookup uses the equality operator by default, but another predicate may be provided via the equals keyword argument. For example, when dealing with numpy arrays, one may set equals=np.array_equal.

label: str

The label corresponding to the selected value.

disabled: bool

Whether to disable user changes.

description: str

Label for this input group. This should be a string describing the widget.

Public constructor

class ipywidgets.widgets.widget_selection.Select(**kwargs)

Bases: _Selection

Listbox that only allows one item to be selected at any given time.

Parameters

options: list

The options for the dropdown. This can either be a list of values, e.g. ['Galileo', 'Brahe', 'Hubble'] or [0, 1, 2], a list of (label, value) pairs, e.g. [('Galileo', 0), ('Brahe', 1), ('Hubble', 2)], or a Mapping between labels and values, e.g., {'Galileo': 0, 'Brahe': 1, 'Hubble': 2}.

index: int

The index of the current selection.

value: any

The value of the current selection. When programmatically setting the value, a reverse lookup is performed among the options to check that the value is valid. The reverse lookup uses the equality operator by default, but another predicate may be provided via the equals keyword argument. For example, when dealing with numpy arrays, one may set equals=np.array_equal.

label: str

The label corresponding to the selected value.

disabled: bool

Whether to disable user changes.

description: str

Label for this input group. This should be a string describing the widget.

rows: int

The number of rows to display in the widget.

Public constructor

rows

The number of rows to display.

class ipywidgets.widgets.widget_selection.SelectMultiple(**kwargs)

Bases: _MultipleSelection

Listbox that allows many items to be selected at any given time.

The value, label and index attributes are all iterables.

Parameters

options: dict or list

The options for the dropdown. This can either be a list of values, e.g. ['Galileo', 'Brahe', 'Hubble'] or [0, 1, 2], or a list of (label, value) pairs, e.g. [('Galileo', 0), ('Brahe', 1), ('Hubble', 2)], or a Mapping between labels and values, e.g., {'Galileo': 0, 'Brahe': 1, 'Hubble': 2}. The labels are the strings that will be displayed in the UI, representing the actual Python choices, and should be unique.

index: iterable of int

The indices of the options that are selected.

value: iterable

The values that are selected. When programmatically setting the value, a reverse lookup is performed among the options to check that the value is valid. The reverse lookup uses the equality operator by default, but another predicate may be provided via the equals keyword argument. For example, when dealing with numpy arrays, one may set equals=np.array_equal.

label: iterable of str

The labels corresponding to the selected value.

disabled: bool

Whether to disable user changes.

description: str

Label for this input group. This should be a string describing the widget.

rows: int

The number of rows to display in the widget.

Public constructor

rows

The number of rows to display.

class ipywidgets.widgets.widget_selection.SelectionRangeSlider(**kwargs)

Bases: _MultipleSelectionNonempty

Slider to select multiple contiguous items from a list.

The index, value, and label attributes contain the start and end of the selection range, not all items in the range.

Parameters

options: dict or list

The options for the dropdown. This can either be a list of values, e.g. ['Galileo', 'Brahe', 'Hubble'] or [0, 1, 2], or a list of (label, value) pairs, e.g. [('Galileo', 0), ('Brahe', 1), ('Hubble', 2)], or a Mapping between labels and values, e.g., {'Galileo': 0, 'Brahe': 1, 'Hubble': 2}. The labels are the strings that will be displayed in the UI, representing the actual Python choices, and should be unique.

index: iterable of int

The indices of the options that are selected.

value: iterable

The values that are selected. When programmatically setting the value, a reverse lookup is performed among the options to check that the value is valid. The reverse lookup uses the equality operator by default, but another predicate may be provided via the equals keyword argument. For example, when dealing with numpy arrays, one may set equals=np.array_equal.

label: iterable of str

The labels corresponding to the selected value.

disabled: bool

Whether to disable user changes.

description: str

Label for this input group. This should be a string describing the widget.

orientation: str

Either 'horizontal' or 'vertical'. Defaults to horizontal.

readout: bool

Display the current label next to the slider. Defaults to True.

continuous_update: bool

If True, update the value of the widget continuously as the user holds the slider. Otherwise, the model is only updated after the user has released the slider. Defaults to True.

Public constructor

behavior

Slider dragging behavior.

continuous_update

Update the value of the widget as the user is holding the slider.

orientation

Vertical or horizontal.

readout

Display the current selected label next to the slider

class ipywidgets.widgets.widget_selection.SelectionSlider(**kwargs)

Bases: _SelectionNonempty

Slider to select a single item from a list or dictionary.

Parameters

options: list

The options for the dropdown. This can either be a list of values, e.g. ['Galileo', 'Brahe', 'Hubble'] or [0, 1, 2], a list of (label, value) pairs, e.g. [('Galileo', 0), ('Brahe', 1), ('Hubble', 2)], or a Mapping between labels and values, e.g., {'Galileo': 0, 'Brahe': 1, 'Hubble': 2}.

index: int

The index of the current selection.

value: any

The value of the current selection. When programmatically setting the value, a reverse lookup is performed among the options to check that the value is valid. The reverse lookup uses the equality operator by default, but another predicate may be provided via the equals keyword argument. For example, when dealing with numpy arrays, one may set equals=np.array_equal.

label: str

The label corresponding to the selected value.

disabled: bool

Whether to disable user changes.

description: str

Label for this input group. This should be a string describing the widget.

orientation: str

Either 'horizontal' or 'vertical'. Defaults to horizontal.

readout: bool

Display the current label next to the slider. Defaults to True.

continuous_update: bool

If True, update the value of the widget continuously as the user holds the slider. Otherwise, the model is only updated after the user has released the slider. Defaults to True.

Public constructor

behavior

Slider dragging behavior.

continuous_update

Update the value of the widget as the user is holding the slider.

orientation

Vertical or horizontal.

readout

Display the current selected label next to the slider

class ipywidgets.widgets.widget_selection.ToggleButtons(**kwargs)

Bases: _Selection

Group of toggle buttons that represent an enumeration.

Only one toggle button can be toggled at any point in time.

Parameters

options: list

The options for the dropdown. This can either be a list of values, e.g. ['Galileo', 'Brahe', 'Hubble'] or [0, 1, 2], a list of (label, value) pairs, e.g. [('Galileo', 0), ('Brahe', 1), ('Hubble', 2)], or a Mapping between labels and values, e.g., {'Galileo': 0, 'Brahe': 1, 'Hubble': 2}.

index: int

The index of the current selection.

value: any

The value of the current selection. When programmatically setting the value, a reverse lookup is performed among the options to check that the value is valid. The reverse lookup uses the equality operator by default, but another predicate may be provided via the equals keyword argument. For example, when dealing with numpy arrays, one may set equals=np.array_equal.

label: str

The label corresponding to the selected value.

disabled: bool

Whether to disable user changes.

description: str

Label for this input group. This should be a string describing the widget.

tooltips: list

Tooltip for each button. If specified, must be the same length as options.

icons: list

Icons to show on the buttons. This must be the name of a font-awesome icon. See http://fontawesome.io/icons/ for a list of icons.

button_style: str

One of ‘primary’, ‘success’, ‘info’, ‘warning’ or ‘danger’. Applies a predefined style to every button.

style: ToggleButtonsStyle

Style parameters for the buttons.

Public constructor

button_style

Use a predefined styling for the buttons.

class ipywidgets.widgets.widget_selection.ToggleButtonsStyle(**kwargs)

Bases: DescriptionStyle, CoreWidget

Button style widget.

Parameters

button_width: str

The width of each button. This should be a valid CSS width, e.g. ‘10px’ or ‘5em’.

font_weight: str

The text font weight of each button, This should be a valid CSS font weight unit, for example ‘bold’ or ‘600’

Public constructor

button_width

The width of each button.

font_weight

Text font weight of each button.

ipywidgets.widgets.widget_selection.findvalue(array, value, compare=<function <lambda>>)

A function that uses the compare function to return a value from the list.

SelectionContainer class.

Represents a multipage container that can be used to group other widgets into pages.

class ipywidgets.widgets.widget_selectioncontainer.Accordion(**kwargs)

Bases: _SelectionContainer

Displays children each on a separate accordion page.

Public constructor

class ipywidgets.widgets.widget_selectioncontainer.Stack(**kwargs)

Bases: _SelectionContainer

Displays only the selected child.

Public constructor

class ipywidgets.widgets.widget_selectioncontainer.Tab(**kwargs)

Bases: _SelectionContainer

Displays children each on a separate accordion tab.

Public constructor

__init__(children=(), **kwargs)

Public constructor

ipywidgets.widgets.widget_selectioncontainer.pad(iterable, padding=None, length=None)

Returns the sequence elements and then returns None up to the given size (or indefinitely if size is None).

String class.

Represents a unicode string using a widget.

class ipywidgets.widgets.widget_string.Combobox(**kwargs)

Bases: Text

Single line textbox widget with a dropdown and autocompletion.

Public constructor

ensure_option

If set, ensure value is in options. Implies continuous_update=False.

class ipywidgets.widgets.widget_string.HTML(**kwargs)

Bases: _String

Renders the string value as HTML.

Public constructor

class ipywidgets.widgets.widget_string.HTMLMath(**kwargs)

Bases: _String

Renders the string value as HTML, and render mathematics.

Public constructor

class ipywidgets.widgets.widget_string.HTMLMathStyle(**kwargs)

Bases: _StringStyle

HTML with math style widget.

Public constructor

class ipywidgets.widgets.widget_string.HTMLStyle(**kwargs)

Bases: _StringStyle

HTML style widget.

Public constructor

class ipywidgets.widgets.widget_string.Label(**kwargs)

Bases: _String

Label widget.

It also renders math inside the string value as Latex (requires $ $ or $$ $$ and similar latex tags).

Public constructor

class ipywidgets.widgets.widget_string.LabelStyle(**kwargs)

Bases: _StringStyle

Label style widget.

Public constructor

font_family

Label text font family.

font_style

Label text font style.

font_variant

Label text font variant.

font_weight

Label text font weight.

text_decoration

Label text decoration.

class ipywidgets.widgets.widget_string.Password(**kwargs)

Bases: Text

Single line textbox widget.

Public constructor

disabled

Enable or disable user changes

class ipywidgets.widgets.widget_string.Text(**kwargs)

Bases: _String

Single line textbox widget.

Public constructor

__init__(*args, **kwargs)

Public constructor

continuous_update

Update the value as the user types. If False, update on submission, e.g., pressing Enter or navigating away.

disabled

Enable or disable user changes

on_submit(callback, remove=False)

(Un)Register a callback to handle text submission.

Triggered when the user clicks enter.

Parameters

callback: callable

Will be called with exactly one argument: the Widget instance

remove: bool (optional)

Whether to unregister the callback

class ipywidgets.widgets.widget_string.TextStyle(**kwargs)

Bases: _StringStyle

Text input style widget.

Public constructor

class ipywidgets.widgets.widget_string.Textarea(**kwargs)

Bases: _String

Multiline text area widget.

Public constructor

continuous_update

Update the value as the user types. If False, update on submission, e.g., pressing Enter or navigating away.

disabled

Enable or disable user changes

rows

The number of rows to display.

Contains the Style class

class ipywidgets.widgets.widget_style.Style(**kwargs)

Bases: Widget

Style specification

Public constructor

TagsInput class.

Represents a list of tags.

class ipywidgets.widgets.widget_tagsinput.ColorsInput(**kwargs)

Bases: TagsInputBase

List of color tags

Public constructor

class ipywidgets.widgets.widget_tagsinput.FloatsInput(**kwargs)

Bases: NumbersInputBase

List of float tags

Public constructor

class ipywidgets.widgets.widget_tagsinput.IntsInput(**kwargs)

Bases: NumbersInputBase

List of int tags

Public constructor

class ipywidgets.widgets.widget_tagsinput.NumbersInputBase(**kwargs)

Bases: TagsInput

Public constructor

class ipywidgets.widgets.widget_tagsinput.TagsInput(**kwargs)

Bases: TagsInputBase

List of string tags

Public constructor

tag_style

Use a predefined styling for the tags.

class ipywidgets.widgets.widget_tagsinput.TagsInputBase(**kwargs)

Bases: DescriptionWidget, ValueWidget, CoreWidget

Public constructor

Implement common widgets layouts as reusable components

class ipywidgets.widgets.widget_templates.AppLayout(**kwargs)

Bases: GridBox, LayoutProperties

Define an application like layout of widgets.

Parameters

header: instance of Widget left_sidebar: instance of Widget center: instance of Widget right_sidebar: instance of Widget footer: instance of Widget

widgets to fill the positions in the layout

merge: bool

flag to say whether the empty positions should be automatically merged

pane_widths: list of numbers/strings

the fraction of the total layout width each of the central panes should occupy (left_sidebar, center, right_sidebar)

pane_heights: list of numbers/strings

the fraction of the width the vertical space that the panes should occupy

(left_sidebar, center, right_sidebar)

grid_gapstr

CSS attribute used to set the gap between the grid cells

justify_contentstr, in [‘flex-start’, ‘flex-end’, ‘center’, ‘space-between’, ‘space-around’]

CSS attribute used to align widgets vertically

align_itemsstr, in [‘top’, ‘bottom’, ‘center’, ‘flex-start’, ‘flex-end’, ‘baseline’, ‘stretch’]

CSS attribute used to align widgets horizontally

width : str height : str

width and height

Examples

Public constructor

__init__(**kwargs)

Public constructor

class ipywidgets.widgets.widget_templates.GridspecLayout(**kwargs)

Bases: GridBox, LayoutProperties

Define a N by M grid layout

Parameters

n_rowsint

number of rows in the grid

n_columnsint

number of columns in the grid

grid_gapstr

CSS attribute used to set the gap between the grid cells

justify_contentstr, in [‘flex-start’, ‘flex-end’, ‘center’, ‘space-between’, ‘space-around’]

CSS attribute used to align widgets vertically

align_itemsstr, in [‘top’, ‘bottom’, ‘center’, ‘flex-start’, ‘flex-end’, ‘baseline’, ‘stretch’]

CSS attribute used to align widgets horizontally

width : str height : str

width and height

Examples

>>> from ipywidgets import GridspecLayout, Button, Layout
>>> layout = GridspecLayout(n_rows=4, n_columns=2, height='200px')
>>> layout[:3, 0] = Button(layout=Layout(height='auto', width='auto'))
>>> layout[1:, 1] = Button(layout=Layout(height='auto', width='auto'))
>>> layout[-1, 0] = Button(layout=Layout(height='auto', width='auto'))
>>> layout[0, 1] = Button(layout=Layout(height='auto', width='auto'))
>>> layout

Public constructor

__init__(n_rows=None, n_columns=None, **kwargs)

Public constructor

class ipywidgets.widgets.widget_templates.LayoutProperties(**kwargs)

Bases: HasTraits

Mixin class for layout templates

This class handles mainly style attributes (height, grid_gap etc.)

Parameters

grid_gapstr

CSS attribute used to set the gap between the grid cells

justify_contentstr, in [‘flex-start’, ‘flex-end’, ‘center’, ‘space-between’, ‘space-around’]

CSS attribute used to align widgets vertically

align_itemsstr, in [‘top’, ‘bottom’, ‘center’, ‘flex-start’, ‘flex-end’, ‘baseline’, ‘stretch’]

CSS attribute used to align widgets horizontally

width : str height : str

width and height

Note

This class is only meant to be used in inheritance as mixin with other classes. It will not work, unless self.layout attribute is defined.

__init__(**kwargs)

align_items

The align-items CSS attribute.

grid_gap

The grid-gap CSS attribute.

height

The width CSS attribute.

justify_content

The justify-content CSS attribute.

width

The width CSS attribute.

class ipywidgets.widgets.widget_templates.TwoByTwoLayout(**kwargs)

Bases: GridBox, LayoutProperties

Define a layout with 2x2 regular grid.

Parameters

top_left: instance of Widget top_right: instance of Widget bottom_left: instance of Widget bottom_right: instance of Widget

widgets to fill the positions in the layout

merge: bool

flag to say whether the empty positions should be automatically merged

grid_gapstr

CSS attribute used to set the gap between the grid cells

justify_contentstr, in [‘flex-start’, ‘flex-end’, ‘center’, ‘space-between’, ‘space-around’]

CSS attribute used to align widgets vertically

align_itemsstr, in [‘top’, ‘bottom’, ‘center’, ‘flex-start’, ‘flex-end’, ‘baseline’, ‘stretch’]

CSS attribute used to align widgets horizontally

width : str height : str

width and height

Examples

>>> from ipywidgets import TwoByTwoLayout, Button
>>> TwoByTwoLayout(top_left=Button(description="Top left"),
...                top_right=Button(description="Top right"),
...                bottom_left=Button(description="Bottom left"),
...                bottom_right=Button(description="Bottom right"))

Public constructor

__init__(**kwargs)

Public constructor

Time picker widget

class ipywidgets.widgets.widget_time.TimePicker(**kwargs)

Bases: DescriptionWidget, ValueWidget, CoreWidget

Display a widget for picking times.

Parameters

value: datetime.time

The current value of the widget.

disabled: bool

Whether to disable user changes.

min: datetime.time

The lower allowed time bound

max: datetime.time

The upper allowed time bound

step: float | ‘any’

The time step to use for the picker, in seconds, or “any”

Examples

>>> import datetime
>>> import ipydatetime
>>> time_pick = ipydatetime.TimePicker()
>>> time_pick.value = datetime.time(12, 34, 3)

Public constructor

disabled

Enable or disable user changes.

step

The time step to use for the picker, in seconds, or “any”.

FileUpload class.

Represents a file upload button.

class ipywidgets.widgets.widget_upload.FileUpload(**kwargs)

Bases: DescriptionWidget, ValueWidget, CoreWidget

File upload widget

This creates a file upload input that allows the user to select one or more files to upload. The file metadata and content can be retrieved in the kernel.

>>> import ipywidgets as widgets
>>> uploader = widgets.FileUpload()

# After displaying uploader and uploading a file:

>>> uploader.value
[
  {
    'name': 'example.txt',
    'type': 'text/plain',
    'size': 36,
    'last_modified': datetime.datetime(2020, 1, 9, 15, 58, 43, 321000, tzinfo=datetime.timezone.utc),
    'content': <memory at 0x10c1b37c8>
  }
]
>>> uploader.value[0].content.tobytes()
b'This is the content of example.txt.

‘

accept: str, optional

Which file types to accept, e.g. ‘.doc,.docx’. For a full description of how to specify this, see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-accept Defaults to accepting all file types.

multiple: bool, optional

Whether to accept multiple files at the same time. Defaults to False.

disabled: bool, optional

Whether user interaction is enabled.

icon: str, optional

The icon to use for the button displayed on the screen. Can be any Font-awesome icon without the fa- prefix. Defaults to ‘upload’. If missing, no icon is shown.

description: str, optional

The text to show on the label. Defaults to ‘Upload’.

button_style: str, optional

One of ‘primary’, ‘success’, ‘info’, ‘warning’, ‘danger’ or ‘’.

style: widgets.widget_button.ButtonStyle, optional

Style configuration for the button.

value: Tuple[Dict], optional

The value of the last uploaded file or set of files. See the documentation for details of how to use this to retrieve file content and metadata: https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20List.html#File-Upload

error: str, optional

Whether the last upload triggered an error.

Public constructor

accept

File types to accept, empty string for all

button_style

Use a predefined styling for the button.

disabled

Enable or disable button

error

Error message

icon

Font-awesome icon name, without the ‘fa-’ prefix.

multiple

If True, allow for multiple files upload

Utilities

ipywidgets.widgets.docutils.doc_subst(snippets)

Substitute format strings in class or function docstring

ipywidgets.widgets.utils.deprecation(message, internal='ipywidgets/widgets/')

Generate a deprecation warning targeting the first frame that is not ‘internal’

internal is a string or list of strings, which if they appear in filenames in the frames, the frames will be considered internal. Changing this can be useful if, for examnple, we know that ipywidgets is calling out to traitlets internally.

Top-level exports

These are seldom needed by users or widget authors

Interactive widgets for the Jupyter notebook.

Provide simple interactive controls in the notebook. Each Widget corresponds to an object in Python and Javascript, with controls on the page.

To put a Widget on the page, you can display it with Jupyter’s display machinery:

from ipywidgets import IntSlider
slider = IntSlider(min=1, max=10)
display(slider)

Moving the slider will change the value. Most Widgets have a current value, accessible as a value attribute.

ipywidgets.load_ipython_extension(ip)

Set up Jupyter to work with widgets

ipywidgets.register_comm_target(kernel=None)

Register the jupyter.widget comm target