Return the content as string if no "path" is given (#1082)

* Return the content as string if no "path" is given.

* Docstrings changing.

future_changes.md

@@ -5,3 +5,4 @@
 ### Changed
   
 ### Fixed
+- `to_svg()`, `to_html()`: return the content as string if no "path" is given. [[#1067](https://github.com/JetBrains/lets-plot/issues/1067)].

python-package/lets_plot/plot/core.py

@@ -477,27 +477,30 @@ def show(self):
  from ..frontend_context._configuration import _display_plot
  _display_plot(self)
 
- def to_svg(self, path) -> str:
+ def to_svg(self, path=None) -> str:
  """
- Export a plot to a file or to a file-like object in SVG format.
+ Export the plot in SVG format.
 
  Parameters
  ----------
  self : `PlotSpec`
  Plot specification to export.
- path : str, file-like object
+ path : str, file-like object, default=None
  Сan be either a string specifying a file path or a file-like object.
  If a string is provided, the result will be exported to the file at that path.
  If a file-like object is provided, the result will be exported to that object.
+ If None is provided, the result will be returned as a string.
 
  Returns
  -------
  str
- Absolute pathname of created file or None if file-like object is provided.
+ Absolute pathname of created file,
+ SVG content as a string or None if a file-like object is provided.
 
  Examples
  --------
- .. jupyter-execute::
+ ..
+ jupyter-execute::
  :linenos:
  :emphasize-lines: 9
 
@@ -514,29 +517,32 @@ def to_svg(self, path) -> str:
  """
  return _to_svg(self, path)
 
- def to_html(self, path, iframe: bool = None) -> str:
+ def to_html(self, path=None, iframe: bool = None) -> str:
  """
- Export a plot to a file or to a file-like object in HTML format.
+ Export the plot in HTML format.
 
  Parameters
  ----------
  self : `PlotSpec`
  Plot specification to export.
- path : str, file-like object
+ path : str, file-like object, default=None
  Сan be either a string specifying a file path or a file-like object.
  If a string is provided, the result will be exported to the file at that path.
  If a file-like object is provided, the result will be exported to that object.
+ If None is provided, the result will be returned as a string.
  iframe : bool, default=False
  Whether to wrap HTML page into a iFrame.
 
  Returns
  -------
  str
- Absolute pathname of created file or None if file-like object is provided.
+ Absolute pathname of created file,
+ HTML content as a string or None if a file-like object is provided.
 
  Examples
  --------
- .. jupyter-execute::
+ ..
+ jupyter-execute::
  :linenos:
  :emphasize-lines: 8
 
@@ -581,7 +587,7 @@ def to_png(self, path, scale: float = None, w=None, h=None, unit=None, dpi=None)
  Returns
  -------
  str
- Absolute pathname of created file or None if file-like object is provided.
+ Absolute pathname of created file or None if a file-like object is provided.
 
  Notes
  -----
@@ -638,7 +644,7 @@ def to_pdf(self, path, scale: float = None, w=None, h=None, unit=None, dpi=None)
  Returns
  -------
  str
- Absolute pathname of created file or None if file-like object is provided.
+ Absolute pathname of created file or None if a file-like object is provided.
 
  Notes
  -----
@@ -839,7 +845,9 @@ def _to_svg(spec, path) -> Union[str, None]:
  from .. import _kbridge as kbr
 
  svg = kbr._generate_svg(spec.as_dict())
- if isinstance(path, str):
+ if path is None:
+ return svg
+ elif isinstance(path, str):
  abspath = _makedirs(path)
  with io.open(abspath, mode="w", encoding="utf-8") as f:
  f.write(svg)
@@ -856,7 +864,9 @@ def _to_html(spec, path, iframe: bool) -> Union[str, None]:
  from .. import _kbridge as kbr
  html_page = kbr._generate_static_html_page(spec.as_dict(), iframe)
 
- if isinstance(path, str):
+ if path is None:
+ return html_page
+ elif isinstance(path, str):
  abspath = _makedirs(path)
  with io.open(abspath, mode="w", encoding="utf-8") as f:
  f.write(html_page)

python-package/lets_plot/plot/subplots.py

@@ -115,23 +115,25 @@ def show(self):
  from ..frontend_context._configuration import _display_plot
  _display_plot(self)
 
- def to_svg(self, path) -> str:
+ def to_svg(self, path=None) -> str:
  """
- Export all plots currently in this 'bunch' to a file or file-like object in SVG format.
+ Export the plot in SVG format.
 
  Parameters
  ----------
  self : `SupPlotsSpec`
  Subplots specification to export.
- path : str, file-like object
- Сan be either a string specifying a file path or a file-like object.
+ path : str, file-like object, default=None
+ It can be a file path, file-like object, or None.
  If a string is provided, the result will be exported to the file at that path.
  If a file-like object is provided, the result will be exported to that object.
-
+ If None is provided, the result will be returned as a string.
  Returns
  -------
  str
- Absolute pathname of created file or None if file-like object is provided.
+ The result depends on the `path` parameter.
+ It can be the absolute path of the file,
+ SVG content as a string, or None if a file-like object is provided.
 
  Examples
  --------
@@ -156,25 +158,28 @@ def to_svg(self, path) -> str:
  """
  return _to_svg(self, path)
 
- def to_html(self, path, iframe: bool = None) -> str:
+ def to_html(self, path=None, iframe: bool = None) -> str:
  """
- Export all plots currently in this 'bunch' to a file or file-like object in HTML format.
+ Export the plot in HTML format.
 
  Parameters
  ----------
  self : `SupPlotsSpec`
  Subplots specification to export.
- path : str, file-like object
- Сan be either a string specifying a file path or a file-like object.
+ path : str, file-like object, default=None
+ It can be a file path, file-like object, or None.
  If a string is provided, the result will be exported to the file at that path.
  If a file-like object is provided, the result will be exported to that object.
+ If None is provided, the result will be returned as a string.
  iframe : bool, default=False
  Whether to wrap HTML page into a iFrame.
 
  Returns
  -------
  str
- Absolute pathname of created file or None if file-like object is provided.
+ The result depends on the `path` parameter.
+ It can be the absolute path of the file,
+ HTML content as a string, or None if a file-like object is provided.
 
  Examples
  --------
@@ -226,7 +231,7 @@ def to_png(self, path, scale=None, w=None, h=None, unit=None, dpi=None) -> str:
  Returns
  -------
  str
- Absolute pathname of created file or None if file-like object is provided.
+ Absolute pathname of created file or None if a file-like object is provided.
 
  Notes
  -----
@@ -287,7 +292,7 @@ def to_pdf(self, path, scale=None, w=None, h=None, unit=None, dpi=None) -> str:
  Returns
  -------
  str
- Absolute pathname of created file or None if file-like object is provided.
+ Absolute pathname of created file or None if a file-like object is provided.
 
  Notes
  -----