From 31872358628b4a7b6bcba5307bce2bf544c9176d Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 19 Mar 2015 17:01:33 -0400 Subject: [PATCH 1/3] DOC : start to move MEP to docs Moved template and MEP25. If people think this is a good idea, we can move the rest of them over from the wiki as well. --- doc/devel/MEP/MEP25.rst | 47 +++++++++++++++++++++++++++++++ doc/devel/MEP/index.rst | 16 +++++++++++ doc/devel/MEP/template.rst | 57 ++++++++++++++++++++++++++++++++++++++ doc/devel/index.rst | 1 + 4 files changed, 121 insertions(+) create mode 100644 doc/devel/MEP/MEP25.rst create mode 100644 doc/devel/MEP/index.rst create mode 100644 doc/devel/MEP/template.rst diff --git a/doc/devel/MEP/MEP25.rst b/doc/devel/MEP/MEP25.rst new file mode 100644 index 000000000000..495a5cf2b816 --- /dev/null +++ b/doc/devel/MEP/MEP25.rst @@ -0,0 +1,47 @@ +.. contents:: Table of Contents + +.. author:: Andrew Seier + +.. date:: July 11, 2014 + +MEP25: Serialization +==================== + + +Status +------ + +**Discussion** + +Branches and Pull requests +-------------------------- + +* development branches: + +* related pull requests: + +Abstract +-------- + +This MEP aims at adding a serializable ``Controller`` objects to act as an ``Artist`` managers. Users would then communicate changes to an ``Artist`` via a ``Controller``. In this way, functionality of the ``Controller`` objects may be added incrementally since each ``Artist`` is still responsible for drawing everything. The goal is to create an API that is usable both by graphing libraries requiring high-level descriptions of figures and libraries requiring low-level interpretations. + +Detailed description +-------------------- + +Matplotlib is a core plotting engine with an API that many users already understand. It's difficult/impossible for other graphing libraries to (1) get a complete figure description, (2) output raw data from the figure object as the user has provided it, (3) understand the semantics of the figure objects without heuristics, and (4) give matplotlib a complete figure description to visualize. In addition, because an ``Artist`` has no conception of its own semantics within the figure, it's difficult to interact with them in a natural way. + +In this sense, matplotlib will adopt a standard Model-View-Controller (MVC) framework. The *Model* will be the user defined data, style, and semantics. The *Views* are the ensemble of each individual ``Artist``, which are responsible for producing the final image based on the *model*. The *Controller* will be the ``Controller`` object managing its set of ``Artist`` objects. + +The ``Controller`` must be able to export the information that it's carrying about the figure on command, perhaps via a ``to_json`` method or similar. Because it would be extremely extraneous to duplicate all of the information in the model with the controller, only user-specified information (data + style) are explicitly kept. If a user wants more information (defaults) from the view/model, it should be able to query for it. + +- This might be annoying to do, non-specified kwargs are pulled from the rcParams object which is in turn created from reading a user specified file and can be dynamically changed at run time. I suppose we could keep a dict of default defaults and compare against that. Not clear how this will interact with the style sheet [[MEP26]] - @tacaswell + +Additional Notes: + +* The `raw data` does not necessarily need to be a ``list``, ``ndarray``, etc. Rather, it can more abstractly just have a method to yield data when needed. + +* Because the ``Controller`` will contain extra information that users may not want to keep around, it should *not* be created by default. You should be able to both (a) instantiate a ``Controller`` with a figure and (b) build a figure with a ``Controller``. + +Use Cases: + +* Export all necessary informat diff --git a/doc/devel/MEP/index.rst b/doc/devel/MEP/index.rst new file mode 100644 index 000000000000..3c76f68f1033 --- /dev/null +++ b/doc/devel/MEP/index.rst @@ -0,0 +1,16 @@ +.. _MEP-index: + +################################ +Matplotlib Enhancement Proposals +################################ + +.. htmlonly:: + + :Release: |version| + :Date: |today| + +.. toctree:: + :maxdepth: 1 + + template + MEP25 diff --git a/doc/devel/MEP/template.rst b/doc/devel/MEP/template.rst new file mode 100644 index 000000000000..ec3e50d05288 --- /dev/null +++ b/doc/devel/MEP/template.rst @@ -0,0 +1,57 @@ +.. contents:: Table of Contents + +.. author:: Michael Droettboom + +.. date:: August 3, 2012 + + +MEP Template +============ + + +This MEP template is a guideline of the sections that a MEP should contain. Extra sections may be added if appropriate, and unnecessary sections may be noted as such. + +Status +------ + +MEPs go through a number of phases in their lifetime: + +- **Discussion**: The MEP is being actively discussed on the mailing list and it is being improved by its author. The mailing list discussion of the MEP should include the MEP number (MEPxxx) in the subject line so they can be easily related to the MEP. + +- **Progress**: Consensus was reached on the mailing list and implementation work has begun. + +- **Completed**: The implementation has been merged into master. + +- **Superseded**: This MEP has been abandoned in favor of another approach. + +Branches and Pull requests +-------------------------- + +All development branches containing work on this MEP should be linked to from here. + +All pull requests submitted relating to this MEP should be linked to from here. (A MEP does not need to be implemented in a single pull request if it makes sense to implement it in discrete phases). + +Abstract +-------- + +The abstract should be a short description of what the MEP will achieve. + +Detailed description +-------------------- + +This section describes the need for the MEP. It should describe the existing problem that it is trying to solve and why this MEP makes the situation better. It should include examples of how the new functionality would be used and perhaps some use cases. + +Implementation +-------------- + +This section lists the major steps required to implement the MEP. Where possible, it should be noted where one step is dependent on another, and which steps may be optionally omitted. Where it makes sense, each step should include a link related pull requests as the implementation progresses. + +Backward compatibility +---------------------- + +This section describes the ways in which the MEP breaks backward incompatibility. + +Alternatives +------------ + +If there were any alternative solutions to solving the same problem, they should be discussed here, along with a justification for the chosen approach. diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 9b1872dd154d..71cac030bd8e 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -22,3 +22,4 @@ The Matplotlib Developers' Guide transformations.rst add_new_projection.rst color_changes + MEP/index From ccfd1c4032197c993a4715ebc2b9a711e97839b4 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 19 Mar 2015 18:37:32 -0400 Subject: [PATCH 2/3] MNT : remove directives that are choking sphinx --- doc/devel/MEP/MEP25.rst | 5 ----- doc/devel/MEP/template.rst | 7 ------- 2 files changed, 12 deletions(-) diff --git a/doc/devel/MEP/MEP25.rst b/doc/devel/MEP/MEP25.rst index 495a5cf2b816..d59e49837aea 100644 --- a/doc/devel/MEP/MEP25.rst +++ b/doc/devel/MEP/MEP25.rst @@ -1,8 +1,3 @@ -.. contents:: Table of Contents - -.. author:: Andrew Seier - -.. date:: July 11, 2014 MEP25: Serialization ==================== diff --git a/doc/devel/MEP/template.rst b/doc/devel/MEP/template.rst index ec3e50d05288..a36b7c9865d2 100644 --- a/doc/devel/MEP/template.rst +++ b/doc/devel/MEP/template.rst @@ -1,10 +1,3 @@ -.. contents:: Table of Contents - -.. author:: Michael Droettboom - -.. date:: August 3, 2012 - - MEP Template ============ From 633155dc77ace7fde13f1892638031a25cfce793 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 26 Mar 2015 23:35:53 -0400 Subject: [PATCH 3/3] MNT : add rest of MEP25, fix wrapping, add ToC --- doc/devel/MEP/MEP25.rst | 146 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 135 insertions(+), 11 deletions(-) diff --git a/doc/devel/MEP/MEP25.rst b/doc/devel/MEP/MEP25.rst index d59e49837aea..0c41348a7586 100644 --- a/doc/devel/MEP/MEP25.rst +++ b/doc/devel/MEP/MEP25.rst @@ -1,7 +1,8 @@ MEP25: Serialization ==================== - +.. contents:: + :local: Status ------ @@ -18,25 +19,148 @@ Branches and Pull requests Abstract -------- -This MEP aims at adding a serializable ``Controller`` objects to act as an ``Artist`` managers. Users would then communicate changes to an ``Artist`` via a ``Controller``. In this way, functionality of the ``Controller`` objects may be added incrementally since each ``Artist`` is still responsible for drawing everything. The goal is to create an API that is usable both by graphing libraries requiring high-level descriptions of figures and libraries requiring low-level interpretations. +This MEP aims at adding a serializable ``Controller`` objects to act +as an ``Artist`` managers. Users would then communicate changes to an +``Artist`` via a ``Controller``. In this way, functionality of the +``Controller`` objects may be added incrementally since each +``Artist`` is still responsible for drawing everything. The goal is to +create an API that is usable both by graphing libraries requiring +high-level descriptions of figures and libraries requiring low-level +interpretations. Detailed description -------------------- -Matplotlib is a core plotting engine with an API that many users already understand. It's difficult/impossible for other graphing libraries to (1) get a complete figure description, (2) output raw data from the figure object as the user has provided it, (3) understand the semantics of the figure objects without heuristics, and (4) give matplotlib a complete figure description to visualize. In addition, because an ``Artist`` has no conception of its own semantics within the figure, it's difficult to interact with them in a natural way. - -In this sense, matplotlib will adopt a standard Model-View-Controller (MVC) framework. The *Model* will be the user defined data, style, and semantics. The *Views* are the ensemble of each individual ``Artist``, which are responsible for producing the final image based on the *model*. The *Controller* will be the ``Controller`` object managing its set of ``Artist`` objects. - -The ``Controller`` must be able to export the information that it's carrying about the figure on command, perhaps via a ``to_json`` method or similar. Because it would be extremely extraneous to duplicate all of the information in the model with the controller, only user-specified information (data + style) are explicitly kept. If a user wants more information (defaults) from the view/model, it should be able to query for it. - -- This might be annoying to do, non-specified kwargs are pulled from the rcParams object which is in turn created from reading a user specified file and can be dynamically changed at run time. I suppose we could keep a dict of default defaults and compare against that. Not clear how this will interact with the style sheet [[MEP26]] - @tacaswell +Matplotlib is a core plotting engine with an API that many users +already understand. It's difficult/impossible for other graphing +libraries to (1) get a complete figure description, (2) output raw +data from the figure object as the user has provided it, (3) +understand the semantics of the figure objects without heuristics, +and (4) give matplotlib a complete figure description to visualize. In +addition, because an ``Artist`` has no conception of its own semantics +within the figure, it's difficult to interact with them in a natural +way. + +In this sense, matplotlib will adopt a standard +Model-View-Controller (MVC) framework. The *Model* will be the user +defined data, style, and semantics. The *Views* are the ensemble of +each individual ``Artist``, which are responsible for producing the +final image based on the *model*. The *Controller* will be the +``Controller`` object managing its set of ``Artist`` objects. + +The ``Controller`` must be able to export the information that it's +carrying about the figure on command, perhaps via a ``to_json`` method +or similar. Because it would be extremely extraneous to duplicate all +of the information in the model with the controller, only +user-specified information (data + style) are explicitly kept. If a +user wants more information (defaults) from the view/model, it should +be able to query for it. + +- This might be annoying to do, non-specified kwargs are pulled from + the rcParams object which is in turn created from reading a user + specified file and can be dynamically changed at run time. I + suppose we could keep a dict of default defaults and compare against + that. Not clear how this will interact with the style sheet + [[MEP26]] - @tacaswell Additional Notes: -* The `raw data` does not necessarily need to be a ``list``, ``ndarray``, etc. Rather, it can more abstractly just have a method to yield data when needed. +* The `raw data` does not necessarily need to be a ``list``, + ``ndarray``, etc. Rather, it can more abstractly just have a method + to yield data when needed. -* Because the ``Controller`` will contain extra information that users may not want to keep around, it should *not* be created by default. You should be able to both (a) instantiate a ``Controller`` with a figure and (b) build a figure with a ``Controller``. +* Because the ``Controller`` will contain extra information that users + may not want to keep around, it should *not* be created by + default. You should be able to both (a) instantiate a ``Controller`` + with a figure and (b) build a figure with a ``Controller``. Use Cases: * Export all necessary informat +* Serializing a matplotlib figure, saving it, and being able to rerun later. +* Any other source sending an appropriately formatted representation to matplotlib to open + +Examples +-------- +Here are some examples of what the controllers should be able to do. + +1. Instantiate a matplotlib figure from a serialized representation (e.g., JSON): :: + + import json + from matplotlib.controllers import Controller + with open('my_figure') as f: + o = json.load(f) + c = Controller(o) + fig = c.figure + +2. Manage artists from the controller (e.g., Line2D): :: + + # not really sure how this should look + c.axes[0].lines[0].color = 'b' + # ? + +3. Export serializable figure representation: :: + + o = c.to_json() + # or... we should be able to throw a figure object in there too + o = Controller.to_json(mpl_fig) + +Implementation +-------------- + +1. Create base ``Controller`` objects that are able to manage + ``Artist`` objects (e.g., ``Hist``) + + Comments: + + * initialization should happen via unpacking ``**``, so we need a + copy of call signature parameter for the ``Artist`` we're + ultimately trying to control. Unfortunate hard-coded + repetition... + * should the additional ``**kwargs`` accepted by each ``Artist`` + be tracked at the ``Controller`` + * how does a ``Controller`` know which artist belongs where? E.g., + do we need to pass ``axes`` references? + + Progress: + + * A simple NB demonstrating some functionality for + ``Line2DController`` objects: + http://nbviewer.ipython.org/gist/theengineear/f0aa8d79f64325e767c0 + +2. Write in protocols for the ``Controller`` to *update* the model. + + Comments: + + * how should containers be dealt with? E.g., what happens to old + patches when we re-bin a histogram? + * in the link from (1), the old line is completely destroyed and + redrawn, what if something is referencing it? + +3. Create method by which a json object can be assembled from the + ``Controllers`` +4. Deal with serializing the unserializable aspects of a figure (e.g., + non-affine transforms?) +5. Be able to instantiate from a serialized representation +6. Reimplement the existing pyplot and Axes method, + e.g. ``pyplot.hist`` and ``Axes.hist`` in terms of the new + controller class. + +> @theengineer: in #2 above, what do you mean by *get updates* from +each ``Artist``? + +^ Yup. The ``Controller`` *shouldn't* need to get updated. This just +happens in #3. Delete comments when you see this. + +Backward compatibility +---------------------- + +* pickling will change +* non-affine transformations will require a defined pickling method + +Alternatives +------------ + +PR #3150 suggested adding semantics by parasitically attaching extra +containers to axes objects. This is a more complete solution with what +should be a more developed/flexible/powerful framework.