easychart.Chart¶

class easychart.Chart(chart=None)¶

A Highchart chart configuration

annotate(text, *, x=0, y=0, xOffset=None, yOffset=None, point=None, align=None, verticalAlign=None, shape=None, padding=None, distance=None, backgroundColor=None, borderColor=None, borderRadius=None, borderWidth=None, useHTML=None, size=None, color=None, xAxis=0, yAxis=0, width=None, allowOverlap=True, draggable='xy', zIndex=None, visible=None)¶

Add an annotation to a chart

Parameters:

text (str) – The annotation label text
x (float) – The x position of the point to which the annotation refers to
y (float) – The y position of the point to which the annotation refers to
xAxis (int) – The x-Axis in which the x coordinate is defined
yAxis (int) – The y-Axis in which the y coordinate is defined
xOffset (float) – The horizontal offset of the annotation relative to the point (in pixels)
yOffset (float) – The vertical offset of the annotation relative to the point (in pixels)
width (int) – The width (in pixels) of the annotation
point (str) – The id of the point to which the annotation refers to (if x and y not specified)
align (str (one of "center", "left", "right")) – The horizontal alignment of the annotation relative to the point
verticalAlign (str (one of "bottom", "middle", "top")) – The vertical alignment of the annotation relative to the point
shape (str (one of "callout", "connector", "rect", "circle", "diamond", "triangle")) – The shape of the annotation
padding (int) – The padding within the box (assuming border or background is set)
distance (float) – The offset of the annotation relative to the point (in lieu of xOffset and yOffset)
size (int) – The font size
color (str) – The font color

Note

For more details on annotations, check out the Highcharts API documentation

property categories¶

Get or set the xAxis categories.

Categories are names used instead of number for categorical charts. Each category name is mapped to a number, with the first element assigned the value of 0.

Note

Alias for chart.xAxis.categories. See Highcharts API for additional details on the xAxis categories

Example:

>>> import easychart

>>> chart = easychart.new("column")
>>> chart.categories = ["France","UK"]
>>> chart.plot([10, 20])

Getter:

Return the xAxis categories (if any)

returns:: list

Setter:

Set the xAxis categories

accepts:: iterable

property datalabels¶

Get or set data labels options

Note

Alias for chart.plotOptions.series.dataLabels. See Highcharts API for additional details on data labels

Getter:

Return the datalabel options (if any)

returns:: dict

Setter:

Set the datalabel options

accepts:: bool, str, tuple, dict

Note

If given a bool, value is assigned to chart.plotOptions.series.dataLabels.enabled
If given a str, value is assigned to chart.plotOptions.series.dataLabels.format
If given a dict, value is assigned as is
If given a tuple, values are iteratively assigned as described above

property datetime¶

Get or set whether the xAxis is a datetime axis

Getter:

Returns whether the xAxis is a datetime axis

returns:: bool

Setter:

Sets whether the xAxis is a datetime axis

accepts:: bool

property decimals¶

Returns the number of tooltip decimals

Getter:

Return the number of tooltip decimals

returns:: int

Setter:

Set the number of tooltip decimals

accepts:: int

draw(shape, *, x=None, y=None, xAxis=0, yAxis=0, r=None, width=None, height=None, xOffset=None, yOffset=None, point=None, points=None, draggable='xy', visible=None, zIndex=None, **kwargs)¶: Draw a shape

export(filename, *, theme=None, scale=2, throttle=None, **kwargs)¶

Export chart to a static format (png, jpeg, svg or pdf) using a remote export server

Parameters:

filename (pathlib.Path, str) – the name of the exported file, including the file extension (e.g. png, jpg, pdf or svg)
theme (dict, None) –
the theme in which to render the chart

defaults to the currently active default theme
scale (int) –
the resolution scale

defaults to 2 (i.e a 600 x 400 chart will be rendered as 1200 x 800)
throttle (int) –
the number of seconds to wait between each export request, such as to respect the rate limit of the export server

defaults to easychart.config.exporting[‘rate-limit’] or 10 seconds
**kwargs (dict (optional)) – Additional arguments to pass to the HTTP request

property exporting¶

Get or set the exporting options

Getter:

Return the exporting options

returns:: int

Setter:

Set the exporting options

accepts:: bool, dict

Note

If given a bool, value is assigned to chart.exporting.enabled
If given a dict, value is assigned as is

property height¶

Get or set the chart height

Note

