from __future__ import absolute_import

import collections

from collections import OrderedDict

import re

import six

from six import string_types

import warnings

from contextlib import contextmanager

from copy import deepcopy, copy

from _plotly_utils.utils import _natural_sort_strings

from plotly.subplots import (

_set_trace_grid_reference,

_get_grid_subplot,

_get_subplot_ref_for_trace)

from .optional_imports import get_module

from _plotly_utils.basevalidators import (

CompoundValidator, CompoundArrayValidator, BaseDataValidator,

BaseValidator, LiteralValidator

)

from . import animation

from .callbacks import (Points, InputDeviceState)

from plotly.utils import ElidedPrettyPrinter

from .validators import (DataValidator, LayoutValidator, FramesValidator)

# Create Undefined sentinel value

# - Setting a property to None removes any existing value

# - Setting a property to Undefined leaves existing value unmodified

Undefined = object()

class BaseFigure(object):

"""

Base class for all figure types (both widget and non-widget)

"""

_bracket_re = re.compile('^(.*)\[(\d+)\]$')

_valid_underscore_properties = {

'error_x': 'error-x',

'error_y': 'error-y',

'error_z': 'error-z',

'copy_xstyle': 'copy-xstyle',

'copy_ystyle': 'copy-ystyle',

'copy_zstyle': 'copy-zstyle',

'paper_bgcolor': 'paper-bgcolor',

'plot_bgcolor': 'plot-bgcolor'

}

_set_trace_uid = False

# Constructor

# -----------

def __init__(self,

data=None,

layout_plotly=None,

frames=None,

skip_invalid=False,

**kwargs):

"""

Construct a BaseFigure object

Parameters

----------

data

One of:

- A list or tuple of trace objects (or dicts that can be coerced

into trace objects)

- If `data` is a dict that contains a 'data',

'layout', or 'frames' key then these values are used to

construct the figure.

- If `data` is a `BaseFigure` instance then the `data`, `layout`,

and `frames` properties are extracted from the input figure

layout_plotly

The plotly layout dict.

Note: this property is named `layout_plotly` rather than `layout`

to deconflict it with the `layout` constructor parameter of the

`widgets.DOMWidget` ipywidgets class, as the `BaseFigureWidget`

class is a subclass of both BaseFigure and widgets.DOMWidget.

If the `data` property is a BaseFigure instance, or a dict that

contains a 'layout' key, then this property is ignored.

frames

A list or tuple of `plotly.graph_objs.Frame` objects (or dicts

that can be coerced into Frame objects)

If the `data` property is a BaseFigure instance, or a dict that

contains a 'frames' key, then this property is ignored.

skip_invalid: bool

If True, invalid properties in the figure specification will be

skipped silently. If False (default) invalid properties in the

figure specification will result in a ValueError

Raises

------

ValueError

if a property in the specification of data, layout, or frames

is invalid AND skip_invalid is False

"""

super(BaseFigure, self).__init__()

# Assign layout_plotly to layout

# ------------------------------

# See docstring note for explanation

layout = layout_plotly

# Subplot properties

# ------------------

# These properties are used by the tools.make_subplots logic.

# We initialize them to None here, before checking if the input data

# object is a BaseFigure, or a dict with _grid_str and _grid_ref

# properties, in which case we bring over the _grid* properties of

# the input

self._grid_str = None

self._grid_ref = None

# Handle case where data is a Figure or Figure-like dict

# ------------------------------------------------------

if isinstance(data, BaseFigure):

# Bring over subplot fields

self._grid_str = data._grid_str

self._grid_ref = data._grid_ref

# Extract data, layout, and frames

data, layout, frames = data.data, data.layout, data.frames

elif (isinstance(data, dict)

and ('data' in data or 'layout' in data or 'frames' in data)):

# Bring over subplot fields

self._grid_str = data.get('_grid_str', None)

self._grid_ref = data.get('_grid_ref', None)

# Extract data, layout, and frames

data, layout, frames = (data.get('data', None),

data.get('layout', None),

data.get('frames', None))

# Handle data (traces)

# --------------------

# ### Construct data validator ###

# This is the validator that handles importing sequences of trace

# objects

self._data_validator = DataValidator(set_uid=self._set_trace_uid)

# ### Import traces ###

data = self._data_validator.validate_coerce(data,

skip_invalid=skip_invalid)

# ### Save tuple of trace objects ###

self._data_objs = data

# ### Import clone of trace properties ###

# The _data property is a list of dicts containing the properties

# explicitly set by the user for each trace.

self._data = [deepcopy(trace._props) for trace in data]

# ### Create data defaults ###

# _data_defaults is a tuple of dicts, one for each trace. When

# running in a widget context, these defaults are populated with

# all property values chosen by the Plotly.js library that

# aren't explicitly specified by the user.

#

# Note: No property should exist in both the _data and

# _data_defaults for the same trace.

self._data_defaults = [{} for _ in data]

# ### Reparent trace objects ###

for trace_ind, trace in enumerate(data):

# By setting the trace's parent to be this figure, we tell the

# trace object to use the figure's _data and _data_defaults

# dicts to get/set it's properties, rather than using the trace

# object's internal _orphan_props dict.

trace._parent = self

# We clear the orphan props since the trace no longer needs then

trace._orphan_props.clear()

# Set trace index

trace._trace_ind = trace_ind

# Layout

# ------

# ### Construct layout validator ###

# This is the validator that handles importing Layout objects

self._layout_validator = LayoutValidator()

# ### Import Layout ###

self._layout_obj = self._layout_validator.validate_coerce(

layout, skip_invalid=skip_invalid)

# ### Import clone of layout properties ###

self._layout = deepcopy(self._layout_obj._props)

# ### Initialize layout defaults dict ###

self._layout_defaults = {}

# ### Reparent layout object ###

self._layout_obj._orphan_props.clear()

self._layout_obj._parent = self

# Config

# ------

# Pass along default config to the front end. For now this just

# ensures that the plotly domain url gets passed to the front end.

# In the future we can extend this to allow the user to supply

# arbitrary config options like in plotly.offline.plot/iplot. But

# this will require a fair amount of testing to determine which

# options are compatible with FigureWidget.

from plotly.offline.offline import _get_jconfig

self._config = _get_jconfig(None)

# Frames

# ------

# ### Construct frames validator ###

# This is the validator that handles importing sequences of frame

# objects

self._frames_validator = FramesValidator()

# ### Import frames ###

self._frame_objs = self._frames_validator.validate_coerce(

frames, skip_invalid=skip_invalid)

# Note: Because frames are not currently supported in the widget

# context, we don't need to follow the pattern above and create

# _frames and _frame_defaults properties and then reparent the

# frames. The figure doesn't need to be notified of

# changes to the properties in the frames object hierarchy.

# Context manager

# ---------------

# ### batch mode indicator ###

# Flag that indicates whether we're currently inside a batch_*()

# context

self._in_batch_mode = False

# ### Batch trace edits ###

# Dict from trace indexes to trace edit dicts. These trace edit dicts

# are suitable as `data` elements of Plotly.animate, but not

# the Plotly.update (See `_build_update_params_from_batch`)

#

# type: OrderedDict[int, OrderedDict[str, typ.Any]]

self._batch_trace_edits = OrderedDict()

# ### Batch layout edits ###

# Dict from layout properties to new layout values. This dict is

# directly suitable for use in Plotly.animate and Plotly.update

# type: collections.OrderedDict[str, typ.Any]

self._batch_layout_edits = OrderedDict()

# Animation property validators

# -----------------------------

self._animation_duration_validator = animation.DurationValidator()

self._animation_easing_validator = animation.EasingValidator()

# Template

# --------

# ### Check for default template ###

self._initialize_layout_template()

# Process kwargs

# --------------

for k, v in kwargs.items():

if k in self:

self[k] = v

elif not skip_invalid:

raise TypeError('invalid Figure property: {}'.format(k))

# Magic Methods

# -------------

def __reduce__(self):

"""

Custom implementation of reduce is used to support deep copying

and pickling

"""

props = self.to_dict()

props['_grid_str'] = self._grid_str

props['_grid_ref'] = self._grid_ref

return (self.__class__,

(props,))

def __setitem__(self, prop, value):

# Normalize prop

# --------------

# Convert into a property tuple

orig_prop = prop

prop = BaseFigure._str_to_dict_path(prop)

# Handle empty case

# -----------------

if len(prop) == 0:

raise KeyError(orig_prop)

# Handle scalar case

# ------------------

# e.g. ('foo',)

elif len(prop) == 1:

# ### Unwrap scalar tuple ###

prop = prop[0]

if prop == 'data':

self.data = value

elif prop == 'layout':

self.layout = value

elif prop == 'frames':

self.frames = value

else:

raise KeyError(prop)

# Handle non-scalar case

# ----------------------

# e.g. ('foo', 1)

else:

res = self

for p in prop[:-1]:

res = res[p]

res[prop[-1]] = value

def __setattr__(self, prop, value):

"""

Parameters

----------

prop : str

The name of a direct child of this object

value

New property value

Returns

-------

None

"""

if prop.startswith('_') or hasattr(self, prop):

# Let known properties and private properties through

super(BaseFigure, self).__setattr__(prop, value)

else:

# Raise error on unknown public properties

raise AttributeError(prop)

def __getitem__(self, prop):

# Normalize prop

# --------------

# Convert into a property tuple

orig_prop = prop

prop = BaseFigure._str_to_dict_path(prop)

# Handle scalar case

# ------------------

# e.g. ('foo',)

if len(prop) == 1:

# Unwrap scalar tuple

prop = prop[0]

if prop == 'data':

return self._data_validator.present(self._data_objs)

elif prop == 'layout':

return self._layout_validator.present(self._layout_obj)

elif prop == 'frames':

return self._frames_validator.present(self._frame_objs)

else:

raise KeyError(orig_prop)

# Handle non-scalar case

# ----------------------

# e.g. ('foo', 1)

else:

res = self

for p in prop:

res = res[p]

return res

def __iter__(self):

return iter(('data', 'layout', 'frames'))

def __contains__(self, prop):

prop = BaseFigure._str_to_dict_path(prop)

if prop[0] not in ('data', 'layout', 'frames'):

return False

elif len(prop) == 1:

return True

else:

return prop[1:] in self[prop[0]]

def __eq__(self, other):

if not isinstance(other, BaseFigure):

# Require objects to both be BaseFigure instances

return False

else:

# Compare plotly_json representations

# Use _vals_equal instead of `==` to handle cases where

# underlying dicts contain numpy arrays

return BasePlotlyType._vals_equal(self.to_plotly_json(),

other.to_plotly_json())

def __repr__(self):

"""

Customize Figure representation when displayed in the

terminal/notebook

"""

props = self.to_plotly_json()

# Elide template

template_props = props.get('layout', {}).get('template', {})

if template_props:

props['layout']['template'] = '...'

repr_str = BasePlotlyType._build_repr_for_class(

props=props,

class_name=self.__class__.__name__)

return repr_str

def _repr_mimebundle_(self, include, exclude, **kwargs):

"""

repr_mimebundle should accept include, exclude and **kwargs

"""

import plotly.io as pio

if pio.renderers.render_on_display:

data = pio.renderers._build_mime_bundle(self.to_dict())

if include:

data = {k: v for (k, v) in data.items() if k in include}

if exclude:

data = {k: v for (k, v) in data.items() if k not in exclude}

