From 092e8ba97cbb8c3edeb2df7d5e83c60ed536c54d Mon Sep 17 00:00:00 2001 From: Twist Date: Fri, 28 Jul 2023 12:24:29 +0100 Subject: [PATCH 1/5] Update to_plotly_json docstring, and implement helper method to create a json string easily. --- .../python/plotly/plotly/basedatatypes.py | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/packages/python/plotly/plotly/basedatatypes.py b/packages/python/plotly/plotly/basedatatypes.py index 8fa70e0ada..6b4f1dda54 100644 --- a/packages/python/plotly/plotly/basedatatypes.py +++ b/packages/python/plotly/plotly/basedatatypes.py @@ -8,6 +8,7 @@ from copy import deepcopy, copy import itertools from functools import reduce +import json from _plotly_utils.utils import ( _natural_sort_strings, @@ -17,6 +18,7 @@ display_string_positions, chomp_empty_strings, find_closest_string, + PlotlyJSONEncoder, ) from _plotly_utils.exceptions import PlotlyKeyError from .optional_imports import get_module @@ -3316,7 +3318,9 @@ def to_dict(self): def to_plotly_json(self): """ - Convert figure to a JSON representation as a Python dict + Convert figure to a JSON representation as a Python dict. + + Note: May include some JSON-invalid data types, use the `PlotlyJSONEncoder` util when encoding. Returns ------- @@ -3324,6 +3328,16 @@ def to_plotly_json(self): """ return self.to_dict() + def to_json_str(self): + """ + Convert to a JSON string representation. + + Returns + ------- + str + """ + return json.dumps(self.to_plotly_json(), cls=PlotlyJSONEncoder) + @staticmethod def _to_ordered_dict(d, skip_uid=False): """ @@ -5603,6 +5617,16 @@ def to_plotly_json(self): """ return deepcopy(self._props if self._props is not None else {}) + def to_json_str(self): + """ + Convert to a JSON string representation. + + Returns + ------- + str + """ + return json.dumps(self.to_plotly_json(), cls=PlotlyJSONEncoder) + @staticmethod def _vals_equal(v1, v2): """ From 07b459395034981a9824d537afb9f19478f1f975 Mon Sep 17 00:00:00 2001 From: Twist Date: Wed, 2 Aug 2023 16:54:03 +0100 Subject: [PATCH 2/5] Method rename and removal to ensure consistency. --- packages/python/plotly/plotly/basedatatypes.py | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/packages/python/plotly/plotly/basedatatypes.py b/packages/python/plotly/plotly/basedatatypes.py index 6b4f1dda54..3697a7310e 100644 --- a/packages/python/plotly/plotly/basedatatypes.py +++ b/packages/python/plotly/plotly/basedatatypes.py @@ -3328,16 +3328,6 @@ def to_plotly_json(self): """ return self.to_dict() - def to_json_str(self): - """ - Convert to a JSON string representation. - - Returns - ------- - str - """ - return json.dumps(self.to_plotly_json(), cls=PlotlyJSONEncoder) - @staticmethod def _to_ordered_dict(d, skip_uid=False): """ @@ -5611,13 +5601,15 @@ def to_plotly_json(self): """ Return plotly JSON representation of object as a Python dict + Note: May include some JSON-invalid data types, use the `PlotlyJSONEncoder` util when encoding. + Returns ------- dict """ return deepcopy(self._props if self._props is not None else {}) - def to_json_str(self): + def to_json(self): """ Convert to a JSON string representation. From 7ef805c87df8a6f3889f97396933730aa46b772b Mon Sep 17 00:00:00 2001 From: Twist Date: Fri, 18 Aug 2023 16:19:44 +0100 Subject: [PATCH 3/5] Use faster plotly.io serialization. --- .../python/plotly/plotly/basedatatypes.py | 27 +++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/packages/python/plotly/plotly/basedatatypes.py b/packages/python/plotly/plotly/basedatatypes.py index 3697a7310e..56238dadf3 100644 --- a/packages/python/plotly/plotly/basedatatypes.py +++ b/packages/python/plotly/plotly/basedatatypes.py @@ -5609,15 +5609,38 @@ def to_plotly_json(self): """ return deepcopy(self._props if self._props is not None else {}) - def to_json(self): + def to_json(self, *args, **kwargs): """ Convert to a JSON string representation. + Parameters + ---------- + validate: bool (default True) + True if the figure should be validated before being converted to + JSON, False otherwise. + + pretty: bool (default False) + True if JSON representation should be pretty-printed, False if + representation should be as compact as possible. + + remove_uids: bool (default True) + True if trace UIDs should be omitted from the JSON representation + + engine: str (default None) + The JSON encoding engine to use. One of: + - "json" for an encoder based on the built-in Python json module + - "orjson" for a fast encoder the requires the orjson package + If not specified, the default encoder is set to the current value of + plotly.io.json.config.default_encoder. + Returns ------- str + Representation of figure as a JSON string """ - return json.dumps(self.to_plotly_json(), cls=PlotlyJSONEncoder) + import plotly.io as pio + + return pio.to_json(self, *args, **kwargs) @staticmethod def _vals_equal(v1, v2): From 9b904c5d527253589c1a0229ff219aaf455c487b Mon Sep 17 00:00:00 2001 From: Twist Date: Mon, 21 Aug 2023 16:56:04 +0100 Subject: [PATCH 4/5] Clean up imports and docstrings for consistency. --- packages/python/plotly/plotly/basedatatypes.py | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/packages/python/plotly/plotly/basedatatypes.py b/packages/python/plotly/plotly/basedatatypes.py index 56238dadf3..b2852f507b 100644 --- a/packages/python/plotly/plotly/basedatatypes.py +++ b/packages/python/plotly/plotly/basedatatypes.py @@ -8,7 +8,6 @@ from copy import deepcopy, copy import itertools from functools import reduce -import json from _plotly_utils.utils import ( _natural_sort_strings, @@ -18,7 +17,6 @@ display_string_positions, chomp_empty_strings, find_closest_string, - PlotlyJSONEncoder, ) from _plotly_utils.exceptions import PlotlyKeyError from .optional_imports import get_module @@ -3318,7 +3316,7 @@ def to_dict(self): def to_plotly_json(self): """ - Convert figure to a JSON representation as a Python dict. + Convert figure to a JSON representation as a Python dict Note: May include some JSON-invalid data types, use the `PlotlyJSONEncoder` util when encoding. @@ -5611,12 +5609,12 @@ def to_plotly_json(self): def to_json(self, *args, **kwargs): """ - Convert to a JSON string representation. + Convert object to a JSON string representation Parameters ---------- validate: bool (default True) - True if the figure should be validated before being converted to + True if the object should be validated before being converted to JSON, False otherwise. pretty: bool (default False) @@ -5636,7 +5634,7 @@ def to_json(self, *args, **kwargs): Returns ------- str - Representation of figure as a JSON string + Representation of object as a JSON string """ import plotly.io as pio From 43d0432805c6b4e406b7e68e688d2f0df3c6c304 Mon Sep 17 00:00:00 2001 From: Twist Date: Tue, 22 Aug 2023 10:47:44 +0100 Subject: [PATCH 5/5] Update `to_plotly_json` docstrings, add to CHANGELOG.md. --- CHANGELOG.md | 5 +++++ packages/python/plotly/plotly/basedatatypes.py | 6 ++++-- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a0f13b6f0..74fe1aa2a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). +## UNRELEASED + +### Updated +- Improved json docstrings, added `BasePlotlyType.to_json()` method [[#4301](https://github.com/plotly/plotly.py/pull/4301)] + ## [5.16.1] - 2023-08-16 ### Fixed diff --git a/packages/python/plotly/plotly/basedatatypes.py b/packages/python/plotly/plotly/basedatatypes.py index b2852f507b..6f4e632055 100644 --- a/packages/python/plotly/plotly/basedatatypes.py +++ b/packages/python/plotly/plotly/basedatatypes.py @@ -3318,7 +3318,8 @@ def to_plotly_json(self): """ Convert figure to a JSON representation as a Python dict - Note: May include some JSON-invalid data types, use the `PlotlyJSONEncoder` util when encoding. + Note: May include some JSON-invalid data types, use the `PlotlyJSONEncoder` util + or the `to_json` method to encode to a string. Returns ------- @@ -5599,7 +5600,8 @@ def to_plotly_json(self): """ Return plotly JSON representation of object as a Python dict - Note: May include some JSON-invalid data types, use the `PlotlyJSONEncoder` util when encoding. + Note: May include some JSON-invalid data types, use the `PlotlyJSONEncoder` util + or the `to_json` method to encode to a string. Returns -------