dhxpyt.chart

 10class Chart:
 11    """
 12    Python wrapper for DHTMLX Chart.
 13
 14    This class provides a Pythonic interface to the DHTMLX Chart JavaScript library.
 15    It supports initialization with a configuration object, API methods, events, and properties.
 16
 17    :param config: The configuration object for the chart (instance of ChartConfig or subclass).
 18    :param widget_parent: The parent DOM element for the chart (optional).
 19    """
 20    def __init__(self, config: ChartConfig, widget_parent: Any = None):
 21        """Initializes the chart instance with the given configuration."""
 22        self.chart = js.dhx.Chart.new(widget_parent, js.JSON.parse(json.dumps(config.to_dict())))
 23
 24    """ Chart API Functions """
 25
 26    def destructor(self) -> None:
 27        """Removes a chart instance and releases the occupied resources."""
 28        self.chart.destructor()
 29
 30    def each_series(self, handler: Callable[[List[Dict[str, Any]]], Any]) -> List[Any]:
 31        """
 32        Iterates over chart series.
 33
 34        :param handler: A callable that receives the list of series and returns a list of results.
 35        :return: List of results from the handler.
 36        """
 37        proxy_handler = create_proxy(handler)
 38        return self.chart.eachSeries(proxy_handler)
 39
 40    def get_series(self, id: str) -> Dict[str, Any]:
 41        """
 42        Returns an object with configuration of a specified series.
 43
 44        :param id: The ID of the series.
 45        :return: Dictionary of series configuration.
 46        """
 47        return self.chart.getSeries(id)
 48
 49    def paint(self) -> None:
 50        """Repaints a chart on a page."""
 51        self.chart.paint()
 52
 53    def set_config(self, config: Dict[str, Any]) -> None:
 54        """
 55        Sets configuration of a chart.
 56
 57        :param config: Dictionary of configuration options.
 58        """
 59        self.chart.setConfig(js.JSON.parse(json.dumps(config)))
 60
 61    def png(self, config: Dict[str, Any] = {}) -> None:
 62        """
 63        Exports a chart to a PNG file.
 64
 65        :param config: Optional export configuration.
 66        """
 67        self.chart.png(js.JSON.parse(json.dumps(config)))
 68
 69    def pdf(self, config: Dict[str, Any] = {}) -> None:
 70        """
 71        Exports a chart to a PDF file.
 72
 73        :param config: Optional export configuration.
 74        """
 75        self.chart.pdf(js.JSON.parse(json.dumps(config)))
 76
 77    """ Chart Events """
 78
 79    def add_event_handler(self, event_name: str, handler: Callable) -> None:
 80        """
 81        Helper to add event handlers dynamically.
 82
 83        :param event_name: The name of the event (e.g., 'resize').
 84        :param handler: The callable to handle the event.
 85        """
 86        event_proxy = create_proxy(handler)
 87        self.chart.events[event_name] = event_proxy
 88
 89    def resize(self, handler: Callable[[int, int], None]) -> None:
 90        """
 91        Fires on changing the size of the chart container.
 92
 93        :param handler: Callable that receives width and height.
 94        """
 95        self.add_event_handler('resize', handler)
 96
 97    def serie_click(self, handler: Callable[[str, str], None]) -> None:
 98        """
 99        Fires on clicking a series.
100
101        :param handler: Callable that receives series ID and item ID.
102        """
103        self.add_event_handler('serieClick', handler)
104
105    def toggle_series(self, handler: Callable[[str, Union[Dict[str, Any], None]], None]) -> None:
106        """
107        Fires on toggle on/off a series in a legend.
108
109        :param handler: Callable that receives series ID and series config (or None).
110        """
111        self.add_event_handler('toggleSeries', handler)
112
113    """ Chart Properties """
114
115    @property
116    def css(self) -> str:
117        """Gets the style classes added to the chart."""
118        return self.chart.css
119
120    @css.setter
121    def css(self, value: str) -> None:
122        """Sets style classes for the chart."""
123        self.chart.css = value
124
125    @property
126    def data(self) -> List[Dict[str, Any]]:
127        """Gets the array of data objects set into the chart."""
128        return self.chart.data
129
130    @data.setter
131    def data(self, value: List[Dict[str, Any]]) -> None:
132        """Sets the array of data objects for the chart."""
133        self.chart.data = value
134
135    @property
136    def export_styles(self) -> Union[bool, List[str]]:
137        """Gets the styles sent to the export service."""
138        return self.chart.exportStyles
139
140    @export_styles.setter
141    def export_styles(self, value: Union[bool, List[str]]) -> None:
142        """Sets the styles for export."""
143        self.chart.exportStyles = value
144
145    @property
146    def legend(self) -> Dict[str, Any]:
147        """Gets the configuration of the chart legend."""
148        return self.chart.legend
149
150    @legend.setter
151    def legend(self, value: Dict[str, Any]) -> None:
152        """Sets the configuration of the chart legend."""
153        self.chart.legend = value
154
155    @property
156    def max_points(self) -> int:
157        """Gets the maxPoints value for averaging large datasets."""
158        return self.chart.maxPoints
159
160    @max_points.setter
161    def max_points(self, value: int) -> None:
162        """Sets the maxPoints value."""
163        self.chart.maxPoints = value
164
165    @property
166    def scales(self) -> Dict[str, Any]:
167        """Gets the configuration of chart scales."""
168        return self.chart.scales
169
170    @scales.setter
171    def scales(self, value: Dict[str, Any]) -> None:
172        """Sets the configuration of chart scales."""
173        self.chart.scales = value
174
175    @property
176    def series(self) -> List[Dict[str, Any]]:
177        """Gets the configuration of chart series."""
178        return self.chart.series
179
180    @series.setter
181    def series(self, value: List[Dict[str, Any]]) -> None:
182        """Sets the configuration of chart series."""
183        self.chart.series = value
184
185    @property
186    def type(self) -> str:
187        """Gets the type of the chart."""
188        return self.chart.type
189
190    @type.setter
191    def type(self, value: str) -> None:
192        """Sets the type of the chart."""
193        self.chart.type = value

