"Annotations",

"Area",

"Bar",

"Box",

"Contour",

"Heatmap",

"Histogram",

"Histogram2d",

"Histogram2dContour",

"Scatter",

"Annotation",

"AngularAxis",

"ColorBar",

"Contours",

"ErrorX",

"ErrorY",

"Figure",

"Font",

"Layout",

"Legend",

"Line",

"Margin",

"Marker",

"RadialAxis",

"Stream",

"Trace",

"XAxis",

"XBins",

"YAxis",

plotlylist='PlotlyList',

data='Data',

angularaxis='AngularAxis',

annotations='Annotations',

area='Area',

plotlydict='PlotlyDict',

plotlytrace='PlotlyTrace',

bar='Bar',

box='Box',

contour='Contour',

heatmap='Heatmap',

histogram='Histogram',

histogram2d='Histogram2d',

histogram2dcontour='Histogram2dContour',

scatter='Scatter',

annotation='Annotation',

colorbar='ColorBar',

contours='Contours',

error_x='ErrorX',

error_y='ErrorY',

figure='Figure',

font='Font',

layout='Layout',

legend='Legend',

line='Line',

margin='Margin',

marker='Marker',

radialaxis='RadialAxis',

stream='Stream',

trace='Trace',

textfont='Font',

tickfont='Font',

titlefont='Font',

xaxis='XAxis',

xbins='XBins',

yaxis='YAxis',

ybins='YBins'

PlotlyList='plotlylist',

Data='data',

AngularAxis='angularaxis',

Annotations='annotations',

PlotlyDict='plotlydict',

PlotlyTrace='plotlytrace',

Area='area',

Bar='bar',

Box='box',

Contour='contour',

Heatmap='heatmap',

Histogram='histogram',

Histogram2d='histogram2d',

Histogram2dContour='histogram2dcontour',

Scatter='scatter',

Annotation='annotation',

ColorBar='colorbar',

Contours='contours',

ErrorX='error_x',

ErrorY='error_y',

Figure='figure',

Font='font',

Layout='layout',

Legend='legend',

Line='line',

Margin='margin',

Marker='marker',

RadialAxis='radialaxis',

Stream='stream',

Trace='trace',

XAxis='xaxis',

XBins='xbins',

YAxis='yaxis',

YBins='ybins'

"""A meta class for PlotlyList class creation.

def __new__(mcs, name, bases, attrs):

doc = attrs['__doc__']

tab_size = 4

min_indent = min([len(a) - len(b)

for a, b in zip(doc.splitlines(),

[l.lstrip()

for l in doc.splitlines()])])

doc = "".join([line[min_indent:] + '\n' for line in doc.splitlines()])

# Add section header for method list...

doc += "Quick method reference:\n\n"

doc += "\t{}.".format(name) + "\n\t{}.".format(name).join(

["update(changes)", "strip_style()", "get_data()",

"to_graph_objs()", "validate()", "to_string()",

"force_clean()"]) + "\n\n"

attrs['__doc__'] = doc.expandtabs(tab_size)

"""A meta class for PlotlyDict class creation.

def __new__(mcs, name, bases, attrs):

obj_key = NAME_TO_KEY[name]

# remove min indentation...

doc = attrs['__doc__']

obj_info = INFO[obj_key]

line_size = 76

tab_size = 4

min_indent = min([len(a) - len(b)

for a, b in zip(doc.splitlines(),

[l.lstrip()

for l in doc.splitlines()])])

doc = "".join([line[min_indent:] + '\n' for line in doc.splitlines()])

# Add section header for method list...

doc += "Quick method reference:\n\n"

doc += "\t{}.".format(name) + "\n\t{}.".format(name).join(

["update(changes)", "strip_style()", "get_data()",

"to_graph_objs()", "validate()", "to_string()",

"force_clean()"]) + "\n\n"

# Add section header

if len(obj_info):

doc += "Valid keys:\n\n"

# Add each key one-by-one and format

width1 = line_size-tab_size

width2 = line_size-2*tab_size

width3 = line_size-3*tab_size

undocumented = "Aw, snap! Undocumented!"

for key in obj_info:

# main portion of documentation

try:

required = str(obj_info[key]['required'])

except KeyError:

required = undocumented

try:

typ = str(obj_info[key]['type'])

except KeyError:

