MAINT: Post-release deprecations

[larsoner]

Post-release deprecations, plus some comment rewordings so that after release this line:

clear; git grep [Dd]eprecat -- ':!*.js' ':!*/conftest.py' ':!*/docs.py' ':!*/test_docs.py' mne/

gives way fewer false alarms. I think going forward we should try to reserve variants of the term "deprecation" in our codebase to signal something that we need to change release-to-release as it makes things easier to find. After this PR it only shows:

mne/source_space/_source_space.py:# XXX this should probably be deprecated because it returns surface Labels,
mne/tests/test_docstring_parameters.py:                    and not hasattr(cf, "_deprecated_original")
mne/time_frequency/tfr.py:        layout=None,  # TODO deprecate? not used in orig implementation either
mne/time_frequency/tfr.py:        title=None,  # don't deprecate this one; has (useful) option title="auto"
mne/time_frequency/tfr.py:        title=None,  # TODO consider deprecating this one, or adding an "auto" option
mne/time_frequency/tfr.py:        vmin=None,  # TODO deprecate in favor of `vlim` (needs helper func refactor)
mne/time_frequency/tfr.py:        title=None,  # don't deprecate; topo titles aren't standard (color, size, just.)
mne/time_frequency/tfr.py:        layout=None,  # TODO deprecate; not used in orig implementation
mne/time_frequency/tfr.py:        title=None,  # don't deprecate this one; has (useful) option title="auto"
mne/time_frequency/tfr.py:        vmin=None,  # TODO deprecate in favor of `vlim` (needs helper func refactor)
mne/time_frequency/tfr.py:        title=None,  # don't deprecate; topo titles aren't standard (color, size, just.)
mne/utils/dataframe.py:    # E   DeprecationWarning: The copy keyword is deprecated and will be removed in a

which is actually the set of things we should consider thinking about after a release, like TODO items or in the case of dataframe.py checking if our min pandas version is high enough that we can remove the shim.

We could now consider starting to use the word deprecate to signal other stuff we should look at like other shims that are required for version-by-version changes in other libraries (e.g., typically / most often pandas, matplotlib).

[larsoner]

Also I noticed in our unification of README and pyproject etc. in #12890 we didn't document anywhere what our internal min (for whichever release is coming up next) is AFAIK. We used to have:

- `pandas <https://pandas.pydata.org>`__ ≥ 1.5.2

Here I've put pandas in there. We could consider explicit pins at some point, but for now comments seem okay. For now I've only added pandas since it's the only one where I removed a shim for < 1.5.

[drammock]

what's the downside to putting an explicit (non-comment) pin right now? Is it that the repo README will reflect pins that don't apply to current stable release? (doesn't seem that bad to me... when we add new deps we add them into pyproject.toml right away in the PR where they're needed so in general I expect the repo README to reflect main not PyPI 🤷🏻)

[larsoner]

Just that in most cases we are 99% compatible with older versions, and just a single test or two breaks, or some niche plotting function. But it's probably most standard to add an explicit lower bound so I'll do that

[larsoner]

I'm also trying some removals of warnings.catch_warnings, we'll see how many of them work 🤞

[drammock]

I think going forward we should try to reserve variants of the term "deprecation" in our codebase to signal something that we need to change release-to-release as it makes things easier to find.

+1 to this idea/effort. Not sure "Deprecation" is the right signal here. My ad-hoc practice includes comments like

mne-python/mne/time_frequency/tfr.py

Line 1190 in 05bd738

# shim for tfr_array_morlet deprecation warning (TODO: remove after 1.7 release)

which aren't really a deprecation... why not TODO as the signal? or something more specific like RELEASE TODO or TODO v1.9?

EDIT: I realize that the linked comment actually does contain the word "deprecation" but it could easily not have, and still made sense! E.g. something like "shim for matplotlib <2.1" or similar.

[larsoner]

Not sure "Deprecation" is the right signal here. My ad-hoc practice includes comments like ... why not TODO as the signal? or something more specific like RELEASE TODO or TODO v1.9?

Because of this:

$ git grep TODO | wc -l
     111

that's too many to have to go through every release, and most of them are longer-term or things we don't care about so imminently.

RELEASE TODO or something similar would be okay, though.

One advantage of deprecation is that we'll either need to check for that as well / separately (i.e., it becomes a separate step), or make sure any future deprecation-related stuff we add a RELEASE TODO or similar to as a reminder. I guess a separate step isn't so onerous especially since we can probably flag both with a suitable regex (which is what's used in the release Wiki anyway).

[drammock]

I guess a separate step isn't so onerous especially since we can probably flag both with a suitable regex

never mind my suggestion about RELEASE, it will cause a bunch of false alarms in mne/datasets/config.py and elsewhere. How about this?

git grep -iI "\(deprecat\|futurewarning\)" -- ':!*.js' ':!*/conftest.py' ':!*/docs.py' ':!*/test_docs.py' mne/

that has 62 hits vs 53 from yours, and seems at least slightly better in terms of not missing things that we likely want to change. Whatever you settle on, please add it to tools/dev/Makefile

[drammock]

what's the downside to putting an explicit (non-comment) pin right now? Is it that the repo README will reflect pins that don't apply to current stable release? (doesn't seem that bad to me... when we add new deps we add them into pyproject.toml right away in the PR where they're needed so in general I expect the repo README to reflect main not PyPI 🤷🏻)

[drammock]

❤️