.local/lib/python3.9/site-packages/pynvim/plugin/decorators.py

   1 """Decorators used by python host plugin system."""
   2
   3 import inspect
   4 import logging
   5
   6 from pynvim.compat import IS_PYTHON3, unicode_errors_default
   7
   8 logger = logging.getLogger(__name__)
   9 debug, info, warn = (logger.debug, logger.info, logger.warning,)
  10 __all__ = ('plugin', 'rpc_export', 'command', 'autocmd', 'function',
  11            'encoding', 'decode', 'shutdown_hook')
  12
  13
  14 def plugin(cls):
  15     """Tag a class as a plugin.
  16
  17     This decorator is required to make the class methods discoverable by the
  18     plugin_load method of the host.
  19     """
  20     cls._nvim_plugin = True
  21     # the _nvim_bind attribute is set to True by default, meaning that
  22     # decorated functions have a bound Nvim instance as first argument.
  23     # For methods in a plugin-decorated class this is not required, because
  24     # the class initializer will already receive the nvim object.
  25     predicate = lambda fn: hasattr(fn, '_nvim_bind')
  26     for _, fn in inspect.getmembers(cls, predicate):
  27         if IS_PYTHON3:
  28             fn._nvim_bind = False
  29         else:
  30             fn.im_func._nvim_bind = False
  31     return cls
  32
  33
  34 def rpc_export(rpc_method_name, sync=False):
  35     """Export a function or plugin method as a msgpack-rpc request handler."""
  36     def dec(f):
  37         f._nvim_rpc_method_name = rpc_method_name
  38         f._nvim_rpc_sync = sync
  39         f._nvim_bind = True
  40         f._nvim_prefix_plugin_path = False
  41         return f
  42     return dec
  43
  44
  45 def command(name, nargs=0, complete=None, range=None, count=None, bang=False,
  46             register=False, sync=False, allow_nested=False, eval=None):
  47     """Tag a function or plugin method as a Nvim command handler."""
  48     def dec(f):
  49         f._nvim_rpc_method_name = 'command:{}'.format(name)
  50         f._nvim_rpc_sync = sync
  51         f._nvim_bind = True
  52         f._nvim_prefix_plugin_path = True
  53
  54         opts = {}
  55
  56         if range is not None:
  57             opts['range'] = '' if range is True else str(range)
  58         elif count is not None:
  59             opts['count'] = count
  60
  61         if bang:
  62             opts['bang'] = ''
  63
  64         if register:
  65             opts['register'] = ''
  66
  67         if nargs:
  68             opts['nargs'] = nargs
  69
  70         if complete:
  71             opts['complete'] = complete
  72
  73         if eval:
  74             opts['eval'] = eval
  75
  76         if not sync and allow_nested:
  77             rpc_sync = "urgent"
  78         else:
  79             rpc_sync = sync
  80
  81         f._nvim_rpc_spec = {
  82             'type': 'command',
  83             'name': name,
  84             'sync': rpc_sync,
  85             'opts': opts
  86         }
  87         return f
  88     return dec
  89
  90
  91 def autocmd(name, pattern='*', sync=False, allow_nested=False, eval=None):
  92     """Tag a function or plugin method as a Nvim autocommand handler."""
  93     def dec(f):
  94         f._nvim_rpc_method_name = 'autocmd:{}:{}'.format(name, pattern)
  95         f._nvim_rpc_sync = sync
  96         f._nvim_bind = True
  97         f._nvim_prefix_plugin_path = True
  98
  99         opts = {
 100             'pattern': pattern
 101         }
 102
 103         if eval:
 104             opts['eval'] = eval
 105
 106         if not sync and allow_nested:
 107             rpc_sync = "urgent"
 108         else:
 109             rpc_sync = sync
 110
 111         f._nvim_rpc_spec = {
 112             'type': 'autocmd',
 113             'name': name,
 114             'sync': rpc_sync,
 115             'opts': opts
 116         }
 117         return f
 118     return dec
 119
 120
 121 def function(name, range=False, sync=False, allow_nested=False, eval=None):
 122     """Tag a function or plugin method as a Nvim function handler."""
 123     def dec(f):
 124         f._nvim_rpc_method_name = 'function:{}'.format(name)
 125         f._nvim_rpc_sync = sync
 126         f._nvim_bind = True
 127         f._nvim_prefix_plugin_path = True
 128
 129         opts = {}
 130
 131         if range:
 132             opts['range'] = '' if range is True else str(range)
 133
 134         if eval:
 135             opts['eval'] = eval
 136
 137         if not sync and allow_nested:
 138             rpc_sync = "urgent"
 139         else:
 140             rpc_sync = sync
 141
 142         f._nvim_rpc_spec = {
 143             'type': 'function',
 144             'name': name,
 145             'sync': rpc_sync,
 146             'opts': opts
 147         }
 148         return f
 149     return dec
 150
 151
 152 def shutdown_hook(f):
 153     """Tag a function or method as a shutdown hook."""
 154     f._nvim_shutdown_hook = True
 155     f._nvim_bind = True
 156     return f
 157
 158
 159 def decode(mode=unicode_errors_default):
 160     """Configure automatic encoding/decoding of strings."""
 161     def dec(f):
 162         f._nvim_decode = mode
 163         return f
 164     return dec
 165
 166
 167 def encoding(encoding=True):
 168     """DEPRECATED: use pynvim.decode()."""
 169     if isinstance(encoding, str):
 170         encoding = True
 171
 172     def dec(f):
 173         f._nvim_decode = encoding
 174         return f
 175     return dec