PhilipElson/matplotlib — pull request #1 by PhilipElson (2012-02-06 17:06:56+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 (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:

* Projection objects needn't be subclasses of Axes, Transforms or any other
mpl base class, therefore it makes interfacing easier for third party
packages.

* 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.

* Implementing __call__ closes the potential future symmetry for other types of
matplotlib interfaces (_as_mpl_path, _as_mpl_transform etc.).

* 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.

* 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.

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,