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

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

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)#

Render chart to an easychart.Grid

Parameters:

  • width (int, str) – plot width

  • theme (str, dict) – theme

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