Allow 'async' for backward-compatibility

This commit should be reverted sometime in the future.

Author: lambdalisue

neovim/api/buffer.py

@@ -1,6 +1,6 @@
 """API for working with a Nvim Buffer."""
 from .common import Remote
-from ..compat import IS_PYTHON3
+from ..compat import IS_PYTHON3, check_async
 
 
 __all__ = ('Buffer')
@@ -98,15 +98,17 @@ def range(self, start, end):
         return Range(self, start, end)
 
     def add_highlight(self, hl_group, line, col_start=0,
-                      col_end=-1, src_id=-1, async_=None):
+                      col_end=-1, src_id=-1, async_=None,
+                      **kwargs):
         """Add a highlight to the buffer."""
-        if async_ is None:
-            async_ = (src_id != 0)
+        async_ = check_async(async_, kwargs, src_id != 0)
         return self.request('nvim_buf_add_highlight', src_id, hl_group,
                             line, col_start, col_end, async_=async_)
 
-    def clear_highlight(self, src_id, line_start=0, line_end=-1, async_=True):
+    def clear_highlight(self, src_id, line_start=0, line_end=-1, async_=None,
+                        **kwargs):
         """Clear highlights from the buffer."""
+        async_ = check_async(async_, kwargs, True)
         self.request('nvim_buf_clear_highlight', src_id,
                      line_start, line_end, async_=async_)
 

neovim/compat.py

@@ -1,6 +1,7 @@
 """Code for supporting compatibility across python versions."""
 
 import sys
+import warnings
 from imp import find_module as original_find_module
 
 
@@ -36,3 +37,21 @@ def find_module(fullname, path):
     unicode_errors_default = 'strict'
 
 NUM_TYPES = (int, long, float)
+
+
+def check_async(async_, kwargs, default):
+    """Return a value of 'async' in kwargs or default when async_ is None
+
+    This helper function exists for backward compatibility (See #274).
+    It shows a warning message when 'async' in kwargs is used to note users.
+    """
+    if async_ is not None:
+        return async_
+    elif 'async' in kwargs:
+        warnings.warn(
+            '"async" attribute is deprecated. Use "async_" instead.',
+            DeprecationWarning,
+        )
+        return kwargs.pop('async')
+    else:
+        return default

neovim/msgpack_rpc/session.py

@@ -5,6 +5,8 @@
 
 import greenlet
 
+from ..compat import check_async
+
 logger = logging.getLogger(__name__)
 error, debug, info, warn = (logger.error, logger.debug, logger.info,
                             logger.warning,)
@@ -76,7 +78,7 @@ def request(self, method, *args, **kwargs):
         is sent instead. This will never block, and the return value or error
         is ignored.
         """
-        async_ = kwargs.pop('async_', False)
+        async_ = check_async(kwargs.pop('async_', None), kwargs, False)
         if async_:
             self._async_session.notify(method, args)
             return