Merge pull request #7900 from larsoner/windows

API: Soft deprecate signal.* windows

doc/API.rst.txt

@@ -8,20 +8,20 @@ objects.  Occasionally this may be convenient, but be aware that if you do so
 your code may break without warning in future releases.  Some widely understood
 rules for what is and isn't public in Python are:
 
-  - Methods / functions / classes and module attributes whose names begin 
+  - Methods / functions / classes and module attributes whose names begin
     with a leading underscore are private.
-  - If a class name begins with a leading underscore none of its members are 
+  - If a class name begins with a leading underscore none of its members are
     public, whether or not they begin with a leading underscore.
-  - If a module name in a package begins with a leading underscore none of 
+  - If a module name in a package begins with a leading underscore none of
     its members are public, whether or not they begin with a leading
     underscore.
   - If a module or package defines ``__all__`` that authoritatively defines the
     public interface.
-  - If a module or package doesn't define ``__all__`` then all names that don't 
+  - If a module or package doesn't define ``__all__`` then all names that don't
     start with a leading underscore are public.
 
 .. note:: Reading the above guidelines one could draw the conclusion that every
-          private module or object starts with an underscore.  This is not the 
+          private module or object starts with an underscore.  This is not the
           case; the presence of underscores do mark something as private, but
           the absence of underscores do not mark something as public.
 
@@ -120,6 +120,8 @@ change is made.
 
 * scipy.signal
 
+  - windows
+
 * scipy.sparse
 
   - linalg

doc/source/signal.windows.rst

@@ -0,0 +1 @@
+.. automodule:: scipy.signal.windows

scipy/__init__.py

@@ -31,6 +31,7 @@
  odr                          --- Orthogonal Distance Regression
  optimize                     --- Optimization Tools
  signal                       --- Signal Processing Tools
+ signal.windows               --- Window functions
  sparse                       --- Sparse Matrices
  sparse.linalg                --- Sparse Linear Algebra
  sparse.linalg.dsolve         --- Linear Solvers

scipy/signal/__init__.py

@@ -222,31 +222,35 @@
 Window functions
 ================
 
+Most window functions are available in the `scipy.signal.windows` namespace,
+but we list them here for convenience:
+
 .. autosummary::
    :toctree: generated/
 
-   get_window        -- Return a window of a given length and type.
-   barthann          -- Bartlett-Hann window
-   bartlett          -- Bartlett window
-   blackman          -- Blackman window
-   blackmanharris    -- Minimum 4-term Blackman-Harris window
-   bohman            -- Bohman window
-   boxcar            -- Boxcar window
-   chebwin           -- Dolph-Chebyshev window
-   cosine            -- Cosine window
-   exponential       -- Exponential window
-   flattop           -- Flat top window
-   gaussian          -- Gaussian window
-   general_gaussian  -- Generalized Gaussian window
-   hamming           -- Hamming window
-   hann              -- Hann window
-   hanning           -- Hann window
-   kaiser            -- Kaiser window
-   nuttall           -- Nuttall's minimum 4-term Blackman-Harris window
-   parzen            -- Parzen window
-   slepian           -- Slepian window
-   triang            -- Triangular window
-   tukey             -- Tukey window
+   get_window                -- Return a window of a given length and type.
+
+   windows.barthann          -- Bartlett-Hann window
+   windows.bartlett          -- Bartlett window
+   windows.blackman          -- Blackman window
+   windows.blackmanharris    -- Minimum 4-term Blackman-Harris window
+   windows.bohman            -- Bohman window
+   windows.boxcar            -- Boxcar window
+   windows.chebwin           -- Dolph-Chebyshev window
+   windows.cosine            -- Cosine window
+   windows.exponential       -- Exponential window
+   windows.flattop           -- Flat top window
+   windows.gaussian          -- Gaussian window
+   windows.general_gaussian  -- Generalized Gaussian window
+   windows.hamming           -- Hamming window
+   windows.hann              -- Hann window
+   windows.hanning           -- Hann window
+   windows.kaiser            -- Kaiser window
+   windows.nuttall           -- Nuttall's minimum 4-term Blackman-Harris window
+   windows.parzen            -- Parzen window
+   windows.slepian           -- Slepian window
+   windows.triang            -- Triangular window
+   windows.tukey             -- Tukey window
 
 Wavelets
 ========
