Merge pull request #107 from sappelhoff/depr

deprecate resolve_stream

Author: cboulay

src/pylsl/resolve.py

@@ -2,7 +2,7 @@
 
 from .lib import lib
 from .info import StreamInfo
-from .util import FOREVER
+from .util import deprecated, FOREVER
 
 
 def resolve_streams(wait_time=1.0):
@@ -166,7 +166,12 @@ def results(self):
         return [StreamInfo(handle=buffer[k]) for k in range(num_found)]
 
 
+@deprecated("Use `resolve_streams` instead.")
 def resolve_stream(*args):
+    """Resolve a stream.
+
+    This function is deprecated. Use `resolve_streams` instead.
+    """
     if len(args) == 0:
         return resolve_streams()
     elif type(args[0]) in [int, float]:

src/pylsl/util.py

@@ -1,4 +1,6 @@
 import ctypes
+import functools
+import warnings
 
 from .lib import lib
 
@@ -108,3 +110,34 @@ def handle_error(errcode):
         raise InternalError("an internal error has occurred.")
     elif errcode < 0:
         raise RuntimeError("an unknown error has occurred.")
+
+
+def deprecated(reason: str = None):
+    """Mark functions as deprecated.
+
+    It will result in a warning being emitted when the function is used.
+
+    Example:
+        @deprecated("use new_function instead")
+        def old_function():
+            pass
+    """
+    def decorator(func):
+        message = f"Function '{func.__name__}' is deprecated."
+        if reason:
+            message += f" {reason}"
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.simplefilter("always", DeprecationWarning)  # ensure it shows up
+            warnings.warn(
+                message,
+                category=DeprecationWarning,
+                stacklevel=2
+            )
+            warnings.simplefilter("default", DeprecationWarning)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator