matplotlib/matplotlib — pull request #694 by PhilipElson (2012-02-06 18:19:04+00:00)
Title: Non string projection definitions

This is an update to the obsolete pull request https://github.com/matplotlib/matplotlib/pull/470.

Apart from using ```__call__```, I have implemented the recommendations suggested (by leejjoon)
(if this is not correct, it is not intentional and I would be happy to make any further
changes). The reasons for using ```_as_mpl_axes``` as an interface instead
of ```__call__``` are:

* Implementing the call of a projection object is not obvious that it should
return a tuple of Axes subclass & kwargs. At least for ```_as_mpl_axes``` the
behaviour is indexable in the documentation and would be easy to look up
what the agreed interface is.
* Projection objects needn't be subclasses of Axes, Transforms or any other
mpl base class, therefore it makes interfacing easier for third party
packages (their code will be easier to follow and they are free to do whatever
they desire with the ```__call__``` method.)
* Internally there is no benefit to calling the projection with () over
```_as_mpl_axes```, indeed, it makes it clearer to the reader what is expected of
the projection.
* Implementing ```__call__``` closes the potential future symmetry for other types of
matplotlib interfaces (```_as_mpl_path```, ```_as_mpl_patch```, ```_as_mpl_transform``` etc.).
* Pre-existing projections may have a better use of ```__call__``` (e.g. pyproj may
decide to extend its API to create a map from a projection, but it has
already used the ```__call__``` for transforming coordinates).
* Provides a consistent interface which similar in style to the ```__array_interface__``` of numpy.

------------------------

With the above changes, the trivial Polar projection object would then look like:

```
class Polar(object):
"""
Represents the polar projection, a Polar instance can be used to initialise
a polar plot in the standard ways, for example::

plt.axes(projection=Polar())

"""
def _as_mpl_axes(self):
# implement the matplotlib axes interface
return PolarAxes, {}
```

Although the whole point of this change is to be able to implement far more interesting (parameterisable) projections.

Many Thanks,