typ = undocumented

try:

val_types = str(obj_info[key]['val_types'])

if typ == 'object':

val_types = "{} object | ".format(KEY_TO_NAME[key]) + \

val_types

except KeyError:

val_types = undocumented

try:

descr = str(obj_info[key]['description'])

except KeyError:

descr = undocumented

str_1 = "{} [required={}] (value={})".format(

key, required, val_types)

if "streamable" in obj_info[key] and obj_info[key]["streamable"]:

str_1 += " (streamable)"

str_1 += ":\n"

str_1 = "\t" + "\n\t".join(textwrap.wrap(str_1,

width=width1)) + "\n"

str_2 = "\t\t" + "\n\t\t".join(textwrap.wrap(descr,

width=width2)) + "\n"

doc += str_1 + str_2

# if a user can run help on this value, tell them!

if typ == "object":

doc += "\n\t\tFor more, run `help(plotly.graph_objs.{" \

"})`\n".format(KEY_TO_NAME[key])

# if example usage exists, tell them!

if 'examples' in obj_info[key]:

ex = "\n\t\tExamples:\n" + "\t\t\t"

ex += "\n\t\t\t".join(

textwrap.wrap(str(obj_info[key]['examples']),

width=width3)) + "\n"

doc += ex

if 'code' in obj_info[key]:

code = "\n\t\tCode snippet:"

code += "\n\t\t\t>>>".join(

str(obj_info[key]['code']).split('>>>')) + "\n"

doc += code

doc += '\n'

attrs['__doc__'] = doc.expandtabs(tab_size)

"""A container for PlotlyDicts, inherits from standard list.

__metaclass__ = ListMeta

def __init__(self, *args):

super(PlotlyList, self).__init__(*args)

if args and isinstance(args[0], dict):

raise exceptions.PlotlyListEntryError(

obj=self,

index=0,

notes="Just like a `list`, `{name}` must be instantiated with "

"a *single* collection.\n"

"In other words these are OK:\n"

">>> {name}()\n"

">>> {name}([])\n"

">>> {name}([dict()])\n"

">>> {name}([dict(), dict()])\n"

"However, these don't make sense:\n"

">>> {name}(dict())\n"

">>> {name}(dict(), dict())"

"".format(name=self.__class__.__name__)

)

self.validate()

if self.__class__.__name__ == 'PlotlyList':

warnings.warn("\nThe PlotlyList class is a base class of "

"list-like graph_objs.\nIt is not meant to be a "

"user interface.")

def to_graph_objs(self, caller=True):

"""Change any nested collections to subclasses of PlotlyDict/List.

for index, entry in enumerate(self):

if isinstance(entry, PlotlyDict):

try:

entry.to_graph_objs(caller=False)

except (exceptions.PlotlyGraphObjectError) as err:

err.add_to_error_path(index)

err.prepare()

raise # re-raise current exception

else:

raise exceptions.PlotlyListEntryError(obj=self,

index=index,

entry=entry)

def update(self, changes):

"""Update current list with changed_list, which must be iterable.

if isinstance(changes, dict):

changes = [changes]

self.to_graph_objs()

for index in range(len(self)):

try:

self[index].update(changes[index % len(changes)])

except ZeroDivisionError:

pass

def strip_style(self):

"""Strip style from the current representation.

self.to_graph_objs()

for plotly_dict in self:

plotly_dict.strip_style()

def get_data(self):

"""Returns the JSON for the plot with non-data elements stripped."""

self.to_graph_objs()

l = list()

for _plotlydict in self:

l += [_plotlydict.get_data()]

del_indicies = [index for index, item in enumerate(self)

if len(item) == 0]

del_ct = 0

for index in del_indicies:

del self[index - del_ct]

del_ct += 1

return l

def validate(self, caller=True):

"""Recursively check the validity of the entries in a PlotlyList.

if caller: # change everything to PlotlyList/Dict objects

try:

self.to_graph_objs()

except exceptions.PlotlyGraphObjectError as err:

err.prepare()

raise

for index, entry in enumerate(self):

if isinstance(entry, PlotlyDict):

try:

entry.validate(caller=False)

except exceptions.PlotlyGraphObjectError as err:

err.add_to_error_path(index)

err.prepare()

raise

else:

raise exceptions.PlotlyGraphObjectError( # TODO!!!

message="uh-oh, this error shouldn't have happenend.",

plain_message="uh-oh, this error shouldn't have happenend.",

path=[index],

)

def to_string(self, level=0, indent=4, eol='\n', pretty=True, max_chars=80):

"""Returns a formatted string showing graph_obj constructors.

