refactor: replace nvim_out_write/nvim_err_write with nvim_echo #620

Problem:
nvim_out_write and nvim_err_write are deprecated since Nvim 0.11.

Solution:
- Replace internal usages `nvim_echo`. Use `ErrorMsg` highlight group
  instead of `opts.err`, for back-compat with older Nvim.
- Mark out_write() and err_write() as deprecated.

Close #588

Author: justinmk

docs/usage/remote-plugins.rst

@@ -30,7 +30,7 @@ Rplugins follow the structure of this example:
 
        @pynvim.autocmd('BufEnter', pattern='*.py', eval='expand("<afile>")', sync=True)
        def on_bufenter(self, filename):
-           self.nvim.out_write('testplugin is in ' + filename + '\n')
+           self.nvim.api.echo([['testplugin is in ' + filename]], True, {})
 
 If ``sync=True`` is supplied Neovim will wait for the handler to finish
 (this is required for function return values),

pynvim/api/nvim.py

@@ -12,6 +12,11 @@
 from typing import (Any, AnyStr, Callable, Dict, Iterator, List, Literal, Optional,
                     TYPE_CHECKING, Union)
 
+if sys.version_info >= (3, 13):
+    from warnings import deprecated
+else:
+    from typing_extensions import deprecated
+
 from msgpack import ExtType
 
 from pynvim.api.buffer import Buffer
@@ -177,12 +182,12 @@ def request(self, name: str, *args: Any, **kwargs: Any) -> Any:
         functions have python wrapper functions. The `api` object can
         be also be used to call API functions as methods:
 
-            vim.api.err_write('ERROR\n', async_=True)
+            vim.api.echo([['ERROR', 'ErrorMsg']], True, {}, async_=True)
             vim.current.buffer.api.get_mark('.')
 
         is equivalent to
 
-            vim.request('nvim_err_write', 'ERROR\n', async_=True)
+            vim.request('nvim_echo', [['ERROR', 'ErrorMsg']], True, {}, async_=True)
             vim.request('nvim_buf_get_mark', vim.current.buffer, '.')
 
 
@@ -417,13 +422,15 @@ def replace_termcodes(
         return self.request('nvim_replace_termcodes', string,
                             from_part, do_lt, special)
 
+    @deprecated('Use nvim.api.echo() instead.')
     def out_write(self, msg: str, **kwargs: Any) -> None:
         r"""Print `msg` as a normal message.
 
         The message is buffered (won't display) until linefeed ("\n").
         """
         return self.request('nvim_out_write', msg, **kwargs)
 
+    @deprecated('Use nvim.api.echo() instead.')
     def err_write(self, msg: str, **kwargs: Any) -> None:
         r"""Print `msg` as an error message.
 

pynvim/plugin/host.py

@@ -68,14 +68,14 @@ def __init__(self, nvim: Nvim):
 
     def _on_async_err(self, msg: str) -> None:
         # uncaught python exception
-        self.nvim.err_write(msg, async_=True)
+        self.nvim.request('nvim_echo', [[msg, 'ErrorMsg']], True, {}, async_=True)
 
     def _on_error_event(self, kind: Any, msg: str) -> None:
         # error from nvim due to async request
         # like nvim.command(..., async_=True)
-        errmsg = "{}: Async request caused an error:\n{}\n".format(
+        errmsg = "{}: Async request caused an error:\n{}".format(
             self.name, decode_if_bytes(msg))
-        self.nvim.err_write(errmsg, async_=True)
+        self.nvim.request('nvim_echo', [[errmsg, 'ErrorMsg']], True, {}, async_=True)
         return errmsg
 
     def start(self, plugins):
@@ -279,7 +279,7 @@ def _on_specs_request(self, path):
         path = decode_if_bytes(path)
         path = pathlib.Path(os.path.normpath(path)).as_posix()  # normalize path
         if path in self._load_errors:
-            self.nvim.out_write(self._load_errors[path] + '\n')
+            self.nvim.request('nvim_echo', [[self._load_errors[path]]], True, {})
         return self._specs.get(path, 0)
 
     def _configure_nvim_for(self, obj):

pynvim/plugin/script_host.py

@@ -64,6 +64,9 @@ def setup(self, nvim):
         info('redirect sys.stdout and sys.stderr')
         self.saved_stdout = sys.stdout
         self.saved_stderr = sys.stderr
+        # TODO(justinmk): out_write, err_write are deprecated, but
+        # script_host.py itself is deprecated by:
+        # https://github.com/neovim/pynvim/issues/567
         sys.stdout = RedirectStream(lambda data: nvim.out_write(data))
         sys.stderr = RedirectStream(lambda data: nvim.err_write(data))
 

pyproject.toml

@@ -15,7 +15,7 @@ requires-python = ">=3.10"
 dependencies = [
     "msgpack>=1.0.0",
     "greenlet>=3.0; python_implementation != 'PyPy'",
-    "typing-extensions>=4.5; python_version < '3.12'",
+    "typing-extensions>=4.5; python_version < '3.13'",
 ]
 
 classifiers = [

test/test_host.py

@@ -54,5 +54,5 @@ def test_host_async_error(vim):
     vim.command("lolwut", async_=True)
     event = vim.next_message()
     assert event[1] == 'nvim_error_event'
-    assert 'rplugin-host: Async request caused an error:\nboom\n' \
-           in h._on_error_event(None, 'boom')
+    errmsg = h._on_error_event(None, 'boom')
+    assert 'Async request caused an error:\nboom' in errmsg