return data

else:

return None

def update(self, dict1=None, **kwargs):

"""

Update the properties of the figure with a dict and/or with

keyword arguments.

This recursively updates the structure of the figure

object with the values in the input dict / keyword arguments.

Parameters

----------

dict1 : dict

Dictionary of properties to be updated

kwargs :

Keyword/value pair of properties to be updated

Examples

--------

>>> import plotly.graph_objs as go

>>> fig = go.Figure(data=[{'y': [1, 2, 3]}])

>>> fig.update(data=[{'y': [4, 5, 6]}])

>>> fig.to_plotly_json()

{'data': [{'type': 'scatter',

'uid': 'e86a7c7a-346a-11e8-8aa8-a0999b0c017b',

'y': array([4, 5, 6], dtype=int32)}],

'layout': {}}

>>> fig = go.Figure(layout={'xaxis':

... {'color': 'green',

... 'range': [0, 1]}})

>>> fig.update({'layout': {'xaxis': {'color': 'pink'}}})

>>> fig.to_plotly_json()

{'data': [],

'layout': {'xaxis':

{'color': 'pink',

'range': [0, 1]}}}

Returns

-------

BaseFigure

Updated figure

"""

with self.batch_update():

for d in [dict1, kwargs]:

if d:

for k, v in d.items():

update_target = self[k]

if update_target == ():

# existing data or frames property is empty

# In this case we accept the v as is.

if k == 'data':

self.add_traces(v)

else:

# Accept v

self[k] = v

elif (isinstance(update_target, BasePlotlyType) or

(isinstance(update_target, tuple) and

isinstance(update_target[0], BasePlotlyType))):

BaseFigure._perform_update(self[k], v)

else:

self[k] = v

return self

# Data

# ----

@property

def data(self):

"""

The `data` property is a tuple of the figure's trace objects

Returns

-------

tuple[BaseTraceType]

"""

return self['data']

@data.setter

def data(self, new_data):

# Validate new_data

# -----------------

err_header = ('The data property of a figure may only be assigned \n'

'a list or tuple that contains a permutation of a '

'subset of itself.\n')

# ### Check valid input type ###

if not isinstance(new_data, (list, tuple)):

err_msg = (err_header + ' Received value with type {typ}'

.format(typ=type(new_data)))

raise ValueError(err_msg)

# ### Check valid element types ###

for trace in new_data:

if not isinstance(trace, BaseTraceType):

err_msg = (

err_header + ' Received element value of type {typ}'

.format(typ=type(trace)))

raise ValueError(err_msg)

# ### Check trace objects ###

# Require that no new traces are introduced

orig_uids = [id(trace) for trace in self.data]

new_uids = [id(trace) for trace in new_data]

invalid_uids = set(new_uids).difference(set(orig_uids))

if invalid_uids:

err_msg = err_header

raise ValueError(err_msg)

# ### Check for duplicates in assignment ###

uid_counter = collections.Counter(new_uids)

duplicate_uids = [

uid for uid, count in uid_counter.items() if count > 1

]

if duplicate_uids:

err_msg = (

err_header + ' Received duplicated traces')

raise ValueError(err_msg)

# Remove traces

# -------------

remove_uids = set(orig_uids).difference(set(new_uids))

delete_inds = []

# ### Unparent removed traces ###

for i, trace in enumerate(self.data):

if id(trace) in remove_uids:

delete_inds.append(i)

# Unparent trace object to be removed

old_trace = self.data[i]

old_trace._orphan_props.update(deepcopy(old_trace._props))

old_trace._parent = None

old_trace._trace_ind = None

# ### Compute trace props / defaults after removal ###

traces_props_post_removal = [t for t in self._data]

traces_prop_defaults_post_removal = [t for t in self._data_defaults]

uids_post_removal = [id(trace_data) for trace_data in self.data]

for i in reversed(delete_inds):

del traces_props_post_removal[i]

