docs: def deprecated(*optional_message):
      """This is a decorator which can be used to mark functions
      as deprecated. It will result in a warning being emitted
      when the function is used.
  
      Parameters
      ----------
      *optional_message : str
          an optional user level hint which should indicate which feature to use otherwise.
  
      """
      def _deprecated(func, *args, **kw):
          caller_stack = stack()[1:]
          while len(caller_stack) > 0:
              frame = caller_stack.pop(0)
              filename = frame[1]
              # skip callee frames if they are other decorators or this file(func)
              if 'decorator' in filename or __file__ in filename:
                  continue
              else: break
          lineno = frame[2]
          # avoid cyclic references!
          del caller_stack, frame
  
          user_msg = 'Call to deprecated function "%s". Called from %s line %i. %s' \
                     % (func.__name__, filename, lineno, msg)
  
          warnings.warn_explicit(
              user_msg,
              category=DeprecationWarning,
              filename=filename,
              lineno=lineno
          )
          return func(*args, **kw)
      if len(optional_message) == 1 and callable(optional_message[0]):
          # this is the function itself, decorate!
          msg = ""
          return decorate(optional_message[0], _deprecated)
      else:
          # actually got a message (or empty parenthesis)
          msg = optional_message[0] if len(optional_message) > 0 else ""
          return decorator(_deprecated)