MEP25: Serialization#

Status#

Rejected

This work is important, but this particular effort has stalled.

Branches and Pull requests#

  • development branches:

  • related pull requests:

Abstract#

This MEP aims at adding a serializableController objects to actas anArtist managers. Users would then communicate changes to anArtist via aController. In this way, functionality of theController objects may be added incrementally since eachArtist is still responsible for drawing everything. The goal is tocreate an API that is usable both by graphing libraries requiringhigh-level descriptions of figures and libraries requiring low-levelinterpretations.

Detailed description#

Matplotlib is a core plotting engine with an API that many usersalready understand. It's difficult/impossible for other graphinglibraries to (1) get a complete figure description, (2) output rawdata 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. Inaddition, because anArtist has no conception of its own semanticswithin the figure, it's difficult to interact with them in a naturalway.

In this sense, matplotlib will adopt a standardModel-View-Controller (MVC) framework. TheModel will be the userdefined data, style, and semantics. TheViews are the ensemble ofeach individualArtist, which are responsible for producing thefinal image based on themodel. TheController will be theController object managing its set ofArtist objects.

TheController must be able to export the information that it'scarrying about the figure on command, perhaps via ato_json methodor similar. Because it would be extremely extraneous to duplicate allof the information in the model with the controller, onlyuser-specified information (data + style) are explicitly kept. If auser wants more information (defaults) from the view/model, it shouldbe able to query for it.

  • This might be annoying to do, non-specified kwargs are pulled fromthe rcParams object which is in turn created from reading a userspecified file and can be dynamically changed at run time. Isuppose we could keep a dict of default defaults and compare againstthat. Not clear how this will interact with the style sheet[[MEP26]] - @tacaswell

Additional Notes:

  • The "raw data" does not necessarily need to be alist,ndarray, etc. Rather, it can more abstractly just have a methodto yield data when needed.

  • Because theController will contain extra information that usersmay not want to keep around, it shouldnot be created bydefault. You should be able to both (a) instantiate aControllerwith a figure and (b) build a figure with aController.

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):

    importjsonfrommatplotlib.controllersimportControllerwithopen('my_figure')asf: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 lookc.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 tooo=Controller.to_json(mpl_fig)

Implementation#

  1. Create baseController objects that are able to manageArtist objects (e.g.,Hist)

    Comments:

    • initialization should happen via unpacking**, so we need acopy of call signature parameter for theArtist we'reultimately trying to control. Unfortunate hard-codedrepetition...

    • should the additional**kwargs accepted by eachArtistbe tracked at theController

    • how does aController know which artist belongs where? E.g.,do we need to passaxes references?

    Progress:

  2. Write in protocols for theController toupdate the model.

    Comments:

    • how should containers be dealt with? E.g., what happens to oldpatches when we re-bin a histogram?

    • in the link from (1), the old line is completely destroyed andredrawn, what if something is referencing it?

  3. Create method by which a json object can be assembled from theControllers

  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 andAxes.hist in terms of the newcontroller class.

> @theengineer: in #2 above, what do you mean byget updates fromeachArtist?

^ Yup. TheControllershouldn't need to get updated. This justhappens 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 extracontainers to axes objects. This is a more complete solution with whatshould be a more developed/flexible/powerful framework.