11class ChartConfig(ControlConfig):
12    """
13    Base configuration class for DHTMLX Chart.
14
15    This class provides the common configuration options for all chart types.
16    Subclasses should be used for specific chart types to ensure correct configuration
17    and to enforce required properties based on the chart type.
18
19    Note: Not all properties are applicable to all chart types. Refer to the documentation
20    of subclasses for type-specific requirements and usage.
21
22    :param type: The type of the chart (e.g., "line", "bar"). Required.
23    :param series: Configuration of chart series as a list of dictionaries. Required for all types.
24    :param scales: Configuration of chart scales as a dictionary. Required for some types (e.g., line, bar).
25    :param data: An array of data objects to set into the chart. Optional.
26    :param legend: Configuration of the chart legend as a dictionary. Optional for most types, required for Treemap.
27    :param css: Style classes to add to the chart. Optional.
28    :param max_points: Displays an average number of values if the dataset is too large. Optional, mainly for line/spline.
29    :param export_styles: Defines styles sent to the export service. Defaults to False.
30    """
31    def __init__(self,
32                 type: str,
33                 series: List[Dict[str, Any]],
34                 scales: Optional[Dict[str, Any]] = None,
35                 data: Optional[List[Dict[str, Any]]] = None,
36                 legend: Optional[Dict[str, Any]] = None,
37                 css: Optional[str] = None,
38                 max_points: Optional[int] = None,
39                 export_styles: Union[bool, List[str]] = False):
40        self.type = type
41        self.series = series
42        self.scales = scales
43        self.data = data
44        self.legend = legend
45        self.css = css
46        self.max_points = max_points
47        self.export_styles = export_styles

49class LineChartConfig(ChartConfig):
50    """
51    Configuration for Line chart.
52
53    Required properties:
54    - series: List of series configurations (e.g., [{id: "A", value: "company A", color: "#81C4E8", strokeWidth: 3}, ...])
55    - scales: Dictionary of scales (e.g., {"bottom": {text: "month"}, "left": {max: 100}})
56
57    Optional properties:
58    - data: Dataset to parse.
59    - legend: Legend configuration (e.g., {series: ["A"], halign: "right"}).
60    - css: Custom CSS classes.
61    - max_points: Average values for large datasets.
62    - export_styles: Export styles.
63
64    Example usage:
65        config = LineChartConfig(series=[...], scales={...})
66    """
67    def __init__(self,
68                 series: List[Dict[str, Any]],
69                 scales: Dict[str, Any],
70                 data: Optional[List[Dict[str, Any]]] = None,
71                 legend: Optional[Dict[str, Any]] = None,
72                 css: Optional[str] = None,
73                 max_points: Optional[int] = None,
74                 export_styles: Union[bool, List[str]] = False):
75        super().__init__(type="line", series=series, scales=scales, data=data, legend=legend,
76                         css=css, max_points=max_points, export_styles=export_styles)

 78class SplineChartConfig(ChartConfig):
 79    """
 80    Configuration for Spline chart.
 81
 82    Required properties:
 83    - series: List of series configurations (e.g., [{id: "A", value: "company A", color: "#81C4E8", strokeWidth: 3}, ...])
 84    - scales: Dictionary of scales (e.g., {"bottom": {text: "month"}, "left": {max: 100}})
 85
 86    Optional properties:
 87    - data: Dataset to parse.
 88    - legend: Legend configuration.
 89    - css: Custom CSS classes.
 90    - max_points: Average values for large datasets.
 91    - export_styles: Export styles.
 92
 93    Example usage:
 94        config = SplineChartConfig(series=[...], scales={...})
 95    """
 96    def __init__(self,
 97                 series: List[Dict[str, Any]],
 98                 scales: Dict[str, Any],
 99                 data: Optional[List[Dict[str, Any]]] = None,
100                 legend: Optional[Dict[str, Any]] = None,
101                 css: Optional[str] = None,
102                 max_points: Optional[int] = None,
103                 export_styles: Union[bool, List[str]] = False):
104        super().__init__(type="spline", series=series, scales=scales, data=data, legend=legend,
105                         css=css, max_points=max_points, export_styles=export_styles)