del traces_prop_defaults_post_removal[i]

del uids_post_removal[i]

# Modify in-place so we don't trigger serialization

del self._data[i]

if delete_inds:

# Update widget, if any

self._send_deleteTraces_msg(delete_inds)

# Move traces

# -----------

# ### Compute new index for each remaining trace ###

new_inds = []

for uid in uids_post_removal:

new_inds.append(new_uids.index(uid))

# ### Compute current index for each remaining trace ###

current_inds = list(range(len(traces_props_post_removal)))

# ### Check whether a move is needed ###

if not all([i1 == i2 for i1, i2 in zip(new_inds, current_inds)]):

# #### Update widget, if any ####

self._send_moveTraces_msg(current_inds, new_inds)

# #### Reorder trace elements ####

# We do so in-place so we don't trigger traitlet property

# serialization for the FigureWidget case

# ##### Remove by curr_inds in reverse order #####

moving_traces_data = []

for ci in reversed(current_inds):

# Push moving traces data to front of list

moving_traces_data.insert(0, self._data[ci])

del self._data[ci]

# #### Sort new_inds and moving_traces_data by new_inds ####

new_inds, moving_traces_data = zip(

*sorted(zip(new_inds, moving_traces_data)))

# #### Insert by new_inds in forward order ####

for ni, trace_data in zip(new_inds, moving_traces_data):

self._data.insert(ni, trace_data)

# ### Update data defaults ###

# There is to front-end syncronization to worry about so this

# operations doesn't need to be in-place

self._data_defaults = [

_trace for i, _trace in sorted(

zip(new_inds, traces_prop_defaults_post_removal))

]

# Update trace objects tuple

self._data_objs = list(new_data)

# Update trace indexes

for trace_ind, trace in enumerate(self._data_objs):

trace._trace_ind = trace_ind

def select_traces(

self, selector=None, row=None, col=None, secondary_y=None):

"""

Select traces from a particular subplot cell and/or traces

that satisfy custom selection criteria.

Parameters

----------

selector: dict or None (default None)

Dict to use as selection criteria.

Traces will be selected if they contain properties corresponding

to all of the dictionary's keys, with values that exactly match

the supplied values. If None (the default), all traces are

selected.

row, col: int or None (default None)

Subplot row and column index of traces to select.

To select traces by row and column, the Figure must have been

created using plotly.subplots.make_subplots. If None

(the default), all traces are selected.

secondary_y: boolean or None (default None)

* If True, only select traces associated with the secondary

y-axis of the subplot.

* If False, only select traces associated with the primary

y-axis of the subplot.

* If None (the default), do not filter traces based on secondary

y-axis.

To select traces by secondary y-axis, the Figure must have been

created using plotly.subplots.make_subplots. See the docstring

for the specs argument to make_subplots for more info on

creating subplots with secondary y-axes.

Returns

-------

generator

Generator that iterates through all of the traces that satisfy

all of the specified selection criteria

"""

if not selector:

selector = {}

if row is not None or col is not None or secondary_y is not None:

grid_ref = self._validate_get_grid_ref()

filter_by_subplot = True

if row is None and col is not None:

# All rows for column

grid_subplot_ref_tuples = [

ref_row[col-1] for ref_row in grid_ref

]

elif col is None and row is not None:

# All columns for row

grid_subplot_ref_tuples = grid_ref[row-1]

elif col is not None and row is not None:

# Single grid cell

grid_subplot_ref_tuples = [grid_ref[row-1][col-1]]

else:

# row and col are None, secondary_y not None

grid_subplot_ref_tuples = [

refs

for refs_row in grid_ref

for refs in refs_row

]

# Collect list of subplot refs, taking secondary_y into account

grid_subplot_refs = []

for refs in grid_subplot_ref_tuples:

if not refs:

continue

if secondary_y is not True:

grid_subplot_refs.append(refs[0])

