Skip to content

Commit e426808

Browse files
jonmmeasejonmmease
committed
Added codegen docstrings for layout.template and the elementdefaults properties
1 parent afaaec8 commit e426808

File tree

123 files changed

+1277
-483
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

123 files changed

+1277
-483
lines changed

‎codegen/__init__.py‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,26 @@ def preprocess_schema(plotly_schema):
4646
for trace in plotly_schema['traces']
4747
},
4848
"layout": {
49-
}
49+
},
50+
"description": """\
51+
Default attributes to be applied to the plot.
52+
This should be a dict with format: `{'layout': layoutTemplate, 'data':
53+
{trace_type: [traceTemplate, ...], ...}}` where `layoutTemplate` is a dict
54+
matching the structure of `figure.layout` and `traceTemplate` is a dict
55+
matching the structure of the trace with type `trace_type` (e.g. 'scatter').
56+
Alternatively, this may be specified as an instance of
57+
plotly.graph_objs.layout.Template.
58+
59+
Trace templates are applied cyclically to
60+
traces of each type. Container arrays (eg `annotations`) have special
61+
handling: An object ending in `defaults` (eg `annotationdefaults`) is
62+
applied to each array item. But if an item has a `templateitemname`
63+
key we look in the template array for an item with matching `name` and
64+
apply that instead. If no matching `name` is found we mark the item
65+
invisible. Any named template item not referenced is appended to the
66+
end of the array, so this can be used to add a watermark annotation or a
67+
logo image, for example. To omit one of these items on the plot, make
68+
an item with matching `templateitemname` and `visible: false`."""
5069
}
5170

5271
layout['template'] = template

‎codegen/utils.py‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1120,6 +1120,9 @@ class ElementDefaultsNode(PlotlyNode):
11201120

11211121
def __init__(self, array_node, plotly_schema):
11221122
"""
1123+
Create node that represents element defaults properties
1124+
(e.g. layout.annotationdefaults). Construct as a wrapper around the
1125+
corresponding array property node (e.g. layout.annotations)
11231126
11241127
Parameters
11251128
----------
@@ -1139,7 +1142,23 @@ def node_data(self):
11391142

11401143
@property
11411144
def description(self):
1142-
return ''
1145+
array_property_path = (self.parent_path_str +
1146+
'.' + self.array_node.name_property)
1147+
1148+
if isinstance(self.array_node, TraceNode):
1149+
data_path = 'data.'
1150+
else:
1151+
data_path = ''
1152+
1153+
defaults_property_path = ('layout.template.' +
1154+
data_path +
1155+
self.parent_path_str +
1156+
'.' + self.plotly_name)
1157+
return f"""\
1158+
When used in a template
1159+
(as {defaults_property_path}),
1160+
sets the default property values to use for elements
1161+
of {array_property_path}"""
11431162

11441163
@property
11451164
def name_base_datatype(self):
@@ -1155,11 +1174,4 @@ def plotly_name(self):
11551174

11561175
@property
11571176
def name_datatype_class(self):
1158-
"""
1159-
Name of the Python datatype class representing this node
1160-
1161-
Returns
1162-
-------
1163-
str
1164-
"""
11651177
return self.element_node.name_datatype_class

‎plotly/graph_objs/_carpet.py‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -226,8 +226,10 @@ def aaxis(self):
226226
plotly.graph_objs.carpet.aaxis.Tickformatstop
227227
instance or dict with compatible properties
228228
tickformatstopdefaults
229-
plotly.graph_objs.carpet.aaxis.Tickformatstop
230-
instance or dict with compatible properties
229+
When used in a template (as layout.template.dat
230+
a.carpet.aaxis.tickformatstopdefaults), sets
231+
the default property values to use for elements
232+
of carpet.aaxis.tickformatstops
231233
tickmode
232234
233235
tickprefix
@@ -514,8 +516,10 @@ def baxis(self):
514516
plotly.graph_objs.carpet.baxis.Tickformatstop
515517
instance or dict with compatible properties
516518
tickformatstopdefaults
517-
plotly.graph_objs.carpet.baxis.Tickformatstop
518-
instance or dict with compatible properties
519+
When used in a template (as layout.template.dat
520+
a.carpet.baxis.tickformatstopdefaults), sets
521+
the default property values to use for elements
522+
of carpet.baxis.tickformatstops
519523
tickmode
520524
521525
tickprefix

‎plotly/graph_objs/_choropleth.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -171,9 +171,10 @@ def colorbar(self):
171171
tstop instance or dict with compatible
172172
properties
173173
tickformatstopdefaults
174-
plotly.graph_objs.choropleth.colorbar.Tickforma
175-
tstop instance or dict with compatible
176-
properties
174+
When used in a template (as layout.template.dat
175+
a.choropleth.colorbar.tickformatstopdefaults),
176+
sets the default property values to use for
177+
elements of choropleth.colorbar.tickformatstops
177178
ticklen
178179
Sets the tick length (in px).
179180
tickmode

‎plotly/graph_objs/_cone.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -260,8 +260,10 @@ def colorbar(self):
260260
plotly.graph_objs.cone.colorbar.Tickformatstop
261261
instance or dict with compatible properties
262262
tickformatstopdefaults
263-
plotly.graph_objs.cone.colorbar.Tickformatstop
264-
instance or dict with compatible properties
263+
When used in a template (as layout.template.dat
264+
a.cone.colorbar.tickformatstopdefaults), sets
265+
the default property values to use for elements
266+
of cone.colorbar.tickformatstops
265267
ticklen
266268
Sets the tick length (in px).
267269
tickmode

‎plotly/graph_objs/_contour.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -193,8 +193,10 @@ def colorbar(self):
193193
plotly.graph_objs.contour.colorbar.Tickformatst
194194
op instance or dict with compatible properties
195195
tickformatstopdefaults
196-
plotly.graph_objs.contour.colorbar.Tickformatst
197-
op instance or dict with compatible properties
196+
When used in a template (as layout.template.dat
197+
a.contour.colorbar.tickformatstopdefaults),
198+
sets the default property values to use for
199+
elements of contour.colorbar.tickformatstops
198200
ticklen
199201
Sets the tick length (in px).
200202
tickmode

‎plotly/graph_objs/_contourcarpet.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -386,9 +386,11 @@ def colorbar(self):
386386
rmatstop instance or dict with compatible
387387
properties
388388
tickformatstopdefaults
389-
plotly.graph_objs.contourcarpet.colorbar.Tickfo
390-
rmatstop instance or dict with compatible
391-
properties
389+
When used in a template (as layout.template.dat
390+
a.contourcarpet.colorbar.tickformatstopdefaults
391+
), sets the default property values to use for
392+
elements of
393+
contourcarpet.colorbar.tickformatstops
392394
ticklen
393395
Sets the tick length (in px).
394396
tickmode

‎plotly/graph_objs/_figure.py‎

Lines changed: 54 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,10 @@ def __init__(
5959
plotly.graph_objs.layout.Annotation instance or
6060
dict with compatible properties
6161
annotationdefaults
62-
plotly.graph_objs.layout.Annotation instance or
63-
dict with compatible properties
62+
When used in a template (as
63+
layout.template.layout.annotationdefaults),
64+
sets the default property values to use for
65+
elements of layout.annotations
6466
autosize
6567
Determines whether or not a layout width or
6668
height that has been left undefined by the user
@@ -212,8 +214,10 @@ def __init__(
212214
plotly.graph_objs.layout.Image instance or dict
213215
with compatible properties
214216
imagedefaults
215-
plotly.graph_objs.layout.Image instance or dict
216-
with compatible properties
217+
When used in a template (as
218+
layout.template.layout.imagedefaults), sets the
219+
default property values to use for elements of
220+
layout.images
217221
legend
218222
plotly.graph_objs.layout.Legend instance or
219223
dict with compatible properties
@@ -265,8 +269,10 @@ def __init__(
265269
plotly.graph_objs.layout.Shape instance or dict
266270
with compatible properties
267271
shapedefaults
268-
plotly.graph_objs.layout.Shape instance or dict
269-
with compatible properties
272+
When used in a template (as
273+
layout.template.layout.shapedefaults), sets the
274+
default property values to use for elements of
275+
layout.shapes
270276
showlegend
271277
Determines whether or not a legend is drawn.
272278
Default is `true` if there is a trace to show
@@ -278,8 +284,10 @@ def __init__(
278284
plotly.graph_objs.layout.Slider instance or
279285
dict with compatible properties
280286
sliderdefaults
281-
plotly.graph_objs.layout.Slider instance or
282-
dict with compatible properties
287+
When used in a template (as
288+
layout.template.layout.sliderdefaults), sets
289+
the default property values to use for elements
290+
of layout.sliders
283291
spikedistance
284292
Sets the default distance (in pixels) to look
285293
for data to draw spikelines to (-1 means no
@@ -289,8 +297,32 @@ def __init__(
289297
hovered on but will not generate spikelines,
290298
such as scatter fills.
291299
template
292-
plotly.graph_objs.layout.Template instance or
293-
dict with compatible properties
300+
Default attributes to be applied to the plot.
301+
This should be a dict with format: `{'layout':
302+
layoutTemplate, 'data': {trace_type:
303+
[traceTemplate, ...], ...}}` where
304+
`layoutTemplate` is a dict matching the
305+
structure of `figure.layout` and
306+
`traceTemplate` is a dict matching the
307+
structure of the trace with type `trace_type`
308+
(e.g. 'scatter'). Alternatively, this may be
309+
specified as an instance of
310+
plotly.graph_objs.layout.Template. Trace
311+
templates are applied cyclically to traces of
312+
each type. Container arrays (eg `annotations`)
313+
have special handling: An object ending in
314+
`defaults` (eg `annotationdefaults`) is applied
315+
to each array item. But if an item has a
316+
`templateitemname` key we look in the template
317+
array for an item with matching `name` and
318+
apply that instead. If no matching `name` is
319+
found we mark the item invisible. Any named
320+
template item not referenced is appended to the
321+
end of the array, so this can be used to add a
322+
watermark annotation or a logo image, for
323+
example. To omit one of these items on the
324+
plot, make an item with matching
325+
`templateitemname` and `visible: false`.
294326
ternary
295327
plotly.graph_objs.layout.Ternary instance or
296328
dict with compatible properties
@@ -302,8 +334,10 @@ def __init__(
302334
plotly.graph_objs.layout.Updatemenu instance or
303335
dict with compatible properties
304336
updatemenudefaults
305-
plotly.graph_objs.layout.Updatemenu instance or
306-
dict with compatible properties
337+
When used in a template (as
338+
layout.template.layout.updatemenudefaults),
339+
sets the default property values to use for
340+
elements of layout.updatemenus
307341
violingap
308342
Sets the gap (in plot fraction) between violins
309343
of adjacent location coordinates.
@@ -4960,8 +4994,10 @@ def add_parcoords(
49604994
The dimensions (variables) of the parallel coordinates
49614995
chart. 2..60 dimensions are supported.
49624996
dimensiondefaults
4963-
plotly.graph_objs.parcoords.Dimension instance or dict
4964-
with compatible properties
4997+
When used in a template (as
4998+
layout.template.data.parcoords.dimensiondefaults), sets
4999+
the default property values to use for elements of
5000+
parcoords.dimensions
49655001
domain
49665002
plotly.graph_objs.parcoords.Domain instance or dict
49675003
with compatible properties
@@ -8186,8 +8222,10 @@ def add_splom(
81868222
plotly.graph_objs.splom.Dimension instance or dict with
81878223
compatible properties
81888224
dimensiondefaults
8189-
plotly.graph_objs.splom.Dimension instance or dict with
8190-
compatible properties
8225+
When used in a template (as
8226+
layout.template.data.splom.dimensiondefaults), sets the
8227+
default property values to use for elements of
8228+
splom.dimensions
81918229
hoverinfo
81928230
Determines which trace information appear on hover. If
81938231
`none` or `skip` are set, no information is displayed

0 commit comments

Comments
 (0)