class_docstr: A ImageIO Plugin.
  
  This is an abstract plugin that documents the v3 plugin API interface. A
  plugin is an adapter/wrapper around a backend that converts a request from
  iio.core (e.g., read an image from file) into a sequence of instructions for
  the backend that fulfill the request.
  
  Plugin authors may choose to subclass this class when implementing a new
  plugin, but aren't obliged to do so. As long as the plugin class implements
  the interface (methods) described below the ImageIO core will treat it just
  like any other plugin.
  
  
  Parameters
  ----------
  request : iio.Request
      A request object that represents the users intent. It provides a
      standard interface to access the various ImageResources and serves them
      to the plugin as a file object (or file). Check the docs for details.
  **kwargs : Any
      Additional configuration arguments for the plugin or backend. Usually
      these match the configuration arguments available on the backend and
      are forwarded to it.
  
  
  Raises
  ------
  InitializationError
      During ``__init__`` the plugin tests if it can fulfill the request. If
      it can't, e.g., because the request points to a file in the wrong
      format, then it should raise an ``InitializationError`` and provide a
      reason for failure. This reason may be reported to the user.
  ImportError
      Plugins will be imported dynamically when listed in
      ``iio.config.known_plugins`` to fulfill requests. This way, users only
      have to load plugins/backends they actually use. If this plugin's backend
      is not installed, it should raise an ``ImportError`` either during
      module import or during class construction.
  
  Notes
  -----
  Upon successful construction the plugin takes ownership of the provided
  request. This means that it is the plugin's responsibility to call
  request.finish() to close the resource when it is no longer needed.
  
  Plugins _must_ implement a context manager that closes and cleans any
  resources held by the plugin upon exit.
