From 489b112f169e66a8e5f0a71a4f595d947b6c5c53 Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Fri, 19 Jul 2019 10:35:04 -0400 Subject: [PATCH 1/8] Summarizing thoughts in issue and setting up specs --- spec_01.md | 46 +++++++++++++++++++++++++++++ spec_02.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ spec_03.md | 31 ++++++++++++++++++++ 3 files changed, 163 insertions(+) create mode 100644 spec_01.md create mode 100644 spec_02.md create mode 100644 spec_03.md diff --git a/spec_01.md b/spec_01.md new file mode 100644 index 0000000..0755c3f --- /dev/null +++ b/spec_01.md @@ -0,0 +1,46 @@ +- Spec: 1 +- Title: Methods on libraries +- Version: 0.1 +- Last-Modified: 2019-07-19 +- Authors: [James Bednar](), + [Julia Signell](jsignell@gmail.com), + [Jake Vanderplas]() +- Status: Active +- Type: Standards +- Content-Type: text/markdown +- Created: 2019-07-19 + +## Abstract +This spec describes a proposed shared API for enabling plotting libraries. + +This spec uses LIBRARY to refer to any specific visualization library. + +## If a method doesn't make sense +If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("JSON support not available in LIBRARY"). + +## `.__spec_version__()` method +Calling `.__spec_version__()` on the library should return a list of the specs that the library complies with. It should include the version of the spec that is being used. + +```python +>>> LIBRARY.__spec_version__() +{1: 0.1, 2: 0.1} +``` + +## Enable output from library +Each library should provide a uniform way to enable itself in jupyter notebook & jupyterlab. + +> #### What currently exists +> - matplotlib has `%matplotlib inline` +> - bokeh has `bokeh.output_notebook()` +> - altair has `alt.renderers.enable('notebook')` + +### Proposal 1 : magics +Every library should define something like `%enable_LIBRARY` + +### Proposal 2: method +Provide an `enable()` method on the library that can take an optional `output` kwarg, but provides a sensible default. + +`LIBRARY.enable()` == `LIBRARY.enable(output='notebook')` + +#### Context +This might be preferred over magics because some tools need a specification that is usable both within and outside of jupyter. We can always add special cases to deal with magics, but prefer just to have a normal Python call that can register things with Jupyter if it's available but doesn't otherwise cause syntax errors (if not skipped) or missing functionality (if skipped) outside of Jupyter/IPython. diff --git a/spec_02.md b/spec_02.md new file mode 100644 index 0000000..5db5bfa --- /dev/null +++ b/spec_02.md @@ -0,0 +1,86 @@ +- Spec: 2 +- Title: Methods on figure objects +- Version: 0.1 +- Last-Modified: 2019-07-19 +- Authors: [James Bednar](), + [David Hoese](), + [Jon Mease](jon.mease@gmail.com), + [Julia Signell](jsignell@gmail.com), +- Status: Active +- Type: Standards +- Content-Type: text/markdown +- Created: 2019-07-19 + +## Abstract +This spec describes a proposed shared API for accessing objects from various plotting libraries. + +In this notebook we will use **figure** to refer to any object that has a visible representation but which can also be saved, exported, etc. This includes generic visualizations or animation that may or may not be a "plot" (axes, ticks, etc)? + +When detailing a method, this spec uses FIGURE to refer to any specific figure object and LIBRARY to refer to any specific visualization library. + +## If a method doesn't make sense +If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("JSON support not available in LIBRARY"). + +## Jupyter methods +Every library that supports rendering in Jupyter should support the various IPython rich display methods, i.e. `repr_html`, `repr_png`, `_ipython_display_`. + +## `.show()` +Every figure should have the ability to render itself. + +### Proposal + 1) The top-level figure class has a `.show()` method that can be called without arguments to display the figure as a side-effect. + 2) The optional `renderer` kwarg can be used to override the current default renderer. e.g.: + - `FIGURE.show(renderer='png')` to display the figure as a static png image/ + - `FIGURE.show(renderer='browser')` to display the figure in a browser tab. This works in non-jupyter/IPython contexts. + +## `.save()` method +Every figure should have the knowledge of how to export itself to a file on disk. + +> #### What currently exists +> - matplotlib has `.savefig` which saves the current figure, with options `fname` and `format` among others. +> - plotly has `write_*` methods which write the figure to a `file` (or writable object) and return `None`. +> - bokeh has top level `export_*` methods for each output format as well as `save` (only outputs html) which both take a FIGURE as the arg. + +### Proposal +Figures should have `FIGURE.save()` method for exporting. + +There are several kwargs that `save` should include: + + 1) `file`: should be a file object or optionally a path to a file. If a file path is used rather than a file object and that is not supported, the library should raise a sensible error. Can default to some user configured value. + 2) `output`: should be a file format that the figure can be exported to i.e. `'png'`, `'json'`, `'html'`. The library should set a default output and/or allow the user to configure the output. For instance matplotlib does: + > If format is not set, then the output format is inferred from the extension of `fname`, if any, and from `rcParams["savefig.format"]` otherwise. If `format` is set, it determines the output format. + > + >from: [matplotlib.pyplot.savefig](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html) + +**NOTE**: These kwargs are deliberately selected to avoid builtins in python 3 which precludes `format`, but no longer precludes `file`. + +After these two, save can have any additional kwargs needed. + +#### What to return +`FIGURE.save()` should return the file path or object that was saved to. + +#### Some examples +Save to default location: + +```python +FIGURE.save() +``` + +Save to a particular location: + +```python +with open('/path/to/output.html', 'w') as file: + FIGURE.save(file) +``` + +is equivalent to + +```python +FIGURE.save(file='/path/to/output.html') +``` + +is equivalent to + +```python +FIGURE.save('/path/to/output.html', output='html') +``` diff --git a/spec_03.md b/spec_03.md new file mode 100644 index 0000000..5421f63 --- /dev/null +++ b/spec_03.md @@ -0,0 +1,31 @@ +- Spec: 3 +- Title: Methods on children of figures +- Version: 0.1 +- Last-Modified: 2019-07-19 +- Authors: [Jon Mease](jon.mease@gmail.com), + [Julia Signell](jsignell@gmail.com), +- Status: Active +- Type: Standards +- Content-Type: text/markdown +- Created: 2019-07-19 + +## Abstract +This spec describes a proposed shared API for accessing objects within the figure hierarchy from various plotting libraries. + +This spec uses **figure** to refer to any object that has a visible representation but which can also be saved, exported, etc. This includes generic visualizations or animation that may or may not be a "plot" (axes, ticks, etc)? + +When referring to parts of a figure (such as axes and ticks) we'll use the term: **child**. + +When detailing a method, this spec uses FIGURE to refer to any specific figure object and LIBRARY to refer to any specific visualization library, and CHILD to refer to the child of a figure. + +## If a method doesn't make sense +If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("JSON support not available in LIBRARY"). + +## Accessing root figure +Every child should know what figure it belongs to. + +### Proposal +Every object in the figure hierarchy should have a `.root` property that returns the parent figure, or if deeply nested, the grand or great-grandparent figure. If the object doesn't belong to a figure then it should return `None`. + +> #### What currently exists +> plotly calls these "graph objects" and returns them on the `figure` property. From 63068a1541d9431cab7bca6d7a8526ac56f6f0ed Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Fri, 19 Jul 2019 10:35:50 -0400 Subject: [PATCH 2/8] Adding readme --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3ebb878..ca62e59 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,5 @@ -# spec -Minimal shared API spec +# Shared specifications for Python Visualization + +This repo will store any specifications that arise as well as any build and testing code that is determined to be useful for managing and verifying the use of specs. + +Every spec will have a version and target a specific section of the library API. From f59d94d9a47dd088f4b6554eb41d8f0ab7a6934d Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Fri, 8 Nov 2019 09:31:20 -0500 Subject: [PATCH 3/8] Apply suggestions from @jbednar Co-Authored-By: James A. Bednar --- spec_01.md | 12 +++++++----- spec_02.md | 14 +++++++------- spec_03.md | 6 +++--- 3 files changed, 17 insertions(+), 15 deletions(-) diff --git a/spec_01.md b/spec_01.md index 0755c3f..7aa885c 100644 --- a/spec_01.md +++ b/spec_01.md @@ -11,12 +11,12 @@ - Created: 2019-07-19 ## Abstract -This spec describes a proposed shared API for enabling plotting libraries. +This spec describes a proposed minimal shared Python API for plotting libraries. This spec uses LIBRARY to refer to any specific visualization library. ## If a method doesn't make sense -If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("JSON support not available in LIBRARY"). +If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("Unsupported: LIBRARY does not provide JSON output"). ## `.__spec_version__()` method Calling `.__spec_version__()` on the library should return a list of the specs that the library complies with. It should include the version of the spec that is being used. @@ -33,14 +33,16 @@ Each library should provide a uniform way to enable itself in jupyter notebook & > - matplotlib has `%matplotlib inline` > - bokeh has `bokeh.output_notebook()` > - altair has `alt.renderers.enable('notebook')` +> - holoviews has `hv.extension('bokeh')` +> - hvplot has `import hvplot.pandas` ### Proposal 1 : magics Every library should define something like `%enable_LIBRARY` -### Proposal 2: method -Provide an `enable()` method on the library that can take an optional `output` kwarg, but provides a sensible default. +### Proposal 2: function call (preferred) +Provide an `enable()` function call on the library that can take an optional `output` kwarg, but provides a sensible default. `LIBRARY.enable()` == `LIBRARY.enable(output='notebook')` #### Context -This might be preferred over magics because some tools need a specification that is usable both within and outside of jupyter. We can always add special cases to deal with magics, but prefer just to have a normal Python call that can register things with Jupyter if it's available but doesn't otherwise cause syntax errors (if not skipped) or missing functionality (if skipped) outside of Jupyter/IPython. +A function call is preferred over magics because some tools need a specification that is usable both within and outside of jupyter. We can always add special cases to deal with magics, but prefer just to have a normal Python call that can register things with Jupyter if it's available but doesn't otherwise cause syntax errors (if not skipped) or missing functionality (if skipped) outside of Jupyter/IPython. diff --git a/spec_02.md b/spec_02.md index 5db5bfa..e6c2f1c 100644 --- a/spec_02.md +++ b/spec_02.md @@ -12,23 +12,23 @@ - Created: 2019-07-19 ## Abstract -This spec describes a proposed shared API for accessing objects from various plotting libraries. +This spec describes a proposed shared Python API for accessing objects from various plotting libraries. -In this notebook we will use **figure** to refer to any object that has a visible representation but which can also be saved, exported, etc. This includes generic visualizations or animation that may or may not be a "plot" (axes, ticks, etc)? +In this notebook we will use **figure** to refer to any object that has a visible representation but that can also be saved, exported, etc. This includes generic visualizations or animations that may or may not be considered a "plot" with axes, ticks, and so on.``` When detailing a method, this spec uses FIGURE to refer to any specific figure object and LIBRARY to refer to any specific visualization library. ## If a method doesn't make sense -If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("JSON support not available in LIBRARY"). +If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("Unsupported: LIBRARY does not provide JSON output"). ## Jupyter methods -Every library that supports rendering in Jupyter should support the various IPython rich display methods, i.e. `repr_html`, `repr_png`, `_ipython_display_`. +Every library that supports rendering in Jupyter should support at least one of the various IPython rich display methods, i.e. `_repr_html_`, `_repr_png_`, `_ipython_display_`. ## `.show()` Every figure should have the ability to render itself. ### Proposal - 1) The top-level figure class has a `.show()` method that can be called without arguments to display the figure as a side-effect. + 1) The top-level figure class should have a `.show()` method that can be called without arguments to display the figure as a side-effect. 2) The optional `renderer` kwarg can be used to override the current default renderer. e.g.: - `FIGURE.show(renderer='png')` to display the figure as a static png image/ - `FIGURE.show(renderer='browser')` to display the figure in a browser tab. This works in non-jupyter/IPython contexts. @@ -46,8 +46,8 @@ Figures should have `FIGURE.save()` method for exporting. There are several kwargs that `save` should include: - 1) `file`: should be a file object or optionally a path to a file. If a file path is used rather than a file object and that is not supported, the library should raise a sensible error. Can default to some user configured value. - 2) `output`: should be a file format that the figure can be exported to i.e. `'png'`, `'json'`, `'html'`. The library should set a default output and/or allow the user to configure the output. For instance matplotlib does: + 1) `file`: should be a file object or optionally a path to a file. If the LIBRARY does not support file paths and a user provides one rather than a file object, the LIBRARY should raise a sensible error. Can default to some user configured value. + 2) `output`: should be a file format that the figure can be exported to i.e. `'png'`, `'jpg'`, `'json'`, `'html'`. The library should set a default output and/or allow the user to configure the output. For instance matplotlib does: > If format is not set, then the output format is inferred from the extension of `fname`, if any, and from `rcParams["savefig.format"]` otherwise. If `format` is set, it determines the output format. > >from: [matplotlib.pyplot.savefig](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html) diff --git a/spec_03.md b/spec_03.md index 5421f63..e0fd4df 100644 --- a/spec_03.md +++ b/spec_03.md @@ -12,20 +12,20 @@ ## Abstract This spec describes a proposed shared API for accessing objects within the figure hierarchy from various plotting libraries. -This spec uses **figure** to refer to any object that has a visible representation but which can also be saved, exported, etc. This includes generic visualizations or animation that may or may not be a "plot" (axes, ticks, etc)? +This spec uses **figure** to refer to any object that has a visible representation but which can also be saved, exported, etc. This includes generic visualizations or animations that may or may not be considered a "plot" with axes, ticks, and so on. When referring to parts of a figure (such as axes and ticks) we'll use the term: **child**. When detailing a method, this spec uses FIGURE to refer to any specific figure object and LIBRARY to refer to any specific visualization library, and CHILD to refer to the child of a figure. ## If a method doesn't make sense -If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("JSON support not available in LIBRARY"). +If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("Unsupported: LIBRARY does not provide JSON output"). ## Accessing root figure Every child should know what figure it belongs to. ### Proposal -Every object in the figure hierarchy should have a `.root` property that returns the parent figure, or if deeply nested, the grand or great-grandparent figure. If the object doesn't belong to a figure then it should return `None`. +Every object in the figure hierarchy should have a `.root` property that returns the top-level parent figure. A deeply nested child object would not return its immediate parent, but the highest-level parent it is aware of (which may be its parent, grandparent, great-grandparent, etc., depending on how deeply it is nested). If the object doesn't belong to a figure then it should return `None`. > #### What currently exists > plotly calls these "graph objects" and returns them on the `figure` property. From 6301a9a6374b63f2161f6d95e4164ef4e919f1ff Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Mon, 2 Dec 2019 16:30:26 -0500 Subject: [PATCH 4/8] Responding to comments --- spec_01.md | 11 +++++------ spec_02.md | 17 +++++++++++++---- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/spec_01.md b/spec_01.md index 7aa885c..fa92098 100644 --- a/spec_01.md +++ b/spec_01.md @@ -18,8 +18,8 @@ This spec uses LIBRARY to refer to any specific visualization library. ## If a method doesn't make sense If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("Unsupported: LIBRARY does not provide JSON output"). -## `.__spec_version__()` method -Calling `.__spec_version__()` on the library should return a list of the specs that the library complies with. It should include the version of the spec that is being used. +## `.__pyviz_spec__()` method +Calling `.__pyviz_spec__()` on the library should return a list of the specs that the library complies with. It should include the version of the spec that is being used. ```python >>> LIBRARY.__spec_version__() @@ -36,13 +36,12 @@ Each library should provide a uniform way to enable itself in jupyter notebook & > - holoviews has `hv.extension('bokeh')` > - hvplot has `import hvplot.pandas` -### Proposal 1 : magics -Every library should define something like `%enable_LIBRARY` - -### Proposal 2: function call (preferred) +### Proposal: function call Provide an `enable()` function call on the library that can take an optional `output` kwarg, but provides a sensible default. `LIBRARY.enable()` == `LIBRARY.enable(output='notebook')` +**NOTE**: This spec doesn't cover the case where you are in a notebook and want to generate a figure separately from a notebook. + #### Context A function call is preferred over magics because some tools need a specification that is usable both within and outside of jupyter. We can always add special cases to deal with magics, but prefer just to have a normal Python call that can register things with Jupyter if it's available but doesn't otherwise cause syntax errors (if not skipped) or missing functionality (if skipped) outside of Jupyter/IPython. diff --git a/spec_02.md b/spec_02.md index e6c2f1c..b68cf39 100644 --- a/spec_02.md +++ b/spec_02.md @@ -30,8 +30,15 @@ Every figure should have the ability to render itself. ### Proposal 1) The top-level figure class should have a `.show()` method that can be called without arguments to display the figure as a side-effect. 2) The optional `renderer` kwarg can be used to override the current default renderer. e.g.: - - `FIGURE.show(renderer='png')` to display the figure as a static png image/ - - `FIGURE.show(renderer='browser')` to display the figure in a browser tab. This works in non-jupyter/IPython contexts. + - `FIGURE.show(renderer='png')` to display the figure as a static png image. + - `FIGURE.show(renderer='browser')` to display the figure in a new browser tab. This works in both jupyter/IPython and non-jupyter/IPython contexts. If the library provides interactivity, an interactive figure is preferred. + +After this kwarg, `show` can have any additional kwargs needed. + +**NOTE**: When specifying options for `renderer`, `jpg` is preferred to `jpeg`. + +#### What to return +`FIGURE.show()` should return `None`. ## `.save()` method Every figure should have the knowledge of how to export itself to a file on disk. @@ -47,14 +54,16 @@ Figures should have `FIGURE.save()` method for exporting. There are several kwargs that `save` should include: 1) `file`: should be a file object or optionally a path to a file. If the LIBRARY does not support file paths and a user provides one rather than a file object, the LIBRARY should raise a sensible error. Can default to some user configured value. - 2) `output`: should be a file format that the figure can be exported to i.e. `'png'`, `'jpg'`, `'json'`, `'html'`. The library should set a default output and/or allow the user to configure the output. For instance matplotlib does: + 2) `output`: should be a file format that the figure can be exported to i.e. `'png'`, `'jpg'`, `'svg'`, `'json'`, `'html'`. The library should set a default output and/or allow the user to configure the output. For instance matplotlib does: > If format is not set, then the output format is inferred from the extension of `fname`, if any, and from `rcParams["savefig.format"]` otherwise. If `format` is set, it determines the output format. > >from: [matplotlib.pyplot.savefig](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html) **NOTE**: These kwargs are deliberately selected to avoid builtins in python 3 which precludes `format`, but no longer precludes `file`. -After these two, save can have any additional kwargs needed. +After these two, `save` can have any additional kwargs needed. + +**NOTE**: When specifying options for `output`, `jpg` is preferred to `jpeg`. #### What to return `FIGURE.save()` should return the file path or object that was saved to. From b9a2fa01c1f1ead9d5429bc2cd18632880f445a4 Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Mon, 2 Dec 2019 16:33:27 -0500 Subject: [PATCH 5/8] Getting rid of spec 3, moving into separate PR --- spec_03.md | 31 ------------------------------- 1 file changed, 31 deletions(-) delete mode 100644 spec_03.md diff --git a/spec_03.md b/spec_03.md deleted file mode 100644 index e0fd4df..0000000 --- a/spec_03.md +++ /dev/null @@ -1,31 +0,0 @@ -- Spec: 3 -- Title: Methods on children of figures -- Version: 0.1 -- Last-Modified: 2019-07-19 -- Authors: [Jon Mease](jon.mease@gmail.com), - [Julia Signell](jsignell@gmail.com), -- Status: Active -- Type: Standards -- Content-Type: text/markdown -- Created: 2019-07-19 - -## Abstract -This spec describes a proposed shared API for accessing objects within the figure hierarchy from various plotting libraries. - -This spec uses **figure** to refer to any object that has a visible representation but which can also be saved, exported, etc. This includes generic visualizations or animations that may or may not be considered a "plot" with axes, ticks, and so on. - -When referring to parts of a figure (such as axes and ticks) we'll use the term: **child**. - -When detailing a method, this spec uses FIGURE to refer to any specific figure object and LIBRARY to refer to any specific visualization library, and CHILD to refer to the child of a figure. - -## If a method doesn't make sense -If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("Unsupported: LIBRARY does not provide JSON output"). - -## Accessing root figure -Every child should know what figure it belongs to. - -### Proposal -Every object in the figure hierarchy should have a `.root` property that returns the top-level parent figure. A deeply nested child object would not return its immediate parent, but the highest-level parent it is aware of (which may be its parent, grandparent, great-grandparent, etc., depending on how deeply it is nested). If the object doesn't belong to a figure then it should return `None`. - -> #### What currently exists -> plotly calls these "graph objects" and returns them on the `figure` property. From b545ca813d387a936c90d5cf7956b28077bd2f04 Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Mon, 2 Dec 2019 16:36:16 -0500 Subject: [PATCH 6/8] Fixing version example --- spec_01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec_01.md b/spec_01.md index fa92098..c331724 100644 --- a/spec_01.md +++ b/spec_01.md @@ -22,7 +22,7 @@ If a given operation doesn't make sense for that library, then it can satisfy th Calling `.__pyviz_spec__()` on the library should return a list of the specs that the library complies with. It should include the version of the spec that is being used. ```python ->>> LIBRARY.__spec_version__() +>>> LIBRARY.__pyviz_spec__() {1: 0.1, 2: 0.1} ``` From c27fd2632be703deffacb3b2c33927e240e1c9e4 Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Mon, 2 Dec 2019 16:47:43 -0500 Subject: [PATCH 7/8] Switching from renderer to output --- spec_02.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec_02.md b/spec_02.md index b68cf39..8f4e5ef 100644 --- a/spec_02.md +++ b/spec_02.md @@ -25,17 +25,17 @@ If a given operation doesn't make sense for that library, then it can satisfy th Every library that supports rendering in Jupyter should support at least one of the various IPython rich display methods, i.e. `_repr_html_`, `_repr_png_`, `_ipython_display_`. ## `.show()` -Every figure should have the ability to render itself. +Every figure should have the ability to display itself. ### Proposal 1) The top-level figure class should have a `.show()` method that can be called without arguments to display the figure as a side-effect. - 2) The optional `renderer` kwarg can be used to override the current default renderer. e.g.: - - `FIGURE.show(renderer='png')` to display the figure as a static png image. - - `FIGURE.show(renderer='browser')` to display the figure in a new browser tab. This works in both jupyter/IPython and non-jupyter/IPython contexts. If the library provides interactivity, an interactive figure is preferred. + 2) The optional `output` kwarg can be used to override the current default renderer. e.g.: + - `FIGURE.show(output='png')` to display the figure as a static png image. + - `FIGURE.show(output='html')` to display the figure in a new browser tab. This works in both jupyter/IPython and non-jupyter/IPython contexts. If the library provides interactivity, an interactive figure is preferred. After this kwarg, `show` can have any additional kwargs needed. -**NOTE**: When specifying options for `renderer`, `jpg` is preferred to `jpeg`. +**NOTE**: When specifying options for `output`, `jpg` is preferred to `jpeg`. #### What to return `FIGURE.show()` should return `None`. From 9ffa4c12dc1ca76bd13b107d7cd7c33c3e66d74d Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Mon, 2 Dec 2019 16:59:34 -0500 Subject: [PATCH 8/8] Adding the preferred jupyter method --- spec_02.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec_02.md b/spec_02.md index 8f4e5ef..91cd6a5 100644 --- a/spec_02.md +++ b/spec_02.md @@ -22,7 +22,7 @@ When detailing a method, this spec uses FIGURE to refer to any specific figure o If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("Unsupported: LIBRARY does not provide JSON output"). ## Jupyter methods -Every library that supports rendering in Jupyter should support at least one of the various IPython rich display methods, i.e. `_repr_html_`, `_repr_png_`, `_ipython_display_`. +Every library that supports rendering in Jupyter should support at least one of the various IPython rich display methods, i.e. `_repr_mimebundle_`, `_repr_html_`, `_repr_png_`, `_ipython_display_`. ## `.show()` Every figure should have the ability to display itself.