@@ -292,7 +296,7 @@
 """
 from __future__ import division, print_function, absolute_import
 
-from . import sigtools
+from . import sigtools, windows
 from .waveforms import *
 from ._max_len_seq import max_len_seq
 from ._upfirdn import upfirdn
@@ -306,12 +310,52 @@
 from .fir_filter_design import *
 from .ltisys import *
 from .lti_conversion import *
-from .windows import *
 from .signaltools import *
 from ._savitzky_golay import savgol_coeffs, savgol_filter
 from .spectral import *
 from .wavelets import *
 from ._peak_finding import *
+from .windows import get_window  # keep this one in signal namespace
+
+
+# deal with * -> windows.* deprecation
+deprecated_windows = ('boxcar', 'triang', 'parzen', 'bohman', 'blackman',
+                      'nuttall', 'blackmanharris', 'flattop', 'bartlett',
+                      'hanning', 'barthann', 'hamming', 'kaiser', 'gaussian',
+                      'general_gaussian', 'chebwin', 'slepian', 'cosine',
+                      'hann', 'exponential', 'tukey')
+
+
+def deco(name):
+    f = getattr(windows, name)
+    # Add deprecation to docstring
+
+    def wrapped(*args, **kwargs):
+        return f(*args, **kwargs)
+
+    wrapped.__name__ = name
+
+    if f.__doc__ is not None:
+        lines = f.__doc__.splitlines()
+        for li, line in enumerate(lines):
+            if line.strip() == 'Parameters':
+                break
+        else:
+            raise RuntimeError('dev error: badly formatted doc')
+        spacing = ' ' * line.find('P')
+        lines.insert(li, ('{0}.. warning:: scipy.signal.{1} is deprecated,\n'
+                          '{0}             use scipy.signal.windows.{1} '
+                          'instead.\n'.format(spacing, name)))
+        wrapped.__doc__ = '\n'.join(lines)
+
+    return wrapped
+
+
+for name in deprecated_windows:
+    locals()[name] = deco(name)
+
+del deprecated_windows, name, deco
+
 
 __all__ = [s for s in dir() if not s.startswith('_')]
 

scipy/signal/setup.py

@@ -10,6 +10,8 @@ def configuration(parent_package='', top_path=None):
 
     config.add_data_dir('tests')
 
+    config.add_subpackage('windows')
+
     config.add_extension('sigtools',
                          sources=['sigtoolsmodule.c', 'firfilter.c',
                                   'medianfilter.c', 'lfilter.c.src',

scipy/signal/tests/test_signaltools.py

@@ -21,10 +21,11 @@
 from scipy.optimize import fmin
 from scipy import signal
 from scipy.signal import (
-    correlate, convolve, convolve2d, fftconvolve, hann, choose_conv_method,
+    correlate, convolve, convolve2d, fftconvolve, choose_conv_method,
     hilbert, hilbert2, lfilter, lfilter_zi, filtfilt, butter, zpk2tf, zpk2sos,
     invres, invresz, vectorstrength, lfiltic, tf2sos, sosfilt, sosfiltfilt,
     sosfilt_zi, tf2zpk, BadCoefficients)
+from scipy.signal.windows import hann
 from scipy.signal.signaltools import _filtfilt_gust
 
 
@@ -1721,13 +1722,13 @@ def _test_phaseshift(self, method, zero_phase):
         # Sinusoids at 0.8*nyquist, windowed to avoid edge artifacts
         freqs = np.array(rates_to) * 0.8 / 2
         d = (np.exp(1j * 2 * np.pi * freqs[:, np.newaxis] * t)
-             * signal.tukey(t.size, 0.1))
+             * signal.windows.tukey(t.size, 0.1))
 
         for rate_to in rates_to:
             q = rate // rate_to
             t_to = np.arange(rate_to*t_tot+1) / float(rate_to)
             d_tos = (np.exp(1j * 2 * np.pi * freqs[:, np.newaxis] * t_to)
-                     * signal.tukey(t_to.size, 0.1))
+                     * signal.windows.tukey(t_to.size, 0.1))
 
             # Set up downsampling filters, match v0.17 defaults
             if method == 'fir':