René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"plotly.io.renderer proposal","articleBody":"## Overview\r\nThis issue is a design proposal for a new renderer abstraction for plotly.py to replace the `iplot` functions.\r\n\r\n## Goals\r\nSeveral goals motivate this work\r\n\r\n 1. Make it possible to support new plot rendering contexts like static images, rendering inside colab, and rendering in popup windows.\r\n 2. Remove the \"offline\" language from plot rendering. As discussed in the [v4 plans](https://github.com/plotly/plotly.py/issues/1420), the Chart Studio integration (the `plotly.plotly` stuff) will be split off into a separate package for v4, and the remaining `plotly` package will be only \"offline\" only.  So having the \"offline\" language will be unnecessary and potentially confusing.\r\n 3. Provide a single location to change the plot rendering approach across an entire notebook.  This will make it much easier for folks to copy/paste documentation examples and change the example to their preferred rendering approach.\r\n\r\n## Background\r\nThere are currently 2 ways to display plots in plotly.py in \"offline\" mode:\r\n\r\n 1. `plotly.offline.iplot`:  This will display plots inline in a Jupyter Notebook or in JupyterLab. The use in the classic notebook requires calling `plotly.offline.init_notebook_mode()` to initialize the notebook before rendering.  The use in JupyterLab requires the [`@jupyterlab/plotly-extension`](https://github.com/jupyterlab/jupyter-renderers/tree/master/packages/plotly-extension)\r\n 2. `plotly.offline.plot`:  This will save the plot to a standalone HTML file and, by default, open it in the default system web browser.\r\n\r\n## Design Influences\r\nThis design is somewhat inspired by the approach used by the Altair project (https://altair-viz.github.io/user_guide/renderers.html), and I expect the Altair implementation will be very helpful reference during the implementation phase of this effort.\r\n\r\nThe design also draws on elements of the `plotly.io.templates` design (See https://github.com/plotly/plotly.py/pull/1224), and is intended to have a consistent user experience.\r\n\r\n## API\r\n\r\n### Default renderer\r\nI propose we add a new configuration object named `renderers` in the `plotly.io` module.  This will sit alongside the `plotly.io.templates` and `plotly.io.orca` configuration objects.  Users will view and specify the current default renderer using property assignment. For example, to specify the equivalent of `plotly.offline.iplot`:\r\n\r\n```python\r\nimport plotly.io as pio\r\npio.renderers.default = 'notebook'  # `init_notebook_mode` and output with `iplot`\r\n```\r\nHere are some other [`mimetype-based.`](https://jupyter.readthedocs.io/en/latest/reference/mimetype.html) renderer options\r\n\r\n```python\r\npio.renderers.default = 'notebook_connected'\r\npio.renderers.default = 'plotly_mimetype'  # Render using plotly mimetype\r\npio.renderers.default = 'jupyterlab' # Same as 'default'\r\npio.renderers.default = 'nteract'  # Same as 'default'\r\npio.renderers.default = 'kaggle'  # Same as 'notebook'\r\npio.renderers.default = 'colab'  # New\r\npio.renderers.default = 'png'  # Init orca server and output as png\r\npio.renderers.default = 'svg'  # Init orca server and output as svg\r\npio.renderers.default = 'pdf'  # Init orca server and output as pdf\r\n```\r\nIn addition to the mime type based renderers for use in a Jupyter context, we can support additional renderers that display figures externally (not inline).  For example\r\n\r\n```python\r\npio.renderers.default = 'browser' # Popup in local default browser tab like plotly.offline.plot\r\npio.renderers.default = 'chrome' # Popup in local chrome tab like plotly.offline.plot\r\npio.renderers.default = 'firefox' # Popup in local firefox tab like plotly.offline.plot\r\npio.renderers.default = 'qtwindow' # (someday) Popup interactive figure in a pyqt browser\r\n```\r\n\r\n### Combining renderers\r\nMultiple renderers can be registered as the default by separating the renderer names with `'+'` characters.  This is the same combination syntax used to combine templates in `plotly.io.templates`. When multiple mime type renderers are specified this way, a single bundle will be created with the render representation for each one.  As motivation, consider\r\n\r\n```python\r\npio.renderers.default = 'notebook+jupyterlab+png'\r\n```\r\nA notebook with this renderer specification would display figures properly in the classic notebook ('notebook'), in jupyterlab ('jupyterlab'), in exported HTML ('notebook'), in the QtConsole/PyCharm ('png'), and in exported PDFs ('png').\r\n\r\nOf course this would result in fairly large notebook sizes, but the user will have the flexibility to define where this code needs to render figures.\r\n\r\n### repr and show\r\nThere will be two ways to display figures.  If one or more mime-type based renderers are defined and the `plotly.io.renderers.render_on_display` property is set to `True`, then the `go.Figure` instances will display themself automatically as their notebook representation.  If `plotly.io.renderers.render_on_display` is set to `False`, then mimetype based rendering will not be performed when figures are displayed.\r\n\r\nIn addition, all renderer types (including external renderers) can be invokes using a new `plotly.io.show` function.  This function will display the figure as a side effect and will return `None`.\r\n\r\nThe `show` functions will also allow the user to override the default renderer. e.g.\r\n```python\r\nimport plotly.io as pio\r\npio.renderers.default = 'notebook'  # `init_notebook_mode` and output with `iplot`\r\n\r\nfig = go.Figure(...)\r\n\r\n# By default show will display figure inline, override to display in browser tab\r\npio.show(fig, renderer='browser')\r\n```\r\n\r\n### Customize renderer properties\r\nSome renderers may need to expose additional configuration options. In this case the default renderer can be specified as an instance of the corresponding class. Each built-in renderer will be defined by a class accessible under `plotly.io.renderers`.\r\n\r\nE.g. to specify a static image renderer with custom properties:\r\n\r\n```python\r\nimport plotly.io as pio\r\npio.renderers['my_png'] = pio.renderers.PngRenderer(width=1000, height=650, scale=1.5)\r\npio.renderers.default = 'my_png'\r\n```\r\n\r\nOr the properties of an existing renderer can be modified directly:\r\n```python\r\npio.renderers['png'].width = 1000\r\npio.renderers['png'].height = 650\r\npio.renderers['png'].scale = 1.5\r\npio.renderers.default = 'png'\r\n```\r\nOr the properties can be overridden temporarily in `plotly.io.show`:\r\n```python\r\npio.show(fig, renderer='png', width=1000, height=650, scale=1.5)\r\n```\r\n\r\n### Registering new renderers\r\nUsers or third-party-libraries may register new renderers by implementing a class following a TBD interface.  \r\n\r\n```python\r\nimport plotly.io as pio\r\n\r\n# Define custom mimetype renderer\r\nclass MyRenderer(pio.base_renderers.MimetypeRenderer):\r\n    ...\r\n    def activate():\r\n        ...\r\n\r\n    def to_mimebundle(self, fig_dict):\r\n        ...\r\n\r\n# Register for use by name\r\nmy_renderer = MyRenderer()\r\npio.renderers['my_renderer'] = my_renderer\r\n\r\n# Set as default\r\npio.renderers.default = 'my_renderer'\r\n```\r\n\r\n### Backward compatibility\r\nFor backward compatibility, `plotly.offline.init_notebook_mode` and `plotly.offline.iplot` will stay around, but they will be implemented on top of the new renderer framework.\r\n\r\nFor plotly.py v3 the default renderer will be `plotly_mimetype` and `iplot` will call `plotly.io.show`.  Calling `plotly.offline.init_notebook_mode()` will set the default renderer to `'plotly_mimetype+notebook'` and `plotly.offline.init_notebook_mode(connected=True)` will set the default renderer to `'plotly_mimetype+notebook_connected'.`\r\n\r\ncc @nicolaskruchten @chriddyp @jackparmer \r\n","author":{"url":"https://github.com/jonmmease","@type":"Person","name":"jonmmease"},"datePublished":"2019-03-11T10:59:08.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":6},"url":"https://github.com/1459/plotly.py/issues/1459"}