194class SplineAreaChartConfig(ChartConfig):
195    """
196    Configuration for SplineArea chart.
197
198    Required properties:
199    - series: List of series configurations.
200    - scales: Dictionary of scales.
201
202    Optional properties:
203    - data: Dataset to parse.
204    - legend: Legend configuration.
205    - css: Custom CSS classes.
206    - max_points: Average values for large datasets (if applicable).
207    - export_styles: Export styles.
208
209    Example usage:
210        config = SplineAreaChartConfig(series=[...], scales={...})
211    """
212    def __init__(self,
213                 series: List[Dict[str, Any]],
214                 scales: Dict[str, Any],
215                 data: Optional[List[Dict[str, Any]]] = None,
216                 legend: Optional[Dict[str, Any]] = None,
217                 css: Optional[str] = None,
218                 max_points: Optional[int] = None,
219                 export_styles: Union[bool, List[str]] = False):
220        super().__init__(type="splineArea", series=series, scales=scales, data=data, legend=legend,
221                         css=css, max_points=max_points, export_styles=export_styles)

107class BarChartConfig(ChartConfig):
108    """
109    Configuration for Bar chart.
110
111    Required properties:
112    - series: List of series configurations (e.g., [{id: "A", value: "company A", fill: "#81C4E8"}, ...])
113    - scales: Dictionary of scales (e.g., {"bottom": {text: "month"}, "left": {max: 100}})
114
115    Optional properties:
116    - data: Dataset to parse.
117    - legend: Legend configuration.
118    - css: Custom CSS classes.
119    - max_points: Average values for large datasets (if applicable).
120    - export_styles: Export styles.
121
122    Example usage:
123        config = BarChartConfig(series=[...], scales={...})
124    """
125    def __init__(self,
126                 series: List[Dict[str, Any]],
127                 scales: Dict[str, Any],
128                 data: Optional[List[Dict[str, Any]]] = None,
129                 legend: Optional[Dict[str, Any]] = None,
130                 css: Optional[str] = None,
131                 max_points: Optional[int] = None,
132                 export_styles: Union[bool, List[str]] = False):
133        super().__init__(type="bar", series=series, scales=scales, data=data, legend=legend,
134                         css=css, max_points=max_points, export_styles=export_styles)

136class XBarChartConfig(ChartConfig):
137    """
138    Configuration for X-Bar (horizontal Bar) chart.
139
140    Required properties:
141    - series: List of series configurations.
142    - scales: Dictionary of scales.
143
144    Optional properties:
145    - data: Dataset to parse.
146    - legend: Legend configuration.
147    - css: Custom CSS classes.
148    - max_points: Average values for large datasets (if applicable).
149    - export_styles: Export styles.
150
151    Example usage:
152        config = XBarChartConfig(series=[...], scales={...})
153    """
154    def __init__(self,
155                 series: List[Dict[str, Any]],
156                 scales: Dict[str, Any],
157                 data: Optional[List[Dict[str, Any]]] = None,
158                 legend: Optional[Dict[str, Any]] = None,
159                 css: Optional[str] = None,
160                 max_points: Optional[int] = None,
161                 export_styles: Union[bool, List[str]] = False):
162        super().__init__(type="x-bar", series=series, scales=scales, data=data, legend=legend,
163                         css=css, max_points=max_points, export_styles=export_styles)