self.to_graph_objs()

if not len(self):

return "{name}()".format(name=self.__class__.__name__)

string = "{name}([{eol}{indent}".format(

name=self.__class__.__name__,

eol=eol,

indent=' ' * indent * (level + 1))

for index, entry in enumerate(self):

string += entry.to_string(level=level+1,

indent=indent,

eol=eol,

pretty=pretty,

max_chars=max_chars)

if index < len(self) - 1:

string += ",{eol}{indent}".format(

eol=eol,

indent=' ' * indent * (level + 1))

string += "{eol}{indent}])".format(eol=eol, indent=' ' * indent * level)

return string

def get_ordered(self, caller=True):

if caller:

try:

self.to_graph_objs(caller=False)

except exceptions.PlotlyGraphObjectError as err:

err.add_note("Could not order list because it could not be "

"converted to a valid graph object.")

err.prepare()

raise

ordered_list = []

for index, entry in enumerate(self):

ordered_list += [entry.get_ordered()]

return ordered_list

def force_clean(self, caller=True):

"""Attempts to convert to graph_objs and calls force_clean() on entries.

if caller:

self.to_graph_objs() # TODO add error handling here!

for entry in self:

entry.force_clean(caller=False)

del_indicies = [index for index, item in enumerate(self)

if len(item) == 0]

del_ct = 0

for index in del_indicies:

del self[index - del_ct]

"""A base dict class for all objects that style a figure in plotly.

__metaclass__ = DictMeta

def __init__(self, *args, **kwargs):

class_name = self.__class__.__name__

super(PlotlyDict, self).__init__(*args, **kwargs)

if issubclass(NAME_TO_CLASS[class_name], PlotlyTrace):

if (class_name != 'PlotlyTrace') and (class_name != 'Trace'):

self['type'] = NAME_TO_KEY[class_name]

self.validate()

if self.__class__.__name__ == 'PlotlyDict':

warnings.warn("\nThe PlotlyDict class is a base class of "

"dictionary-like graph_objs.\nIt is not meant to be "

"a user interface.")

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

"""Update current dict with dict1 and then dict2.

self.to_graph_objs()

if dict1 is not None:

for key, val in dict1.items():

if key in self:

if isinstance(self[key], (PlotlyDict, PlotlyList)):

self[key].update(val)

else:

self[key] = val

else:

self[key] = val

if len(dict2):

for key, val in dict2.items():

if key in self:

if isinstance(self[key], (PlotlyDict, PlotlyList)):

self[key].update(val)

else:

self[key] = val

else:

self[key] = val

self.to_graph_objs()

def strip_style(self):

"""Strip style from the current representation.

self.to_graph_objs()

obj_key = NAME_TO_KEY[self.__class__.__name__]

keys = self.keys()

for key in keys:

if isinstance(self[key], (PlotlyDict, PlotlyList)):

self[key].strip_style()

else:

try:

if INFO[obj_key][key]['type'] == 'style':

if not hasattr(self[key], '__iter__'):

del self[key]

except KeyError: # TODO: Update the JSON

# print "'type' not in {} for {}".format(obj_key, key)

pass

def get_data(self):

"""Returns the JSON for the plot with non-data elements stripped."""

self.to_graph_objs()

class_name = self.__class__.__name__

obj_key = NAME_TO_KEY[class_name]

d = dict()

for key, val in self.items():

if isinstance(val, (PlotlyDict, PlotlyList)):

d[key] = val.get_data()

else:

try:

if INFO[obj_key][key]['type'] == 'data': # TODO: Update the JSON

d[key] = val

except KeyError:

pass

keys = d.keys()

for key in keys:

if isinstance(d[key], (dict, list)):

if len(d[key]) == 0:

del d[key]

if len(d) == 1:

d = d.values()[0]

return d

def to_graph_objs(self, caller=True):