class_docstr_tok: ["A","ImageIO","Plugin",".","This","is","an","abstract","plugin","that","documents","the","v3","plugin","API","interface",".","A","plugin","is","an","adapter\/wrapper","around","a","backend","that","converts","a","request","from","iio.core","(","e.g.",",","read","an","image","from","file",")","into","a","sequence","of","instructions","for","the","backend","that","fulfill","the","request",".","Plugin","authors","may","choose","to","subclass","this","class","when","implementing","a","new","plugin",",","but","are","n't","obliged","to","do","so",".","As","long","as","the","plugin","class","implements","the","interface","(","methods",")","described","below","the","ImageIO","core","will","treat","it","just","like","any","other","plugin",".","Parameters","--","--","--","--","--","request",":","iio.Request","A","request","object","that","represents","the","users","intent",".","It","provides","a","standard","interface","to","access","the","various","ImageResources","and","serves","them","to","the","plugin","as","a","file","object","(","or","file",")",".","Check","the","docs","for","details",".","*","*","kwargs",":","Any","Additional","configuration","arguments","for","the","plugin","or","backend",".","Usually","these","match","the","configuration","arguments","available","on","the","backend","and","are","forwarded","to","it",".","Raises","--","--","--","InitializationError","During","``","__init__","``","the","plugin","tests","if","it","can","fulfill","the","request",".","If","it","ca","n't",",","e.g.",",","because","the","request","points","to","a","file","in","the","wrong","format",",","then","it","should","raise","an","``","InitializationError","``","and","provide","a","reason","for","failure",".","This","reason","may","be","reported","to","the","user",".","ImportError","Plugins","will","be","imported","dynamically","when","listed","in","``","iio.config.known_plugins","``","to","fulfill","requests",".","This","way",",","users","only","have","to","load","plugins\/backends","they","actually","use",".","If","this","plugin","'s","backend","is","not","installed",",","it","should","raise","an","``","ImportError","``","either","during","module","import","or","during","class","construction",".","Notes","--","--","-","Upon","successful","construction","the","plugin","takes","ownership","of","the","provided","request",".","This","means","that","it","is","the","plugin","'s","responsibility","to","call","request.finish","(",")","to","close","the","resource","when","it","is","no","longer","needed",".","Plugins","_must_","implement","a","context","manager","that","closes","and","cleans","any","resources","held","by","the","plugin","upon","exit","."]
docstr: Write a ndimage to a ImageResource.
  
  The ``write`` method encodes the given ndimage into the format handled
  by the backend and writes it to the ImageResource. It overwrites
  any content that may have been previously stored in the file.
  
  If the backend supports only a single format then it must check if
  the ImageResource matches that format and raise an exception if not.
  Typically, this should be done during initialization in the form of a
  ``InitializationError``.
  
  If the backend supports more than one format it must determine the
  requested/desired format. Usually this can be done by inspecting the
  ImageResource (e.g., by checking ``request.extension``), or by providing
  a mechanism to explicitly set the format (perhaps with a - sensible -
  default value). If the plugin can not determine the desired format, it
  **must not** write to the ImageResource, but raise an exception instead.
  
  If the backend supports at least one format that can hold multiple
  ndimages it should be capable of handling ndimage batches and lists of
  ndimages. If the ``ndimage`` input is a list of ndimages, the plugin
  should not assume that the ndimages are not stackable, i.e., ndimages
  may have different shapes. Otherwise, the ``ndimage`` may be a batch of
  multiple ndimages stacked along the first axis of the array. The plugin
  must be able to discover this, either automatically or via additional
  `kwargs`. If there is ambiguity in the process, the plugin must clearly
  document what happens in such cases and, if possible, describe how to
  resolve this ambiguity.
  
  Parameters
  ----------
  ndimage : ArrayLike
      The ndimage to encode and write to the current ImageResource.
  **kwargs : Any
      The write method may accept any number of plugin-specific keyword
      arguments to customize the writing behavior. Usually these match the
      arguments available on the backend and are forwarded to it.
  
  Returns
  -------
  encoded_image : bytes or None
      If the chosen ImageResource is the special target ``"<bytes>"`` then
      write should return a byte string containing the encoded image data.
      Otherwise, it returns None.
  
  Notes
  -----
  The ImageResource to which the plugin should write to is managed by the
  provided request object. Directly accessing the managed ImageResource is
  _not_ permitted. Instead, you can get FileLike access to the
  ImageResource via request.get_file().
  
  If the backend doesn't support writing to FileLike objects, you can
  request a temporary file to pass to the backend via
  ``request.get_local_filename()``. This is, however, not very performant
  (involves copying the Request's content from a temporary file), so you
  should avoid doing this whenever possible. Consider it a fallback method
  in case all else fails.
docstr_tok: ["Write","a","ndimage","to","a","ImageResource",".","The","``","write","``","method","encodes","the","given","ndimage","into","the","format","handled","by","the","backend","and","writes","it","to","the","ImageResource",".","It","overwrites","any","content","that","may","have","been","previously","stored","in","the","file",".","If","the","backend","supports","only","a","single","format","then","it","must","check","if","the","ImageResource","matches","that","format","and","raise","an","exception","if","not",".","Typically",",","this","should","be","done","during","initialization","in","the","form","of","a","``","InitializationError","``",".","If","the","backend","supports","more","than","one","format","it","must","determine","the","requested\/desired","format",".","Usually","this","can","be","done","by","inspecting","the","ImageResource","(","e.g.",",","by","checking","``","request.extension","``",")",",","or","by","providing","a","mechanism","to","explicitly","set","the","format","(","perhaps","with","a","-","sensible","-","default","value",")",".","If","the","plugin","can","not","determine","the","desired","format",",","it","*","*","must","not","*","*","write","to","the","ImageResource",",","but","raise","an","exception","instead",".","If","the","backend","supports","at","least","one","format","that","can","hold","multiple","ndimages","it","should","be","capable","of","handling","ndimage","batches","and","lists","of","ndimages",".","If","the","``","ndimage","``","input","is","a","list","of","ndimages",",","the","plugin","should","not","assume","that","the","ndimages","are","not","stackable",",","i.e.",",","ndimages","may","have","different","shapes",".","Otherwise",",","the","``","ndimage","``","may","be","a","batch","of","multiple","ndimages","stacked","along","the","first","axis","of","the","array",".","The","plugin","must","be","able","to","discover","this",",","either","automatically","or","via","additional","`","kwargs","`",".","If","there","is","ambiguity","in","the","process",",","the","plugin","must","clearly","document","what","happens","in","such","cases","and",",","if","possible",",","describe","how","to","resolve","this","ambiguity",".","Parameters","--","--","--","--","--","ndimage",":","ArrayLike","The","ndimage","to","encode","and","write","to","the","current","ImageResource",".","*","*","kwargs",":","Any","The","write","method","may","accept","any","number","of","plugin-specific","keyword","arguments","to","customize","the","writing","behavior",".","Usually","these","match","the","arguments","available","on","the","backend","and","are","forwarded","to","it",".","Returns","--","--","--","-","encoded_image",":","bytes","or","None","If","the","chosen","ImageResource","is","the","special","target","``","``","<","bytes",">","''","``","then","write","should","return","a","byte","string","containing","the","encoded","image","data",".","Otherwise",",","it","returns","None",".","Notes","--","--","-","The","ImageResource","to","which","the","plugin","should","write","to","is","managed","by","the","provided","request","object",".","Directly","accessing","the","managed","ImageResource","is","_not_","permitted",".","Instead",",","you","can","get","FileLike","access","to","the","ImageResource","via","request.get_file","(",")",".","If","the","backend","does","n't","support","writing","to","FileLike","objects",",","you","can","request","a","temporary","file","to","pass","to","the","backend","via","``","request.get_local_filename","(",")","``",".","This","is",",","however",",","not","very","performant","(","involves","copying","the","Request","'s","content","from","a","temporary","file",")",",","so","you","should","avoid","doing","this","whenever","possible",".","Consider","it","a","fallback","method","in","case","all","else","fails","."]
code: def write(
      self, ndimage: Union[ArrayLike, List[ArrayLike]]
  ) -> Optional[bytes]:
      """Write a ndimage to a ImageResource.
  
      The ``write`` method encodes the given ndimage into the format handled
      by the backend and writes it to the ImageResource. It overwrites
      any content that may have been previously stored in the file.
  
      If the backend supports only a single format then it must check if
      the ImageResource matches that format and raise an exception if not.
      Typically, this should be done during initialization in the form of a
      ``InitializationError``.
  
      If the backend supports more than one format it must determine the
      requested/desired format. Usually this can be done by inspecting the
      ImageResource (e.g., by checking ``request.extension``), or by providing
      a mechanism to explicitly set the format (perhaps with a - sensible -
      default value). If the plugin can not determine the desired format, it
      **must not** write to the ImageResource, but raise an exception instead.
  
      If the backend supports at least one format that can hold multiple
      ndimages it should be capable of handling ndimage batches and lists of
      ndimages. If the ``ndimage`` input is a list of ndimages, the plugin
      should not assume that the ndimages are not stackable, i.e., ndimages
      may have different shapes. Otherwise, the ``ndimage`` may be a batch of
      multiple ndimages stacked along the first axis of the array. The plugin
      must be able to discover this, either automatically or via additional
      `kwargs`. If there is ambiguity in the process, the plugin must clearly
      document what happens in such cases and, if possible, describe how to
      resolve this ambiguity.
  
      Parameters
      ----------
      ndimage : ArrayLike
          The ndimage to encode and write to the current ImageResource.
      **kwargs : Any
          The write method may accept any number of plugin-specific keyword
          arguments to customize the writing behavior. Usually these match the
          arguments available on the backend and are forwarded to it.
  
      Returns
      -------
      encoded_image : bytes or None
          If the chosen ImageResource is the special target ``"<bytes>"`` then
          write should return a byte string containing the encoded image data.
          Otherwise, it returns None.
  
      Notes
      -----
      The ImageResource to which the plugin should write to is managed by the
      provided request object. Directly accessing the managed ImageResource is
      _not_ permitted. Instead, you can get FileLike access to the
      ImageResource via request.get_file().
  
      If the backend doesn't support writing to FileLike objects, you can
      request a temporary file to pass to the backend via
      ``request.get_local_filename()``. This is, however, not very performant
      (involves copying the Request's content from a temporary file), so you
      should avoid doing this whenever possible. Consider it a fallback method
      in case all else fails.
  
      """
      raise NotImplementedError()
  
file_path: imageio/imageio/core/v3_plugin_api.py
imports: from .None import Request
  from ..typing import ArrayLike
  import numpy
  from typing import Optional, Dict, Any, Tuple, Union, List, Iterator
  from dataclasses import dataclass
label_desc: Use image node_id 3 for calling the PluginV3 obj's underlying member method code with example usage: obj.write(ndimage) without return types