165class AreaChartConfig(ChartConfig):
166    """
167    Configuration for Area chart.
168
169    Required properties:
170    - series: List of series configurations (e.g., [{id: "A", value: "company A", color: "#81C4E8", strokeWidth: 3}, ...])
171    - scales: Dictionary of scales.
172
173    Optional properties:
174    - data: Dataset to parse.
175    - legend: Legend configuration.
176    - css: Custom CSS classes.
177    - max_points: Average values for large datasets (if applicable).
178    - export_styles: Export styles.
179
180    Example usage:
181        config = AreaChartConfig(series=[...], scales={...})
182    """
183    def __init__(self,
184                 series: List[Dict[str, Any]],
185                 scales: Dict[str, Any],
186                 data: Optional[List[Dict[str, Any]]] = None,
187                 legend: Optional[Dict[str, Any]] = None,
188                 css: Optional[str] = None,
189                 max_points: Optional[int] = None,
190                 export_styles: Union[bool, List[str]] = False):
191        super().__init__(type="area", series=series, scales=scales, data=data, legend=legend,
192                         css=css, max_points=max_points, export_styles=export_styles)

250class Pie3DChartConfig(ChartConfig):
251    """
252    Configuration for Pie 3D chart.
253
254    Required properties:
255    - series: List of series configurations.
256
257    Optional properties:
258    - data: Dataset to parse.
259    - legend: Legend configuration.
260    - css: Custom CSS classes.
261    - export_styles: Export styles.
262
263    Note: Scales and max_points are not applicable.
264
265    Example usage:
266        config = Pie3DChartConfig(series=[...])
267    """
268    def __init__(self,
269                 series: List[Dict[str, Any]],
270                 data: Optional[List[Dict[str, Any]]] = None,
271                 legend: Optional[Dict[str, Any]] = None,
272                 css: Optional[str] = None,
273                 export_styles: Union[bool, List[str]] = False):
274        super().__init__(type="pie3D", series=series, data=data, legend=legend,
275                         css=css, export_styles=export_styles)

223class PieChartConfig(ChartConfig):
224    """
225    Configuration for Pie chart.
226
227    Required properties:
228    - series: List of series configurations (e.g., [{value: "value", color: "color", text: "month"}])
229
230    Optional properties:
231    - data: Dataset to parse.
232    - legend: Legend configuration (e.g., {values: {text: "id", color: "color"}}).
233    - css: Custom CSS classes.
234    - export_styles: Export styles.
235
236    Note: Scales and max_points are not applicable.
237
238    Example usage:
239        config = PieChartConfig(series=[...])
240    """
241    def __init__(self,
242                 series: List[Dict[str, Any]],
243                 data: Optional[List[Dict[str, Any]]] = None,
244                 legend: Optional[Dict[str, Any]] = None,
245                 css: Optional[str] = None,
246                 export_styles: Union[bool, List[str]] = False):
247        super().__init__(type="pie", series=series, data=data, legend=legend,
248                         css=css, export_styles=export_styles)

277class DonutChartConfig(ChartConfig):
278    """
279    Configuration for Donut chart.
280
281    Required properties:
282    - series: List of series configurations.
283
284    Optional properties:
285    - data: Dataset to parse.
286    - legend: Legend configuration.
287    - css: Custom CSS classes.
288    - export_styles: Export styles.
289
290    Note: Scales and max_points are not applicable.
291
292    Example usage:
293        config = DonutChartConfig(series=[...])
294    """
295    def __init__(self,
296                 series: List[Dict[str, Any]],
297                 data: Optional[List[Dict[str, Any]]] = None,
298                 legend: Optional[Dict[str, Any]] = None,
299                 css: Optional[str] = None,
300                 export_styles: Union[bool, List[str]] = False):
301        super().__init__(type="donut", series=series, data=data, legend=legend,
302                         css=css, export_styles=export_styles)

304class RadarChartConfig(ChartConfig):
305    """
306    Configuration for Radar chart.
307
308    Required properties:
309    - series: List of series configurations (e.g., [{id: "A", value: "company A", color: "#81C4E8", pointColor: "#81C4E8"}])
310    - scales: Dictionary of scales (e.g., {"radial": {value: "month", maxTicks: 10}})
311
312    Optional properties:
313    - data: Dataset to parse.
314    - legend: Legend configuration.
315    - css: Custom CSS classes.
316    - max_points: Average values for large datasets (if applicable).
317    - export_styles: Export styles.
318
319    Example usage:
320        config = RadarChartConfig(series=[...], scales={...})
321    """
322    def __init__(self,
323                 series: List[Dict[str, Any]],
324                 scales: Dict[str, Any],
325                 data: Optional[List[Dict[str, Any]]] = None,
326                 legend: Optional[Dict[str, Any]] = None,
327                 css: Optional[str] = None,
328                 max_points: Optional[int] = None,
329                 export_styles: Union[bool, List[str]] = False):
330        super().__init__(type="radar", series=series, scales=scales, data=data, legend=legend,
331                         css=css, max_points=max_points, export_styles=export_styles)