Merge pull request #4301 from itsluketwist/feature/update-json-funcs

Update to_plotly_json docstring, and add new to_json_string helper method

Author: alexcjohnson

Diff for: CHANGELOG.md

@@ -3,7 +3,12 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## UNRELEASED
- - Fixed two issues with px.imshow: [[#4330](https://github.com/plotly/plotly.py/issues/4330)] when facet_col is an earlier dimension than animation_frame for xarrays and [[#4329](https://github.com/plotly/plotly.py/issues/4329)] when facet_col has string coordinates in xarrays [[#4331](https://github.com/plotly/plotly.py/pull/4331)]
+
+### Updated
+- Improved json docstrings, added `BasePlotlyType.to_json()` method [[#4301](https://github.com/plotly/plotly.py/pull/4301)]
+
+### Fixed
+- Fixed two issues with px.imshow: [[#4330](https://github.com/plotly/plotly.py/issues/4330)] when facet_col is an earlier dimension than animation_frame for xarrays and [[#4329](https://github.com/plotly/plotly.py/issues/4329)] when facet_col has string coordinates in xarrays [[#4331](https://github.com/plotly/plotly.py/pull/4331)]
 
 ## [5.16.1] - 2023-08-16
 

Diff for: packages/python/plotly/plotly/basedatatypes.py

@@ -3318,6 +3318,9 @@ 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
+        or the `to_json` method to encode to a string.
+
         Returns
         -------
         dict
@@ -5597,12 +5600,48 @@ 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
+        or the `to_json` method to encode to a string.
+
         Returns
         -------
         dict
         """
         return deepcopy(self._props if self._props is not None else {})
 
+    def to_json(self, *args, **kwargs):
+        """
+        Convert object to a JSON string representation
+
+        Parameters
+        ----------
+        validate: bool (default True)
+            True if the object 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 object as a JSON string
+        """
+        import plotly.io as pio
+
+        return pio.to_json(self, *args, **kwargs)
+
     @staticmethod
     def _vals_equal(v1, v2):
         """