"""Walk obj, convert dicts and lists to plotly graph objs.

info_key = NAME_TO_KEY[self.__class__.__name__]

keys = self.keys()

for key in keys:

if isinstance(self[key], (PlotlyDict, PlotlyList)):

try:

self[key].to_graph_objs(caller=False)

except exceptions.PlotlyGraphObjectError as err:

err.add_to_error_path(key)

err.prepare()

raise

elif key in INFO[info_key] and 'type' in INFO[info_key][key]:

if INFO[info_key][key]['type'] == 'object':

class_name = KEY_TO_NAME[key]

obj = NAME_TO_CLASS[class_name]() # gets constructor

if isinstance(obj, PlotlyDict):

if not isinstance(self[key], dict):

try:

val_types = INFO[info_key][key]['val_types']

except KeyError:

val_types = 'undocumented'

raise exceptions.PlotlyDictValueError(

obj=self,

key=key,

value=self[key],

val_types=val_types,

notes="value needs to be dictionary-like"

)

for k, v in self.pop(key).items():

obj[k] = v # finish up momentarily...

else: # if not PlotlyDict, it MUST be a PlotlyList

if not isinstance(self[key], list):

try:

val_types = INFO[info_key][key]['val_types']

except KeyError:

val_types = 'undocumented'

raise exceptions.PlotlyDictValueError( # TODO!!!

obj=self,

key=key,

value=self[key],

val_types=val_types,

notes="value needs to be list-like"

)

obj += self.pop(key)

try:

obj.to_graph_objs(caller=False)

except exceptions.PlotlyGraphObjectError as err:

err.add_to_error_path(key)

err.prepare()

raise

self[key] = obj # whew! made it!

def validate(self, caller=True): # TODO: validate values too?

"""Recursively check the validity of the keys in a PlotlyDict.

if caller: # change everything to 'checkable' objs

try:

self.to_graph_objs(caller=False)

except exceptions.PlotlyGraphObjectError as err:

err.prepare()

raise

obj_key = NAME_TO_KEY[self.__class__.__name__]

for key, val in self.items():

if isinstance(val, (PlotlyDict, PlotlyList)):

try:

val.validate(caller=False)

except exceptions.PlotlyGraphObjectError as err:

err.add_to_error_path(key)

err.prepare()

raise

else:

if key in INFO[obj_key]:

if 'type' not in INFO[obj_key][key]:

continue # TODO: 'type' may not be documented yet!

if INFO[obj_key][key]['type'] == 'object':

try:

val_types = INFO[obj_key][key]['val_types']

except KeyError:

val_types = 'undocumented'

raise exceptions.PlotlyDictValueError(

obj=self,

key=key,

value=val,

val_types=val_types

)

else:

matching_objects = [obj for obj in INFO if key in INFO[obj]]

notes = ''

if len(matching_objects):

notes += "That key is valid only in these objects:\n\n"

for obj in matching_objects:

notes += "\t{}".format(KEY_TO_NAME[obj])

try:

notes += '({}="{}")\n'.format(

repr(key), INFO[obj][key]['val_types'])

except KeyError:

notes += '({}="..")\n'.format(repr(key))

notes.expandtabs()

else:

notes += ("Couldn't find uses for key: {}\n\n"

"".format(repr(key)))

raise exceptions.PlotlyDictKeyError(obj=self,

key=key,

notes=notes)

def to_string(self, level=0, indent=4, eol='\n', pretty=True, max_chars=80):

