Allow variable stacklevel for deprecation warnings.

[Carreau]

Each decoration needs to be manually checked, I have ideas on how to
make that better, by inspecting the above frames and look whether there
is a sentinel asking to add 1 to the stack number, but not tonight.

closes #6137

Alternative would be to use something like:

def extra_stack():
     import sys
     f = sys._getframe()
     fback = f.f_back
     count = 0
     while '__DEPRECATION_SKIP_STACK__' in fback.f_locals.keys():
         count +=1
         fback = fback.f_back
     return count

And mark corresponding decorators with __DEPRECATION_SKIP_STACK__ = 1.
or

def extra_stack(module_name='skimage'):
     import sys
     f = sys._getframe()
     fback = f.f_back
     count = 0
     while module_name in fback.f_global['__name__']:
         count +=1
         fback = fback.f_back
     return count

Which would always compute stacklevels so that deprecation warnings are emitted outside of skimage, potentially with a global toggle for skimage own CI Suite.

Description

Checklist

• Docstrings for all functions
• Gallery example in ./doc/examples (new features only)
• Benchmark in ./benchmarks, if your changes aren't covered by an
  existing benchmark
• Unit tests
• Clean style in the spirit of PEP8
• Descriptive commit messages (see below)

For reviewers

• Check that the PR title is short, concise, and will make sense 1 year
  later.
• Check that new functions are imported in corresponding __init__.py.
• Check that new features, API changes, and deprecations are mentioned in
  doc/release/release_dev.rst.

[pep8speaks]

Hello @Carreau! Thanks for opening this PR. We checked the lines you've touched for PEP 8 issues, and found:

• In the file skimage/_shared/utils.py:

Line 252:80: E501 line too long (94 > 79 characters)
Line 273:43: E226 missing whitespace around arithmetic operator
Line 287:73: E226 missing whitespace around arithmetic operator
Line 287:80: E501 line too long (95 > 79 characters)

• In the file skimage/feature/_hog.py:

Line 49:80: E501 line too long (80 > 79 characters)

• In the file skimage/filters/_unsharp_mask.py:

Line 19:80: E501 line too long (80 > 79 characters)

• In the file skimage/restoration/_cycle_spin.py:

Line 51:80: E501 line too long (80 > 79 characters)

• In the file skimage/restoration/_denoise.py:

Line 96:80: E501 line too long (80 > 79 characters)
Line 435:80: E501 line too long (80 > 79 characters)
Line 754:80: E501 line too long (80 > 79 characters)
Line 936:80: E501 line too long (80 > 79 characters)

• In the file skimage/restoration/inpaint.py:

Line 193:80: E501 line too long (80 > 79 characters)

• In the file skimage/restoration/non_local_means.py:

Line 13:80: E501 line too long (80 > 79 characters)

• In the file skimage/segmentation/slic_superpixels.py:

Line 112:80: E501 line too long (80 > 79 characters)

• In the file skimage/transform/pyramids.py:

Line 104:80: E501 line too long (80 > 79 characters)
Line 175:80: E501 line too long (80 > 79 characters)

[hmaarrfk]

i like the explicit parameter approach.

Adding additional global variables is tricky to get by correct, and I feel like it won't scale well with additional support for other interpreters.

i don't have time to read the code now in full but i do think it is an interesting approach.

the other thing i would say, i often as a keyword only argument in some of my functions called:

• _stacklevel_increment
  to allow one to forward warnings an arbitrary amount up the call stack.

[rfezzani]

Suggested change

	deprecated_version="0.19", extra_stacklevel=1)
	deprecated_version="0.19")

This is causing the CI failures: extra_stacklevel is defined for deprecate_kawarg

[rfezzani]

@Carreau, as an alternative, please see #6183 that defines a decorator's base class for storing the callstack length of each decorated function to automatically compute the correct warning stacklevel.

[mkcor]

@rfezzani please cherry-pick this for #6183 😉

[rfezzani]

Done, thank you 😉

[grlee77]

closing this as we ended up going with the approach in #6183. Thanks for initiating this work, @Carreau