Michael Droettboom <mdroe@...552...> writes:
Working with the documentation this past week has me a little
frustrated with the state of it. Enough to write a MEP.
In particular, it would be nice to compile a list of concerns about
the docstrings and documentation layout so that we can address as
much as possible in a single pass. Also, let me know if there are
any relevant PRs and Issues.
In particular, I think PR #1032, as it is a large structural
reorganization, my dovetail well with the proposed reorganization of
the docs.
Mike
The proposal looks great. I would like to comment on one issue that it touches,
and which I found very uncomfortable to work with as a newcomer. I think that
matplotlib style of using *args and **kwargs for delegation of arguments is a
rather bad practice, which is hard to solve by just updating documentation. It
breaks many rules of pep 20: it is implicit, since it is not allowing
introspection, it is nested, since it always involves nested calls, it allows
for alternative ways to do things, and I also don't think it's anyhow beautiful.
Most of the things passed with *args, **kwargs can be done with an added
function call, like:
points = ax.scatter(data)
points.update(*args, **kwargs)
What would be the disadvantage of abolishing this practice?
Anton
I understand the comments about the difficulty of introspection. The reason it works the way it does is so that additional parameters can be added to the artist layer without needing to update every single plotting function. A real world example of this is when hatching was added -- that feature only had to be added in one place and most artists were able to use it. In that sense, I think this approach is very beautiful in terms of code maintainability and extensibility.
I'm willing to consider this if there's a better suggestion, but I think pushing what is currently a single function call for the user in to two is not going to fly.
An alternative might be to have "style" objects that are passed to the plotting functions, and these style objects could grow new features over time. But that's going to break a lot of backward compatibility, of course.
Mike
···
On 08/26/2012 05:33 AM, Anton Akhmerov wrote:
Michael Droettboom <mdroe@...552...> writes:
Working with the documentation this past week has me a little
frustrated with the state of it. Enough to write a MEP.
Mep10 · matplotlib/matplotlib Wiki · GitHub
In particular, it would be nice to compile a list of concerns about
the docstrings and documentation layout so that we can address as
much as possible in a single pass. Also, let me know if there are
any relevant PRs and Issues.
In particular, I think PR #1032, as it is a large structural
reorganization, my dovetail well with the proposed reorganization of
the docs.
Mike
The proposal looks great. I would like to comment on one issue that it touches,
and which I found very uncomfortable to work with as a newcomer. I think that
matplotlib style of using *args and **kwargs for delegation of arguments is a
rather bad practice, which is hard to solve by just updating documentation. It
breaks many rules of pep 20: it is implicit, since it is not allowing
introspection, it is nested, since it always involves nested calls, it allows
for alternative ways to do things, and I also don't think it's anyhow beautiful.
Most of the things passed with *args, **kwargs can be done with an added
function call, like:
points = ax.scatter(data)
points.update(*args, **kwargs)
What would be the disadvantage of abolishing this practice?
I'm jumping into this conversation a bit late, but from Python 3.3 it
will be possible to set a __signature__ attribute on a function, using
a Signature object which can be programmatically generated. So it
should be possible, with a bit of legwork, to introspect pass-through
parameters without having to manually declare them at the highest
level.
The details are here:
Thanks,
Thomas
···
On 26 August 2012 18:19, Michael Droettboom <mdroe@...31...> wrote:
I understand the comments about the difficulty of introspection. The
reason it works the way it does is so that additional parameters can be
added to the artist layer without needing to update every single
plotting function. A real world example of this is when hatching was
added -- that feature only had to be added in one place and most artists
were able to use it. In that sense, I think this approach is very
beautiful in terms of code maintainability and extensibility.