if secondary_y is not False and len(refs) > 1:

grid_subplot_refs.append(refs[1])

else:

filter_by_subplot = False

grid_subplot_refs = None

return self._perform_select_traces(

filter_by_subplot, grid_subplot_refs, selector)

def _perform_select_traces(

self, filter_by_subplot, grid_subplot_refs, selector):

for trace in self.data:

# Filter by subplot

if filter_by_subplot:

trace_subplot_ref = _get_subplot_ref_for_trace(trace)

if trace_subplot_ref not in grid_subplot_refs:

continue

# Filter by selector

if not self._selector_matches(trace, selector):

continue

yield trace

@staticmethod

def _selector_matches(obj, selector):

if selector is None:

return True

for k in selector:

if k not in obj:

return False

obj_val = obj[k]

selector_val = selector[k]

if isinstance(obj_val, BasePlotlyType):

obj_val = obj_val.to_plotly_json()

if isinstance(selector_val, BasePlotlyType):

selector_val = selector_val.to_plotly_json()

if obj_val != selector_val:

return False

return True

def for_each_trace(

self, fn, selector=None, row=None, col=None, secondary_y=None):

"""

Apply a function to all traces that satisfy the specified selection

criteria

Parameters

----------

fn:

Function that inputs a single trace object.

selector: dict or None (default None)

Dict to use as selection criteria.

Traces will be selected if they contain properties corresponding

to all of the dictionary's keys, with values that exactly match

the supplied values. If None (the default), all traces are

selected.

row, col: int or None (default None)

Subplot row and column index of traces to select.

To select traces by row and column, the Figure must have been

created using plotly.subplots.make_subplots. If None

(the default), all traces are selected.

secondary_y: boolean or None (default None)

* If True, only select traces associated with the secondary

y-axis of the subplot.

* If False, only select traces associated with the primary

y-axis of the subplot.

* If None (the default), do not filter traces based on secondary

y-axis.

To select traces by secondary y-axis, the Figure must have been

created using plotly.subplots.make_subplots. See the docstring

for the specs argument to make_subplots for more info on

creating subplots with secondary y-axes.

Returns

-------

self

Returns the Figure object that the method was called on

"""

for trace in self.select_traces(

selector=selector, row=row, col=col, secondary_y=secondary_y):

fn(trace)

return self

def update_traces(

self,

patch=None,

selector=None,

row=None,

col=None,

secondary_y=None,

**kwargs

):

"""

Perform a property update operation on all traces that satisfy the

specified selection criteria

Parameters

----------

patch: dict or None (default None)

Dictionary of property updates to be applied to all traces that

satisfy the selection criteria.

selector: dict or None (default None)

Dict to use as selection criteria.

Traces will be selected if they contain properties corresponding

to all of the dictionary's keys, with values that exactly match

the supplied values. If None (the default), all traces are

selected.

row, col: int or None (default None)

Subplot row and column index of traces to select.

To select traces by row and column, the Figure must have been

created using plotly.subplots.make_subplots. If None

(the default), all traces are selected.

secondary_y: boolean or None (default None)

* If True, only select traces associated with the secondary

y-axis of the subplot.

* If False, only select traces associated with the primary

y-axis of the subplot.

* If None (the default), do not filter traces based on secondary

y-axis.

To select traces by secondary y-axis, the Figure must have been

created using plotly.subplots.make_subplots. See the docstring

for the specs argument to make_subplots for more info on

creating subplots with secondary y-axes.

**kwargs

Additional property updates to apply to each selected trace. If

a property is specified in both patch and in **kwargs then the

one in **kwargs takes precedence.

Returns

-------

self

Returns the Figure object that the method was called on

"""

for trace in self.select_traces(

selector=selector, row=row, col=col, secondary_y=secondary_y):

trace.update(patch, **kwargs)

return self

