docs: def _wrap(func, msg):
      """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."""
  
      @functools.wraps(func)
      def new_func(*args, **kwargs):
          warnings.simplefilter('always', DeprecationWarning)     # turn off filter
          warnings.warn(msg, category=DeprecationWarning, stacklevel=2)
          warnings.simplefilter('default', DeprecationWarning)    # reset filter
          return func(*args, **kwargs)
      return new_func