class_docstr: Class to act as proxy for the array that can be read from a file
  
  The array proxy allows us to freeze the passed fileobj and header such that
  it returns the expected data array.
  
  This implementation assumes a contiguous array in the file object, with one
  of the numpy dtypes, starting at a given file position ``offset`` with
  single ``slope`` and ``intercept`` scaling to produce output values.
  
  The class ``__init__`` requires a spec which defines how the data will be
  read and rescaled. The spec may be a tuple of length 2 - 5, containing the
  shape, storage dtype, offset, slope and intercept, or a ``header`` object
  with methods:
  
  * get_data_shape
  * get_data_dtype
  * get_data_offset
  * get_slope_inter
  
  A header should also have a 'copy' method.  This requirement will go away
  when the deprecated 'header' property goes away.
  
  This implementation allows us to deal with Analyze and its variants,
  including Nifti1, and with the MGH format.
  
  Other image types might need more specific classes to implement the API.
  See :mod:`nibabel.minc1`, :mod:`nibabel.ecat` and :mod:`nibabel.parrec` for
  examples.
class_docstr_tok: ["Class","to","act","as","proxy","for","the","array","that","can","be","read","from","a","file","The","array","proxy","allows","us","to","freeze","the","passed","fileobj","and","header","such","that","it","returns","the","expected","data","array",".","This","implementation","assumes","a","contiguous","array","in","the","file","object",",","with","one","of","the","numpy","dtypes",",","starting","at","a","given","file","position","``","offset","``","with","single","``","slope","``","and","``","intercept","``","scaling","to","produce","output","values",".","The","class","``","__init__","``","requires","a","spec","which","defines","how","the","data","will","be","read","and","rescaled",".","The","spec","may","be","a","tuple","of","length","2","-","5",",","containing","the","shape",",","storage","dtype",",","offset",",","slope","and","intercept",",","or","a","``","header","``","object","with","methods",":","*","get_data_shape","*","get_data_dtype","*","get_data_offset","*","get_slope_inter","A","header","should","also","have","a","'copy","'","method",".","This","requirement","will","go","away","when","the","deprecated","'header","'","property","goes","away",".","This","implementation","allows","us","to","deal","with","Analyze","and","its","variants",",","including","Nifti1",",","and","with","the","MGH","format",".","Other","image","types","might","need","more","specific","classes","to","implement","the","API",".","See",":","mod",":","`","nibabel.minc1","`",",",":","mod",":","`","nibabel.ecat","`","and",":","mod",":","`","nibabel.parrec","`","for","examples","."]
docstr: Initialize array proxy instance
  
  Parameters
  ----------
  file_like : object
      File-like object or filename. If file-like object, should implement
      at least ``read`` and ``seek``.
  spec : object or tuple
      Tuple must have length 2-5, with the following values:
  
      #. shape: tuple - tuple of ints describing shape of data;
      #. storage_dtype: dtype specifier - dtype of array inside proxied
         file, or input to ``numpy.dtype`` to specify array dtype;
      #. offset: int - offset, in bytes, of data array from start of file
         (default: 0);
      #. slope: float - scaling factor for resulting data (default: 1.0);
      #. inter: float - intercept for rescaled data (default: 0.0).
  
      OR
  
      Header object implementing ``get_data_shape``, ``get_data_dtype``,
      ``get_data_offset``, ``get_slope_inter``
  mmap : {True, False, 'c', 'r'}, optional, keyword only
      `mmap` controls the use of numpy memory mapping for reading data.
      If False, do not try numpy ``memmap`` for data array.  If one of
      {'c', 'r'}, try numpy memmap with ``mode=mmap``.  A `mmap` value of
      True gives the same behavior as ``mmap='c'``.  If `file_like`
      cannot be memory-mapped, ignore `mmap` value and read array from
      file.
  order : {None, 'F', 'C'}, optional, keyword only
      `order` controls the order of the data array layout. Fortran-style,
      column-major order may be indicated with 'F', and C-style, row-major
      order may be indicated with 'C'. None gives the default order, that
      comes from the `_default_order` class variable.
  keep_file_open : { None, True, False }, optional, keyword only
      `keep_file_open` controls whether a new file handle is created
      every time the image is accessed, or a single file handle is
      created and used for the lifetime of this ``ArrayProxy``. If
      ``True``, a single file handle is created and used. If ``False``,
      a new file handle is created every time the image is accessed.
      If ``file_like`` is an open file handle, this setting has no
      effect. The default value (``None``) will result in the value of
      ``KEEP_FILE_OPEN_DEFAULT`` being used.
