import textwrap import pkgutil import copy import os import json from functools import reduce try: from math import gcd except ImportError: # Python 2 from fractions import gcd # Create Lazy sentinal object to indicate that a template should be loaded # on-demand from package_data Lazy = object() # Templates configuration class # ----------------------------- class TemplatesConfig(object): """ Singleton object containing the current figure templates (aka themes) """ def __init__(self): # Initialize properties dict self._templates = {} # Initialize built-in templates default_templates = [ "ggplot2", "seaborn", "simple_white", "plotly", "plotly_white", "plotly_dark", "presentation", "xgridoff", "ygridoff", "gridon", "none", ] for template_name in default_templates: self._templates[template_name] = Lazy self._validator = None self._default = None # ### Magic methods ### # Make this act as a dict of templates def __len__(self): return len(self._templates) def __contains__(self, item): return item in self._templates def __iter__(self): return iter(self._templates) def __getitem__(self, item): if isinstance(item, str): template_names = item.split("+") else: template_names = [item] templates = [] for template_name in template_names: template = self._templates[template_name] if template is Lazy: from plotly.graph_objs.layout import Template if template_name == "none": # "none" is a special built-in named template that applied no defaults template = Template(data_scatter=[{}]) self._templates[template_name] = template else: # Load template from package data path = os.path.join( "package_data", "templates", template_name + ".json" ) template_str = pkgutil.get_data("plotly", path).decode("utf-8") template_dict = json.loads(template_str) template = Template(template_dict, _validate=False) self._templates[template_name] = template templates.append(self._templates[template_name]) return self.merge_templates(*templates) def __setitem__(self, key, value): self._templates[key] = self._validate(value) def __delitem__(self, key): # Remove template del self._templates[key] # Check if we need to remove it as the default if self._default == key: self._default = None def _validate(self, value): if not self._validator: from plotly.validators.layout import TemplateValidator self._validator = TemplateValidator() return self._validator.validate_coerce(value) def keys(self): return self._templates.keys() def items(self): return self._templates.items() def update(self, d={}, **kwargs): """ Update one or more templates from a dict or from input keyword arguments. Parameters ---------- d: dict Dictionary from template names to new template values. kwargs Named argument value pairs where the name is a template name and the value is a new template value. """ for k, v in dict(d, **kwargs).items(): self[k] = v # ### Properties ### @property def default(self): """ The name of the default template, or None if no there is no default If not None, the default template is automatically applied to all figures during figure construction if no explicit template is specified. The names of available templates may be retrieved with: >>> import plotly.io as pio >>> list(pio.templates) Returns ------- str """ return self._default @default.setter def default(self, value): # Validate value # Could be a Template object, the key of a registered template, # Or a string containing the names of multiple templates joined on # '+' characters self._validate(value) self._default = value def __repr__(self): return """\ Templates configuration ----------------------- Default template: {default} Available templates: {available} """.format( default=repr(self.default), available=self._available_templates_str() ) def _available_templates_str(self): """ Return nicely wrapped string representation of all available template names """ available = "\n".join( textwrap.wrap( repr(list(self)), width=79 - 8, initial_indent=" " * 8, subsequent_indent=" " * 9, ) ) return available def merge_templates(self, *args): """ Merge a collection of templates into a single combined template. Templates are process from left to right so if multiple templates specify the same propery, the right-most template will take precedence. Parameters ---------- args: list of Template Zero or more template objects (or dicts with compatible properties) Returns ------- template: A combined template object Examples -------- >>> pio.templates.merge_templates( ... go.layout.Template(layout={'font': {'size': 20}}), ... go.layout.Template(data={'scatter': [{'mode': 'markers'}]}), ... go.layout.Template(layout={'font': {'family': 'Courier'}})) layout.Template({ 'data': {'scatter': [{'mode': 'markers', 'type': 'scatter'}]}, 'layout': {'font': {'family': 'Courier', 'size': 20}} }) """ if args: return reduce(self._merge_2_templates, args) else: from plotly.graph_objs.layout import Template return Template() def _merge_2_templates(self, template1, template2): """ Helper function for merge_templates that merges exactly two templates Parameters ---------- template1: Template template2: Template Returns ------- Template: merged template """ # Validate/copy input templates result = self._validate(template1) other = self._validate(template2) # Cycle traces for trace_type in result.data: result_traces = result.data[trace_type] other_traces = other.data[trace_type] if result_traces and other_traces: lcm = ( len(result_traces) * len(other_traces) // gcd(len(result_traces), len(other_traces)) ) # Cycle result traces result.data[trace_type] = result_traces * (lcm // len(result_traces)) # Cycle other traces other.data[trace_type] = other_traces * (lcm // len(other_traces)) # Perform update result.update(other) return result # Make config a singleton object # ------------------------------ templates = TemplatesConfig() del TemplatesConfig # Template utilities # ------------------ def walk_push_to_template(fig_obj, template_obj, skip): """ Move style properties from fig_obj to template_obj. Parameters ---------- fig_obj: plotly.basedatatypes.BasePlotlyType template_obj: plotly.basedatatypes.BasePlotlyType skip: set of str Set of names of properties to skip """ from _plotly_utils.basevalidators import ( CompoundValidator, CompoundArrayValidator, is_array, ) for prop in list(fig_obj._props): if prop == "template" or prop in skip: # Avoid infinite recursion continue fig_val = fig_obj[prop] template_val = template_obj[prop] validator = fig_obj._get_validator(prop) if isinstance(validator, CompoundValidator): walk_push_to_template(fig_val, template_val, skip) if not fig_val._props: # Check if we can remove prop itself fig_obj[prop] = None elif isinstance(validator, CompoundArrayValidator) and fig_val: template_elements = list(template_val) template_element_names = [el.name for el in template_elements] template_propdefaults = template_obj[prop[:-1] + "defaults"] for fig_el in fig_val: element_name = fig_el.name if element_name: # No properties are skipped inside a named array element skip = set() if fig_el.name in template_element_names: item_index = template_element_names.index(fig_el.name) template_el = template_elements[item_index] walk_push_to_template(fig_el, template_el, skip) else: template_el = fig_el.__class__() walk_push_to_template(fig_el, template_el, skip) template_elements.append(template_el) template_element_names.append(fig_el.name) # Restore element name # since it was pushed to template above fig_el.name = element_name else: walk_push_to_template(fig_el, template_propdefaults, skip) template_obj[prop] = template_elements elif not validator.array_ok or not is_array(fig_val): # Move property value from figure to template template_obj[prop] = fig_val try: fig_obj[prop] = None except ValueError: # Property cannot be set to None, move on. pass def to_templated(fig, skip=("title", "text")): """ Return a copy of a figure where all styling properties have been moved into the figure's template. The template property of the resulting figure may then be used to set the default styling of other figures. Parameters ---------- fig Figure object or dict representing a figure skip A collection of names of properties to skip when moving properties to the template. Defaults to ('title', 'text') so that the text of figure titles, axis titles, and annotations does not become part of the template Examples -------- Imports >>> import plotly.graph_objs as go >>> import plotly.io as pio Construct a figure with large courier text >>> fig = go.Figure(layout={'title': 'Figure Title', ... 'font': {'size': 20, 'family': 'Courier'}, ... 'template':"none"}) >>> fig # doctest: +NORMALIZE_WHITESPACE Figure({ 'data': [], 'layout': {'font': {'family': 'Courier', 'size': 20}, 'template': '...', 'title': {'text': 'Figure Title'}} }) Convert to a figure with a template. Note how the 'font' properties have been moved into the template property. >>> templated_fig = pio.to_templated(fig) >>> templated_fig.layout.template layout.Template({ 'layout': {'font': {'family': 'Courier', 'size': 20}} }) >>> templated_fig Figure({ 'data': [], 'layout': {'template': '...', 'title': {'text': 'Figure Title'}} }) Next create a new figure with this template >>> fig2 = go.Figure(layout={ ... 'title': 'Figure 2 Title', ... 'template': templated_fig.layout.template}) >>> fig2.layout.template layout.Template({ 'layout': {'font': {'family': 'Courier', 'size': 20}} }) The default font in fig2 will now be size 20 Courier. Next, register as a named template... >>> pio.templates['large_courier'] = templated_fig.layout.template and specify this template by name when constructing a figure. >>> go.Figure(layout={ ... 'title': 'Figure 3 Title', ... 'template': 'large_courier'}) # doctest: +ELLIPSIS Figure(...) Finally, set this as the default template to be applied to all new figures >>> pio.templates.default = 'large_courier' >>> fig = go.Figure(layout={'title': 'Figure 4 Title'}) >>> fig.layout.template layout.Template({ 'layout': {'font': {'family': 'Courier', 'size': 20}} }) Returns ------- go.Figure """ # process fig from plotly.basedatatypes import BaseFigure from plotly.graph_objs import Figure if not isinstance(fig, BaseFigure): fig = Figure(fig) # Process skip if not skip: skip = set() else: skip = set(skip) # Always skip uids skip.add("uid") # Initialize templated figure with deep copy of input figure templated_fig = copy.deepcopy(fig) # Handle layout walk_push_to_template( templated_fig.layout, templated_fig.layout.template.layout, skip=skip ) # Handle traces trace_type_indexes = {} for trace in list(templated_fig.data): template_index = trace_type_indexes.get(trace.type, 0) # Extend template traces if necessary template_traces = list(templated_fig.layout.template.data[trace.type]) while len(template_traces) <= template_index: # Append empty trace template_traces.append(trace.__class__()) # Get corresponding template trace template_trace = template_traces[template_index] # Perform push properties to template walk_push_to_template(trace, template_trace, skip=skip) # Update template traces in templated_fig templated_fig.layout.template.data[trace.type] = template_traces # Update trace_type_indexes trace_type_indexes[trace.type] = template_index + 1 # Remove useless trace arrays any_non_empty = False for trace_type in templated_fig.layout.template.data: traces = templated_fig.layout.template.data[trace_type] is_empty = [trace.to_plotly_json() == {"type": trace_type} for trace in traces] if all(is_empty): templated_fig.layout.template.data[trace_type] = None else: any_non_empty = True # Check if we can remove the data altogether key if not any_non_empty: templated_fig.layout.template.data = None return templated_fig