alias for chart.chart.height

Getter:

Return the chart height

returns:: int, str

Setter:

Set the chart height

accepts:: int, str

Note

The chart height can be provided as a number of pixels, a string representing a number of pixels (e.g. "400px") or a percentage (e.g. 50%) of the chart width

property inverted¶

Get or set whether the chart is inverted

Note

alias for chart.chart.inverted

Getter:

Return whether the chart is inverted

returns:: bool

Setter:

Set whether the chart is inverted

accepts:: bool

property legend¶

Get or set the legend

Getter:

Return the legend configuration

returns:: dict

Setter:

Set the legend configuration

accepts:: bool, dict

Note

If given a bool, value is assigned to chart.legend.enabled
If given a dict, value is assigned to chart.legend

property marker¶

Return marker options

Getter:

Returns marker options

returns:: dict

Setter:

Sets marker options

accepts:: bool, dict

Note

If given a bool, value is assigned to chart.plotOptions.series.marker.enabled
If given None, assigns False to chart.plotOptions.series.marker.enabled
If given a dict, value is assigned to chart.plotOptions.series.marker

plot(data=None, **kwargs)¶

Plot data

Returns:: self – the chart instance
Return type:: Chart

save(filename, *, indent=4)¶

Serializes and dumps the chart configuration as JSON to file

Parameters:

filename (str, Path) – target location
indent (int) – the JSON indentation (number of spaces)
file (Serializes and dumps the chart configuration to)
filename – target location
indent – the JSON indentation (number of spaces)

serialize() → dict¶

Serializes the chart to a native python structure

Return type:: dict

show(*, width=None, theme=None, constr=None)¶

Render chart to an easychart.Grid

Parameters:

width (int, str) – plot width
theme (str, dict) – theme
constr (str) – one of ‘chart’, ‘stock’, ‘map’ or ‘gantt’

Return type:

Grid

Note

The width given in parameter sets the plot width, not the chart width. See notes on chart and plot sizing for more details

property stacked¶: Alias for Chart.plotOptions.series.stacking

property subtitle¶

Get or set the chart subtitle

Note

See Highcharts API for full list of available options

Getter:

Return the chart subtitle configuration (if any)

returns:: dict

Setter:

Set the chart subtitle

accepts:: str, dict

Note

If given a str, assigns the value to chart.subtitle.text
If given a dict, assigns the value to chart.subtitle

example:

>>> chart = easychart.new()
>>> chart.subtitle = "Source: USDA"
>>> chart.serialize()
{"subtitle":{"text":"Source: USDA"}}

property title¶

Get or set the chart title

Note

See Highcharts API for full list of available options

Getter:

Return the chart title configuration (if defined)

returns:: dict

Setter:

Set the chart title

accepts:: str, dict

Note

If given a str, assigns the value to chart.title.text
If given a dict, assigns the value to chart.title

example:

>>> chart = easychart.new()
>>> chart.title = "US Corn Acreage"
>>> chart.serialize()
{"title":{"text":"US Corn Acreage"}}

property tooltip¶

Get or set tooltip configurations

Getter:

Return the tooltip configuration

returns:: dict

Setter:

Set the tooltip configuration

accepts:: str, bool, tuple, dict

Note

If given a bool, assigns the value to chart.tooltip.enabled
If given "shared", sets tooltip.shared = True
If given a str of the form <prefix>{value:.4f}<suffix>, parses it and sets each of the tooltip.valuePrefix, tooltip.valueDecimals and tooltipvalueSuffix

property type¶

Get or set the default series type

Note

alias for chart.chart.type

Getter:

Return the default series type

returns:: str

Setter:

Set the default series type

accepts:: str

property width¶

Get or set the chart width

Note

alias for chart.chart.width

Getter:

Return the chart width

returns:: int, str

Setter:

Set the chart width

accepts:: int, str

Note

The chart width can be provided as a number of pixels, a string representing a number of pixels (e.g. "400px") or a percentage (e.g. 50%) of the default chart width which is defined as 600px

property zoom¶

Get or set the zoom type for the chart

Note

Alias for chart.zoomType; see Highcharts API for additional details on available options

Getter:

Return the zoom type (if defined)

returns:: str

Setter:

Set the zoom options

accepts:: str, bool

Note

If given a str, the value is set under chart.zoomType
If given True, the value ‘xy’ is set under chart.zoomType
If given False, the zoomType is set to None