docstr_tok: ["Initialize","array","proxy","instance","Parameters","--","--","--","--","--","file_like",":","object","File-like","object","or","filename",".","If","file-like","object",",","should","implement","at","least","``","read","``","and","``","seek","``",".","spec",":","object","or","tuple","Tuple","must","have","length","2-5",",","with","the","following","values",":","#",".","shape",":","tuple","-","tuple","of","ints","describing","shape","of","data",";","#",".","storage_dtype",":","dtype","specifier","-","dtype","of","array","inside","proxied","file",",","or","input","to","``","numpy.dtype","``","to","specify","array","dtype",";","#",".","offset",":","int","-","offset",",","in","bytes",",","of","data","array","from","start","of","file","(","default",":","0",")",";","#",".","slope",":","float","-","scaling","factor","for","resulting","data","(","default",":","1.0",")",";","#",".","inter",":","float","-","intercept","for","rescaled","data","(","default",":","0.0",")",".","OR","Header","object","implementing","``","get_data_shape","``",",","``","get_data_dtype","``",",","``","get_data_offset","``",",","``","get_slope_inter","``","mmap",":","{","True",",","False",",","'","c","'",",","'","r","'","}",",","optional",",","keyword","only","`","mmap","`","controls","the","use","of","numpy","memory","mapping","for","reading","data",".","If","False",",","do","not","try","numpy","``","memmap","``","for","data","array",".","If","one","of","{","'","c","'",",","'","r","'","}",",","try","numpy","memmap","with","``","mode=mmap","``",".","A","`","mmap","`","value","of","True","gives","the","same","behavior","as","``","mmap=","'","c","'","``",".","If","`","file_like","`","can","not","be","memory-mapped",",","ignore","`","mmap","`","value","and","read","array","from","file",".","order",":","{","None",",","'","F","'",",","'","C","'","}",",","optional",",","keyword","only","`","order","`","controls","the","order","of","the","data","array","layout",".","Fortran-style",",","column-major","order","may","be","indicated","with","'","F","'",",","and","C-style",",","row-major","order","may","be","indicated","with","'","C","'",".","None","gives","the","default","order",",","that","comes","from","the","`","_default_order","`","class","variable",".","keep_file_open",":","{","None",",","True",",","False","}",",","optional",",","keyword","only","`","keep_file_open","`","controls","whether","a","new","file","handle","is","created","every","time","the","image","is","accessed",",","or","a","single","file","handle","is","created","and","used","for","the","lifetime","of","this","``","ArrayProxy","``",".","If","``","True","``",",","a","single","file","handle","is","created","and","used",".","If","``","False","``",",","a","new","file","handle","is","created","every","time","the","image","is","accessed",".","If","``","file_like","``","is","an","open","file","handle",",","this","setting","has","no","effect",".","The","default","value","(","``","None","``",")","will","result","in","the","value","of","``","KEEP_FILE_OPEN_DEFAULT","``","being","used","."]
code: def __init__(
      self,
      file_like,
      spec,
      *,
      mmap=True,
      order=None,
      keep_file_open=None,
  ):
      """Initialize array proxy instance
  
      Parameters
      ----------
      file_like : object
          File-like object or filename. If file-like object, should implement
          at least ``read`` and ``seek``.
      spec : object or tuple
          Tuple must have length 2-5, with the following values:
  
          #. shape: tuple - tuple of ints describing shape of data;
          #. storage_dtype: dtype specifier - dtype of array inside proxied
             file, or input to ``numpy.dtype`` to specify array dtype;
          #. offset: int - offset, in bytes, of data array from start of file
             (default: 0);
          #. slope: float - scaling factor for resulting data (default: 1.0);
          #. inter: float - intercept for rescaled data (default: 0.0).
  
          OR
  
          Header object implementing ``get_data_shape``, ``get_data_dtype``,
          ``get_data_offset``, ``get_slope_inter``
      mmap : {True, False, 'c', 'r'}, optional, keyword only
          `mmap` controls the use of numpy memory mapping for reading data.
          If False, do not try numpy ``memmap`` for data array.  If one of
          {'c', 'r'}, try numpy memmap with ``mode=mmap``.  A `mmap` value of
          True gives the same behavior as ``mmap='c'``.  If `file_like`
          cannot be memory-mapped, ignore `mmap` value and read array from
          file.
      order : {None, 'F', 'C'}, optional, keyword only
          `order` controls the order of the data array layout. Fortran-style,
          column-major order may be indicated with 'F', and C-style, row-major
          order may be indicated with 'C'. None gives the default order, that
          comes from the `_default_order` class variable.
      keep_file_open : { None, True, False }, optional, keyword only
          `keep_file_open` controls whether a new file handle is created
          every time the image is accessed, or a single file handle is
          created and used for the lifetime of this ``ArrayProxy``. If
          ``True``, a single file handle is created and used. If ``False``,
          a new file handle is created every time the image is accessed.
          If ``file_like`` is an open file handle, this setting has no
          effect. The default value (``None``) will result in the value of
          ``KEEP_FILE_OPEN_DEFAULT`` being used.
      """
      if mmap not in (True, False, "c", "r"):
          raise ValueError(
              "mmap should be one of {True, False, 'c', 'r'}"
          )
      if order not in (None, "C", "F"):
          raise ValueError("order should be one of {None, 'C', 'F'}")
      self.file_like = file_like
      if hasattr(spec, "get_data_shape"):
          slope, inter = spec.get_slope_inter()
          par = (
              spec.get_data_shape(),
              spec.get_data_dtype(),
              spec.get_data_offset(),
              1.0 if slope is None else slope,
              0.0 if inter is None else inter,
          )
      elif 2 <= len(spec) <= 5:
          optional = (0, 1.0, 0.0)
          par = spec + optional[len(spec) - 2 :]
      else:
          raise TypeError(
              "spec must be tuple of length 2-5 or header object"
          )
  
      # Warn downstream users that the class variable order is going away
      if hasattr(self.__class__, "order"):
          warnings.warn(
              f"Class {self.__class__} has an `order` class variable. "
              "ArrayProxy subclasses should rename this variable to `_default_order` "
              "to avoid conflict with instance variables.\n"
              "* deprecated in version: 5.0\n"
              "* will raise error in version: 7.0\n",
              DeprecationWarning,
              stacklevel=2,
          )
          # Override _default_order with order, to follow intent of subclasser
          self._default_order = self.order
  
      # Copies of values needed to read array
      (
          self._shape,
          self._dtype,
          self._offset,
          self._slope,
          self._inter,
      ) = par
      # Permit any specifier that can be interpreted as a numpy dtype
      self._dtype = np.dtype(self._dtype)
      self._mmap = mmap
      if order is None:
          order = self._default_order
      self.order = order
      # Flags to keep track of whether a single ImageOpener is created, and
      # whether a single underlying file handle is created.
      (
          self._keep_file_open,
          self._persist_opener,
      ) = self._should_keep_file_open(keep_file_open)
      self._lock = RLock()
  
imports: from __future__ import annotations
  import typing
  import warnings
  from contextlib import contextmanager
  from threading import RLock
  import numpy
  from .None import openers
  from .fileslice import canonical_slicers, fileslice
  from .volumeutils import apply_read_scaling, array_from_file
label_desc: Use image node_id 1 to create a new ArrayProxy object from inherited base classes: ArrayLike with example: obj = ArrayProxy(file_like, spec)