plugins/python/nbdkit-python-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-python-plugin - nbdkit python plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit python /path/to/plugin.py [arguments...]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-python-plugin> is an embedded Python interpreter for
  12 L<nbdkit(1)>, allowing you to write nbdkit plugins in Python.
  13
  14 =head2 If you have been given an nbdkit Python plugin
  15
  16 Assuming you have a Python script which is an nbdkit plugin, you run it
  17 like this:
  18
  19  nbdkit python /path/to/plugin.py
  20
  21 You may have to add further C<key=value> arguments to the command
  22 line.  Read the Python script to see if it requires any.
  23
  24 =head1 WRITING A PYTHON NBDKIT PLUGIN
  25
  26 For an example plugin written in Python, see:
  27 L<https://github.com/libguestfs/nbdkit/blob/master/plugins/python/example.py>
  28
  29 Broadly speaking, Python nbdkit plugins work like C ones, so you should
  30 read L<nbdkit-plugin(3)> first.
  31
  32 To write a Python nbdkit plugin, you create a Python file which
  33 contains at least the following required functions (in the top level
  34 C<__main__> module):
  35
  36  API_VERSION = 2
  37  def open(readonly):
  38    # see below
  39  def get_size(h):
  40    # see below
  41  def pread(h, buf, offset, flags):
  42    # see below
  43
  44 Note that the subroutines must have those literal names (like C<open>),
  45 because the C part looks up and calls those functions directly.  You
  46 may want to include documentation and globals (eg. for storing global
  47 state).  Any other top level statements are run when the script is
  48 loaded, just like ordinary Python.
  49
  50 =head2 Python versions
  51
  52 In B<nbdkit E<le> 1.14>, either Python 2 or 3 could be used.  It was
  53 selected at compile time by either:
  54
  55  ./configure
  56
  57 which selected the version of Python by looking at the C<python>
  58 interpreter found on the C<$PATH>.  Or:
  59
  60  ./configure PYTHON=/usr/bin/python3
  61
  62 which allowed you to select a different interpreter and hence a
  63 different version of Python.
  64
  65 B<nbdkit E<ge> 1.16> drops all support for Python 2, since Python 2
  66 has reached its end of life.
  67
  68 The new behaviour is that C<./configure> looks for C<python3> or
  69 C<python> (in that order) on the C<$PATH>.  It will fail if the first
  70 interpreter it finds is a Python 2 interpreter.  You may also still
  71 choose a Python interpreter by setting the C<PYTHON> variable at
  72 configure time as above.
  73
  74 If you wish to continue using nbdkit plugins written in Python 2 then
  75 you must use nbdkit E<le> 1.14, but we would advise you to update your
  76 plugins.
  77
  78 To find out which version the Python plugin was compiled for, use the
  79 I<--dump-plugin> option, eg:
  80
  81  $ nbdkit python --dump-plugin
  82  ...
  83  python_version=3.7.0
  84  python_pep_384_abi_version=3
  85
  86 =head2 API versions
  87
  88 The nbdkit API has evolved and new versions are released periodically.
  89 To ensure backwards compatibility plugins have to opt in to the new
  90 version.  From Python you do this by declaring a constant in your
  91 module:
  92
  93  API_VERSION = 2
  94
  95 (where 2 is the latest version at the time this documentation was
  96 written).  All newly written Python modules must have this constant.
  97
  98 =head2 Executable script
  99
 100 If you want you can make the script executable and include a "shebang"
 101 at the top:
 102
 103  #!/usr/sbin/nbdkit python
 104
 105 See also L<nbdkit(1)/Shebang scripts>.
 106
 107 These scripts can also be installed in the C<$plugindir>.  See
 108 L<nbdkit-plugin(3)/WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES>.
 109
 110 =head2 Methods
 111
 112 Your script may use C<import nbdkit> to have access to the following
 113 methods in the C<nbdkit> module:
 114
 115  nbdkit.set_error(err)
 116
 117 Record C<err> as the reason you are about to throw an exception. C<err>
 118 should correspond to usual errno values, where it may help to
 119 C<import errno>.
 120
 121 =head2 Exceptions
 122
 123 Python callbacks should throw exceptions to indicate errors.  Remember
 124 to use C<nbdkit.set_error> if you need to control which error is sent
 125 back to the client; if omitted, the client will see an error of C<EIO>.
 126
 127 =head2 Python callbacks
 128
 129 This just documents the arguments to the callbacks in Python, and any
 130 way that they differ from the C callbacks.  In all other respects they
 131 work the same way as the C callbacks, so you should go and read
 132 nbdkit-plugin(3).
 133
 134 =over 4
 135
 136 =item C<dump_plugin>
 137
 138 (Optional)
 139
 140 There are no arguments or return value.
 141
 142 =item C<config>
 143
 144 (Optional)
 145
 146  def config(key, value):
 147    # no return value
 148
 149 =item C<config_complete>
 150
 151 (Optional)
 152
 153 There are no arguments or return value.
 154
 155 =item C<open>
 156
 157 (Required)
 158
 159  def open(readonly):
 160    # return handle
 161
 162 You can return any non-NULL Python value as the handle.  It is passed
 163 back in subsequent calls.
 164
 165 =item C<close>
 166
 167 (Optional)
 168
 169  def close(h):
 170    # no return value
 171
 172 After C<close> returns, the reference count of the handle is
 173 decremented in the C part, which usually means that the handle and its
 174 contents will be garbage collected.
 175
 176 =item C<get_size>
 177
 178 (Required)
 179
 180  def get_size(h):
 181    # return the size of the disk
 182
 183 =item C<is_rotational>
 184
 185 (Optional)
 186
 187  def is_rotational(h):
 188    # return a boolean
 189
 190 =item C<can_multi_conn>
 191
 192 (Optional)
 193
 194  def can_multi_conn(h):
 195    # return a boolean
 196
 197 =item C<can_write>
 198
 199 (Optional)
 200
 201  def can_write(h):
 202    # return a boolean
 203
 204 =item C<can_flush>
 205
 206 (Optional)
 207
 208  def can_flush(h):
 209    # return a boolean
 210
 211 =item C<can_trim>
 212
 213 (Optional)
 214
 215  def can_trim(h):
 216    # return a boolean
 217
 218 =item C<can_zero>
 219
 220 (Optional)
 221
 222  def can_zero(h):
 223    # return a boolean
 224
 225 =item C<can_fast_zero>
 226
 227 (Optional)
 228
 229  def can_fast_zero(h):
 230    # return a boolean
 231
 232 =item C<can_fua>
 233
 234 (Optional)
 235
 236  def can_fua(h):
 237    # return nbdkit.FUA_NONE or nbdkit.FUA_EMULATE
 238    # or nbdkit.FUA_NATIVE
 239
 240 =item C<can_cache>
 241
 242 (Optional)
 243
 244  def can_cache(h):
 245    # return nbdkit.CACHE_NONE or nbdkit.CACHE_EMULATE
 246    # or nbdkit.CACHE_NATIVE
 247
 248 =item C<init_sparse>
 249
 250 (Optional)
 251
 252  def init_sparse(h):
 253    # return a boolean
 254
 255 =item C<init_zero>
 256
 257 (Optional)
 258
 259  def init_zero(h):
 260    # return a boolean
 261
 262 =item C<pread>
 263
 264 (Required)
 265
 266  def pread(h, buf, offset, flags):
 267    # read into the buffer
 268
 269 The body of your C<pread> function should read exactly C<len(buf)>
 270 bytes of data starting at disk C<offset> and write it into the buffer
 271 C<buf>.  C<flags> is always 0.
 272
 273 NBD only supports whole reads, so your function should try to read
 274 the whole region (perhaps requiring a loop).  If the read fails or
 275 is partial, your function should throw an exception, optionally using
 276 C<nbdkit.set_error> first.
 277
 278 =item C<pwrite>
 279
 280 (Optional)
 281
 282  def pwrite(h, buf, offset, flags):
 283    length = len (buf)
 284    # no return value
 285
 286 The body of your C<pwrite> function should write the buffer C<buf> to
 287 the disk.  You should write C<count> bytes to the disk starting at
 288 C<offset>.  C<flags> may contain C<nbdkit.FLAG_FUA>.
 289
 290 NBD only supports whole writes, so your function should try to
 291 write the whole region (perhaps requiring a loop).  If the write
 292 fails or is partial, your function should throw an exception,
 293  optionally using C<nbdkit.set_error> first.
 294
 295 =item C<flush>
 296
 297 (Optional)
 298
 299  def flush(h, flags):
 300    # no return value
 301
 302 The body of your C<flush> function should do a L<sync(2)> or
 303 L<fdatasync(2)> or equivalent on the backing store.
 304 C<flags> is always 0.
 305
 306 If the flush fails, your function should throw an exception, optionally
 307 using C<nbdkit.set_error> first.
 308
 309 =item C<trim>
 310
 311 (Optional)
 312
 313  def trim(h, count, offset, flags):
 314    # no return value
 315
 316 The body of your C<trim> function should "punch a hole" in the backing
 317 store.  C<flags> may contain C<nbdkit.FLAG_FUA>.  If the trim fails,
 318 your function should throw an exception, optionally using
 319 C<nbdkit.set_error> first.
 320
 321 =item C<zero>
 322
 323 (Optional)
 324
 325  def zero(h, count, offset, flags):
 326    # no return value
 327
 328 The body of your C<zero> function should ensure that C<count> bytes of
 329 the disk, starting at C<offset>, will read back as zero.  C<flags> is
 330 a bitmask which may include C<nbdkit.FLAG_MAY_TRIM>,
 331 C<nbdkit.FLAG_FUA>, C<nbdkit.FLAG_FAST_ZERO>.
 332
 333 NBD only supports whole writes, so your function should try to
 334 write the whole region (perhaps requiring a loop).
 335
 336 If the write fails or is partial, your function should throw an
 337 exception, optionally using C<nbdkit.set_error> first.  In particular,
 338 if you would like to automatically fall back to C<pwrite> (perhaps
 339 because there is nothing to optimize if
 340 S<C<flags & nbdkit.FLAG_MAY_TRIM>> is false), use
 341 S<C<nbdkit.set_error (errno.EOPNOTSUPP)>>.
 342
 343 =item C<cache>
 344
 345 (Optional)
 346
 347  def cache(h, count, offset, flags):
 348    # no return value
 349
 350 The body of your C<cache> function should prefetch data in the
 351 indicated range.
 352
 353 If the cache operation fails, your function should throw an exception,
 354 optionally using C<nbdkit.set_error> first.
 355
 356 =back
 357
 358 =head2 Missing callbacks
 359
 360 =over 4
 361
 362 =item Missing: C<load> and C<unload>
 363
 364 These are not needed because you can just use ordinary Python
 365 constructs.
 366
 367 =item Missing: C<thread_model>
 368
 369 See L</Threads> below.
 370
 371 =item Missing:
 372 C<name>,
 373 C<version>,
 374 C<longname>,
 375 C<description>,
 376 C<config_help>,
 377 C<magic_config_key>,
 378 C<can_extents>,
 379 C<extents>.
 380
 381 These are not yet supported.
 382
 383 =back
 384
 385 =head2 Threads
 386
 387 The thread model for Python callbacks currently cannot be set from
 388 Python.  It is hard-coded in the C part to
 389 C<NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS>.  This may change or be
 390 settable in future.
 391
 392 =head1 FILES
 393
 394 =over 4
 395
 396 =item F<$plugindir/nbdkit-python-plugin.so>
 397
 398 The plugin.
 399
 400 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 401
 402 =back
 403
 404 =head1 VERSION
 405
 406 C<nbdkit-python-plugin> first appeared in nbdkit 1.2.
 407
 408 =head1 SEE ALSO
 409
 410 L<nbdkit(1)>,
 411 L<nbdkit-plugin(3)>,
 412 L<python(1)>.
 413
 414 =head1 AUTHORS
 415
 416 Eric Blake
 417
 418 Richard W.M. Jones
 419
 420 Nir Soffer
 421
 422 =head1 COPYRIGHT
 423
 424 Copyright (C) 2013-2019 Red Hat Inc.