def _select_layout_subplots_by_prefix(

self,

prefix,

selector=None,

row=None,

col=None,

secondary_y=None

):

"""

Helper called by code generated select_* methods

"""

if row is not None or col is not None or secondary_y is not None:

# Build mapping from container keys ('xaxis2', 'scene4', etc.)

# to (row, col, secondary_y) triplets

grid_ref = self._validate_get_grid_ref()

container_to_row_col = {}

for r, subplot_row in enumerate(grid_ref):

for c, subplot_refs in enumerate(subplot_row):

if not subplot_refs:

continue

# collect primary keys

for i, subplot_ref in enumerate(subplot_refs):

for layout_key in subplot_ref.layout_keys:

if layout_key.startswith(prefix):

is_secondary_y = i == 1

container_to_row_col[layout_key] = (

r + 1, c + 1, is_secondary_y)

else:

container_to_row_col = None

# Natural sort keys so that xaxis20 is after xaxis3

layout_keys = _natural_sort_strings(list(self.layout))

for k in layout_keys:

if k.startswith(prefix) and self.layout[k] is not None:

# Filter by row/col

if (row is not None and

container_to_row_col.get(

k, (None, None, None))[0] != row):

# row specified and this is not a match

continue

elif (col is not None and

container_to_row_col.get(

k, (None, None, None))[1] != col):

# col specified and this is not a match

continue

elif (secondary_y is not None and

container_to_row_col.get(

k, (None, None, None))[2] != secondary_y):

continue

# Filter by selector

if not self._selector_matches(self.layout[k], selector):

continue

yield self.layout[k]

# Restyle

# -------

def plotly_restyle(self, restyle_data, trace_indexes=None, **kwargs):

"""

Perform a Plotly restyle operation on the figure's traces

Parameters

----------

restyle_data : dict

Dict of trace style updates.

Keys are strings that specify the properties to be updated.

Nested properties are expressed by joining successive keys on

'.' characters (e.g. 'marker.color').

Values may be scalars or lists. When values are scalars,

that scalar value is applied to all traces specified by the

`trace_indexes` parameter. When values are lists,

the restyle operation will cycle through the elements

of the list as it cycles through the traces specified by the

`trace_indexes` parameter.

Caution: To use plotly_restyle to update a list property (e.g.

the `x` property of the scatter trace), the property value

should be a scalar list containing the list to update with. For

example, the following command would be used to update the 'x'

property of the first trace to the list [1, 2, 3]

>>> fig.plotly_restyle({'x': [[1, 2, 3]]}, 0)

trace_indexes : int or list of int

Trace index, or list of trace indexes, that the restyle operation

applies to. Defaults to all trace indexes.

Returns

-------

None

"""

# Normalize trace indexes

# -----------------------

trace_indexes = self._normalize_trace_indexes(trace_indexes)

# Handle source_view_id

# ---------------------

# If not None, the source_view_id is the UID of the frontend

# Plotly.js view that initially triggered this restyle operation

# (e.g. the user clicked on the legend to hide a trace). We pass

# this UID along so that the frontend views can determine whether

# they need to apply the restyle operation on themselves.

source_view_id = kwargs.get('source_view_id', None)

# Perform restyle on trace dicts

# ------------------------------

restyle_changes = self._perform_plotly_restyle(restyle_data,

trace_indexes)

if restyle_changes:

# The restyle operation resulted in a change to some trace

# properties, so we dispatch change callbacks and send the

# restyle message to the frontend (if any)

msg_kwargs = ({'source_view_id': source_view_id}

if source_view_id is not None

else {})

self._send_restyle_msg(

restyle_changes,

trace_indexes=trace_indexes,

**msg_kwargs)

self._dispatch_trace_change_callbacks(

restyle_changes, trace_indexes)

def _perform_plotly_restyle(self, restyle_data, trace_indexes):

"""

Perform a restyle operation on the figure's traces data and return

the changes that were applied

Parameters

----------