René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"New module proposal: plotly.io","articleBody":"## Overview\r\nI propose that we introduce a new module, `plotly.io`, to house a new suite of functions related to the input and output of plotly figure objects.\r\n\r\n## Why now?\r\nThere are two immediate needs motivating this proposal.\r\n\r\n 1. It's time to integrate [orca](https://github.com/plotly/orca) for static image export\r\n 2. For integration with the JupyterLab [plotly-renderer](https://github.com/jupyterlab/jupyter-renderers/tree/master/packages/plotly-extension) and JupyterLab [chart editor](https://github.com/plotly/jupyterlab-chart-editor), we need a function to write out the JSON representation of a figure with the proper plotly metadata\r\n\r\n## How do things work now?\r\nHere's in inventory of some of our current methods that can perform I/O operations:\r\n - `plotly.plotly.plot`\r\n   - Save figure to plot.ly (with optional filename) and return URL\r\n   - Optionally open in browser\r\n - `plotly.offline.plot`\r\n   - Save html to a local file\r\n   - or return an HTML `div` string\r\n   - optionally open in browser \r\n - `plotly.image.save_as`\r\n   - Save image to a local file with specified image parameters by making a request to plot.ly\r\n - `plotly.get_figure`\r\n   - Convert plot.ly URL into a local figure object\r\n\r\n## Why add something new?\r\nBy my taste, these APIs are a bit scattered and not very discoverable by users without consulting external documentation.  It's also unclear (to me at least) where additional I/O methods, like to two listed above, should be added.\r\n\r\nThere are good reasons that we ended up where we are (e.g. there was no offline mode when the `plotly.plotly` module was developed), but I'd like to propose we adopt a new approach moving forward.\r\n\r\nThe goal is that the options for saving/loading/converting figures should consistent and easily discoverable without the need to consult external documentation.  By triggering tab-completion on the `plotly.io` module, users should be able to learn about all of the import/export options available to them.\r\n\r\n## Design\r\nI propose that the initial functions in the `plotly.io` module have one of 4 prefixes, followed by the format name:\r\n\r\n - `read_{format}(file, ...) -\u003e Figure`:  These methods all accept, as the first argument, either a string or a `read`-able file object. Strings are interpreted as local file paths, other objects are read from. These methods all return a `Figure` object.\r\n - `write_{format}(fig, file, ...) -\u003e None`: These methods all accept the `Figure` to be written as the first argument. The second argument is either a string or a `write`-able file object. Strings are interpreted as local file paths, other objects are written to. These methods `raise` on write failures and return `None`.\r\n - `from_{format}(data, ...) -\u003e Figure`: These methods all accept, as the first argument, some in-memory Python object and return a `Figure` object. These methods don't interact with the file system and have no side effects.\r\n - `to_{format}(fig, ...) -\u003e Any`: These methods all accept the `Figure` to be converted as the first argument. They return an in memory Python object corresponding to the format. These methods don't interact with the file system and have no side effects.\r\n\r\nThe ellipses (`...`) in the signatures above represent additional arguments/options that are specific to given format.\r\n\r\nIn addition to their presence as standalone functions in `plotly.io`, there would also be `write_{format}` and `to_{format}` methods on `Figure` objects. This way, people could use tab completion on a figure itself to learn how to save/convert it.\r\n\r\n## Examples\r\nHere are some examples of functions that could follow these conventions\r\n\r\n```python\r\nimport plotly.graph_objs as go\r\nimport plotly.io as plio\r\nfig = go.Figure(...)\r\n```\r\nSave to HTML file and embed plotly.js\r\n```python\r\nplio.write_html(fig, 'somewhere.html', include_plotlyjs=True)\r\n# or\r\nfig.write_html('somewhere.html', include_plotlyjs=True)\r\n```\r\nBuild an HTML `div` string for figure, and don't embed plotly.js\r\n```python\r\ndiv_str = plio.to_html(fig, output_type='div', include_plotlyjs=False)\r\n# or\r\ndiv_str = fig.to_html(output_type='div', include_plotlyjs=False)\r\n```\r\nSave figure to a file as an svg image of a specific size (using orca)\r\n```python\r\nplio.write_image(fig, 'somewhere.svg', format='svg', width=500, height=400)\r\n# or\r\nfig.write_image('somewhere.svg', format='svg', width=500, height=400)\r\n```\r\nBuild a bytes string representation of the Figure converted to a PNG image\r\n```python\r\npng_bytes = plio.to_image(fig, format='png')\r\n```\r\nBuild a `PIL` `Image` object representing the figure as a static image\r\n```python\r\npil_img = plio.to_pil(fig, format='png')\r\n```\r\nSave to json file\r\n```python\r\nplio.write_json(fig, 'fig.json')\r\n```\r\nSave as gzipped json file to an [HDFS filesystem using PyArrow](https://arrow.apache.org/docs/python/filesystems.html)\r\n```python\r\nimport pyarrow as pa\r\nfs = pa.hdfs.connect(host, port, user=user, ...)\r\nwith fs.open('/path/to/fig.json.gz', 'rb') as f:\r\n    plio.write_json(fig, f, compression='gzip')\r\n```\r\nConvert to json string\r\n```python\r\njson_str = plio.to_json(fig)\r\n```\r\nConvert figure to plot.ly url\r\n```python\r\nplot_ly_url = plio.to_plot_ly(fig)\r\n```\r\nGet figure from plot.ly url\r\n```python\r\nfig = plio.from_plot_ly(plot_ly_url)\r\n```\r\nConvert matplotlib/altair/holoviews/other object to plotly figure\r\n```python\r\nfig = plio.from_matplotlib(mpl_fig)\r\nfig = plio.from_holoviews(hv_obj)\r\nfig = plio.from_altair(altair_fig)\r\n```\r\n\r\n## What happens to `plot`?\r\nNothing, it works fine and there's no reason to change it. Some of these new methods could directly call the current plot methods, or we could look at refactoring the internals a bit so that both `plot` and `io` methods share most of their logic.\r\n\r\n## What about displaying plots?\r\nI don't intend for any of the `to_{format}`/`save_{format}` functions to display the figure.  So initially, the `plot` and `iplot` methods would continue to serve that purpose.\r\n\r\nOne option would be to eventually add a `plotly.io.show` method that is capable of displaying figures using different \"backends\" (similar in spirit to matplotlib).  We actually already have 5 backends for displaying figures:\r\n 1. plot.ly in browser (`plotly.plotly.plot`)\r\n 2. plot.ly in notebook iframe (`plotly.plotly.iplot`)\r\n 3. offline in browser (`plotly.offline.plot`)\r\n 4. offline in notebook (`plotly.offline.iplot`)\r\n 5. display as ipywidget (`plotly.graph_objs.FigureWidget`)\r\n\r\nOnce we have orca integrated, we could even add a static image backend if people were interested in that.\r\n\r\n## Milestone\r\nI propose adding the `plotly.io` module with support for json and orca-based image formats in version 3.2.0.  Depending on how much work it turns out to be, it would be nice to also populate the module with existing html and plot_ly support as well.\r\n\r\nPlease chime in if you have opinions on this!\r\n\r\ncc: @chriddyp @cldougl @Kully @nicolaskruchten @jackparmer @bcdunbar","author":{"url":"https://github.com/jonmmease","@type":"Person","name":"jonmmease"},"datePublished":"2018-08-07T16:20:20.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":8},"url":"https://github.com/1098/plotly.py/issues/1098"}