"""Returns a formatted string showing graph_obj constructors.

self.to_graph_objs() # todo, consider catching and re-raising?

if not len(self):

return "{name}()".format(name=self.__class__.__name__)

string = "{name}(".format(name=self.__class__.__name__)

index = 0

obj_key = NAME_TO_KEY[self.__class__.__name__]

for key in INFO[obj_key]: # this sets the order of the keys! nice.

if key in self:

string += "{eol}{indent}{key}=".format(

eol=eol,

indent=' ' * indent * (level+1),

key=key)

try:

string += self[key].to_string(level=level+1,

indent=indent,

eol=eol,

pretty=pretty,

max_chars=max_chars)

except AttributeError:

val = repr(self[key])

val_chars = max_chars - (indent*(level+1)) - (len(key)+1)

if pretty and (len(val) > val_chars):

string += val[:val_chars - 5] + '...' + val[-1]

else:

string += val

if index < len(self) - 1:

string += ","

index += 1

if index == len(self):

break

string += "{eol}{indent})".format(eol=eol, indent=' ' * indent * level)

return string

def get_ordered(self, caller=True):

if caller: # change everything to 'order-able' objs

try:

self.to_graph_objs(caller=False)

except exceptions.PlotlyGraphObjectError as err:

err.add_note("dictionary could not be ordered because it "

"could not be converted to a valid plotly graph "

"object.")

err.prepare()

raise

obj_type = NAME_TO_KEY[self.__class__.__name__]

ordered_dict = collections.OrderedDict()

# grab keys like xaxis1, xaxis2, etc...

unordered_keys = [key for key in self if key not in INFO[obj_type]]

for key in INFO[obj_type]:

if key in self:

if isinstance(self[key], (PlotlyDict, PlotlyList)):

ordered_dict[key] = self[key].get_ordered(caller=False)

else:

ordered_dict[key] = self[key]

for key in unordered_keys:

if isinstance(self[key], (PlotlyDict, PlotlyList)):

ordered_dict[key] = self[key].get_ordered(caller=False)

else:

ordered_dict[key] = self[key]

return ordered_dict

def force_clean(self, caller=True):

"""Attempts to convert to graph_objs and call force_clean() on values.

obj_key = NAME_TO_KEY[self.__class__.__name__]

if caller:

self.to_graph_objs(caller=False)

del_keys = [key for key in self if str(key) not in INFO[obj_key]]

for key in del_keys:

del self[key]

keys = self.keys()

for key in keys:

try:

self[key].force_clean(caller=False) # TODO: add error handling

except AttributeError:

pass

if isinstance(self[key], (dict, list)):

if len(self[key]) == 0:

del self[key] # clears empty collections!

elif self[key] is None:

"""A list of traces to be shown on a plot/graph.

def to_graph_objs(self, caller=True): # TODO TODO TODO! check logic!

"""Change any nested collections to subclasses of PlotlyDict/List.

for index, entry in enumerate(self):

if isinstance(entry, PlotlyDict):

self[index] = NAME_TO_CLASS[entry.__class__.__name__](entry)

elif isinstance(entry, dict):

if 'type' not in entry: # assume 'scatter' if not given

entry['type'] = 'scatter'

try:

obj_name = KEY_TO_NAME[entry['type']]

except KeyError:

raise exceptions.PlotlyDataTypeError(

obj=self,

index=index

)

obj = NAME_TO_CLASS[obj_name]() # don't hide if KeyError!

for k, v in entry.items():

obj[k] = v

self[index] = obj

if not isinstance(self[index], PlotlyTrace): # Trace ONLY!!!

raise exceptions.PlotlyListEntryError(

obj=self,

index=index,

notes="The entry could not be converted into a PlotlyTrace "

"object (e.g., Scatter, Heatmap, Bar, etc).",

)

"""A list-like object to contain all figure notes.

def to_graph_objs(self, caller=True):

"""Change any nested collections to subclasses of PlotlyDict/List.

for index, entry in enumerate(self):

if isinstance(entry, (PlotlyDict, PlotlyList)):

if not isinstance(entry, Annotation):

raise exceptions.PlotlyListEntryError(

obj=self,

index=index,

notes="The entry could not be converted into an "

"Annotation object because it was already a "

"different kind of graph object.",

)

elif isinstance(entry, dict):

obj = Annotation()

for k, v in entry.items():

obj[k] = v

self[index] = obj

else:

raise exceptions.PlotlyListEntryError(

obj=self,

index=index,

notes="The entry could not be converted into an Annotation "

"object because it was not a dictionary.",

)

"""A general data class for plotly.

def __init__(self, *args, **kwargs):

super(PlotlyTrace, self).__init__(*args, **kwargs)

if self.__class__.__name__ == 'PlotlyTrace':

warnings.warn("\nThe PlotlyTrace class is a base class of "

"dictionary-like plot types.\nIt is not meant to be "

"a user interface.")

def to_string(self, level=0, indent=4, eol='\n', pretty=True, max_chars=80):

"""Returns a formatted string showing graph_obj constructors.

self.to_graph_objs()

if self.__class__.__name__ != "Trace":

trace_type = self.pop('type')

string = super(PlotlyTrace, self).to_string(level=level,

indent=indent,

eol=eol,

pretty=pretty,

max_chars=max_chars)

self['type'] = trace_type

else: