Starting specs 1 and 2

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.

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.

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')
+```

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.