I'm fine with this. However, I didn't even know mpl.finance existed!

Does anybody else have any feedback?

Yeah -- I wasn't aware of this either. I think finance should probably be put in the pyplot namespace (which then gets pulled into pylab) rather than putting in in pylab though. But all this is based on absolutely zero knowledge of how this is being used outside of matplotlib.

I thought maybe I was the one who introduced mpl.py, but it looks like it was John, back in 2007. I don't recall the rationale. I use it in quite a few places in my own code. I don't mind changing my own code to accomodate its removal--I can do it easily, and will do so in any case--but I do wonder whether some other misguided soul might be using it, and might be puzzled by its disappearance with no deprecation process. After all, it is a whole module, even though it is undocumented and trivial in its content. (It might have been introduced so that one could import core matplotlib modules without importing the legacy numerix module. I haven't tried to diagnose whether that is actually its effect. It is part of a changeset that was phasing out numerix. I was quite involved in all the comings and goings with numerix, Numeric, numarray, numpy, and the variations of masked arrays.)

@efiring Maybe add a warning just to be careful?

Yes, I think the way to remove mpl.py is by starting with a deprecation warning.

I agree. That will save us a lot of mailing list traffic if a lot of people are using it.

@ivanov Shall I close this PR in favour of a deprecation, or would you just like to update and rebase this one?

I'll update and rebase in a couple of hours, that does sound like a more
prudent approach

ok, I've added the deprecation warning. The only caveat now is that as of Python 2.7, DeprecationWarnings are ignored by default, and the flag to enable them (python -Wall or python -Wd) is not easily available in ipython, one has to do

python -Wall `which ipython`

@ivanov Awesome. Thanks. Regarding the DeprecationWarning, this seems relevant. In particular on the last paragraph of that section:

You can re-enable display of DeprecationWarning messages by running Python with the -Wdefault (short form: -Wd) switch, or by setting the PYTHONWARNINGS environment variable to "default" (or "d") before running Python. Python code can also re-enable them by calling warnings.simplefilter('default').

Should we add a warnings.simplefilter('default') to turn on the DeprecationWarning for mpl.py? I believe it's important for the user to see what API calls will break in the future, contrary to what that web page claims.

@dmcdougall thanks for that link, it seems the decision to silence DeperecationWarning was made without considering the fact that developers would want to use it to clearly signal upcoming changes in their library.

Here are a few options that I see, will seek broader feedback on mpl-devel list:

A) turn on warnings.simplefilter('default') in mpl.py, so only users of this module would see it

I don't think we want to turn on warnings.simplefilter('default') permanently on import of this module, since what may likely follow would be other DeperecationWarnings from other places. These, in turn, would be silenced again as soon as the user stopped importing matplotlib.mpl.

B) turn on warnings.simplefilter('default') in mpl.py, and turn them off again (for just this one warning)

This seems a bit inelegant, and does not solve our otherwise silenced DeperecationWarning`s in other places, there are about 40 others right now.

C) turn on warnings.simplefilter('default') in matplotlib's __init__.py

This gets all of matplotlib's DeperecationWarnings 'activated', but it will also activate them from other modules the user might be working with.

I think, overall, we should not be in the business of taking control away form the user - I'd be annoyed as a user to have to disable something matplotlib did on my behalf, especially when default python mechanisms for disabling or enabling warnings from the command line would be ignored after this.

D) make a MatplotlibDeperecationWarning class that inherits from UserWarning - and use it everywhere we currently use DeperecationWarning.

UserWarnings are still enabled by default, so these will make their way in front the eyeballs of our users. PR #1565 has an implemntation of this approach, it seems like the right one to me.

I agree with the suggestion to move to MatplotlibDeprecationWarning. Seems the cleanest thing to do. Be prepared for an onslaught of new warnings presented to our users ;) Maybe we want to add a "deprecations" page to the docs with some advice on how to fix each one? (Or maybe this could be a subsection of api_changes.rst?)

this can be merged after #1597, since it now utilizes the MatplotlibDeprecationWarning class. Also added documentation to API Changes about this deprecation, at @mdboom's suggestion

@ivanov The deprecations PR was merged, so this will need rebasing. However, before you do rebase it, we should think about when this should be deprecated. If we deprecate now (as in, for a 1.2.1 release), we run the risk of the deprecation not getting enough visibility if 1.3 rolls around quicker than expected. If we deprecate in 1.3 (which is what this PR is doing currently), mpl.py won't be removed until 1.4/2.0, and that might be a while. There's no 'correct' approach here, just two different ones with different outcomes.

I have never used mpl.py, so I'm not sure I have the necessary experience to give an objective suggestion.

Ok, thanks for the reminder to rebase. I don't see a reason to rush with removing this, even if we deprecate in 1.2.1, we probably shouldn't remove until 1.4 - I just wanted to see this go the way of the dodo at some point, and this will be a first important step toward that.

Actually, come to think of it, 1.2.1 is a bugfix release. Deprecating mpl.py doesn't fix a bug, so I think master is more appropriate, which is what you've done here.

oh yeah, I think I also had that thinking to begin with...

@ivanov, It looks like this unfortunately needs rebasing, after which it can be merged. I don't quite understand the bit about finance, but I trust you do and have handled it correctly.

Just a tiny nitpick: could you add the version of matplotlib when the removal of mpl will take place? I find this very useful both for users and developpers (the latter then being able to git grep the code in order to remove all deprecated stuff just before the release, instead of going through the git blame process to find out at which date the methods/module have been deprecated).

@NelleV Where do you think it should go? In the warning message?

@dmcdougall Yes, this way the users see it.

Numpydoc also recommands adding it to the docstring as the following example:

.. note:: Deprecated in Numpy 1.6
          `ndobj_old` will be removed in Numpy 2.0,

In the interest of getting this merged, I'm going to fork this branch to address @NelleV's concerns.

See #1670.

Resolved in #1670.