DEP: deprecate private but non-underscored signal.spline namespace

[rgommers]

See gh-14360 for details. This shows the approach for a small namespace that clearly was and is private.

I also noticed that some of these functions aren't even tested - let's ignore that for now (they probably should be deprecated outright, I'm not sure spline functionality in signal makes sense to begin with).

[rgommers]

Yep picked a great example - a C signature that cannot be moved to Python apparently:

scipy/signal/spline.py:8:22: invalid syntax
def cspline2d(input, lambda=0.0, precision=-1.0):
                     ^
##[error]Bash exited with code '1'

Let's ignore that for today, since this PR is mostly to illustrate what gh-14360 proposes.

[ilayn]

Makes sense to me. Maybe a bit neutral message at the top but empahsis on maybe.

[rgommers]

Okay these functions simply do not take keyword arguments at all:

>>> from scipy import signal, misc
>>> image = misc.face(gray=True).astype(np.float32)
>>> ck = signal.cspline2d(image, 8.0)  # example from signal tutorial
>>> ck = signal.cspline2d(image, lambda=8.0)
  File "<ipython-input-13-b8ade8846998>", line 1
    ck = signal.cspline2d(image, lambda=8.0)
                                       ^
SyntaxError: invalid syntax

>>> ck = signal.cspline2d(image, 8.0, -1.0)
>>> ck = signal.cspline2d(image, 8.0, precision=-1.0)
Traceback (most recent call last):
  File "<ipython-input-15-980c53dbf3d6>", line 1, in <module>
    ck = signal.cspline2d(image, 8.0, precision=-1.0)
TypeError: cspline2d() takes no keyword arguments

>>> qk = signal.qspline2d(image, 0.0)
>>> qk = signal.qspline2d(image, 0.1)  # any value other than 0.0 raises an exception
Traceback (most recent call last):
  File "<ipython-input-30-a51ff69afa47>", line 1, in <module>
    qk = signal.qspline2d(image, 0.1)
ValueError: Smoothing spline not yet implemented.

>>> signal.qspline2d(image, precision=-1.0)
Traceback (most recent call last):
  File "<ipython-input-33-3ecfefa69c4f>", line 1, in <module>
    signal.qspline2d(image, precision=-1.0)
TypeError: qspline2d() takes no keyword arguments

>>> qk = signal.qspline2d(image, 0.0, -1.0)

qspline2d code contains:

if (lambda != 0.0) PYERR("Smoothing spline not yet implemented.");

So we can rename the lambda keyword to something that's not a SyntaxError in Python.

[peterbell10]

How about using a module level __getattr__:

import warnings
from . import _spline

__all__ = ['cspline2d', 'qspline2d', 'sepfir2d', 'symiirorder1', 'symiirorder2']


def __dir__():
    return __all__


def __getattr__(name):
    if name not in __all__:
        raise AttributeError(
            f"scipy.signal.spline is deprecated and has no attribute {name}. "
            "Try looking in scipy.signal instead.")

    warnings.warn(f"Please use `{name}` from the `scipy.signal` namespace, "
                  "the `scipy.signal.spline` namespace is deprecated.",
                  category=DeprecationWarning, stacklevel=2)
    return getattr(_spline, name)

This saves some boiler plate code, and also makes from x import foo warn as well as calls through attribute access like spline.foo which isn't necessarily where the function is called. So, the stack trace will point directly to the site that needs to be changed.

It also reveals that bspline.py needs to be updated to import from the underscored module just after importing scipy and without needing tests to run.

[rgommers]

Nice idea! Agreed that that is more maintainable. It also avoids having to fiddle with docstrings.

[rgommers]

Lint failure is because flake8 does not yet understand getattr:

scipy/signal/spline.py:9:1 undefined name 'cspline2d' in __all__

This failure will go away when the PR is merged; it can be ignored. Everything else is green, so this PR should be good to go now.

[ilayn]

Looks good, thanks Ralf, Peter!

[rgommers]

I added a release note in https://github.com/scipy/scipy/wiki/Release-note-entries-for-SciPy-1.8.0.

[mdhaber]

@rgommers I'm seeing the lint failure in other PRs, e.g. gh-14454. Do they need to manually merge master? I thought only CircleCI doesn't do that automatically.

[peterbell10]

Hrm, it look like it's pyflakes that failing not lint_diff.py. I think we need to change from pyflakes to flake8 so it respects noqa comments, I'll open a PR for that.