DOC+RF: Adjust docs for ArrayProxy keep_file_open flag, and for fileslice

thread lock. Variable rename in fileslice to avoid collision with built-in.

Author: pauldmccarthy

nibabel/analyze.py

@@ -950,7 +950,7 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             `mmap` value of True gives the same behavior as ``mmap='c'``.  If
             image data file cannot be memory-mapped, ignore `mmap` value and
             read array from file.
-        keep_file_open : { 'auto', True, False }, optional, keyword only
+        keep_file_open : { None, 'auto', 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
@@ -960,8 +960,9 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             present, a single file handle is created and persisted. If
             ``indexed_gzip`` is not available, behaviour is the same as if
             ``keep_file_open is False``. If ``file_map`` refers to an open
-            file handle, this setting has no effect. The default value is
-            set to the value of ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT``.
+            file handle, this setting has no effect. The default value
+            (``None``) will result in the value of
+            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
 
         Returns
         -------
@@ -1003,8 +1004,7 @@ def from_filename(klass, filename, mmap=True, keep_file_open=None):
             `mmap` value of True gives the same behavior as ``mmap='c'``.  If
             image data file cannot be memory-mapped, ignore `mmap` value and
             read array from file.
-
-        keep_file_open : { 'auto', True, False }, optional, keyword only
+        keep_file_open : { None, 'auto', 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
@@ -1013,8 +1013,9 @@ def from_filename(klass, filename, mmap=True, keep_file_open=None):
             ``'auto'``, and the optional ``indexed_gzip`` dependency is
             present, a single file handle is created and persisted. If
             ``indexed_gzip`` is not available, behaviour is the same as if
-            ``keep_file_open is False``. The default value is set to the value
-            of ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT``.
+            ``keep_file_open is False``. The default value (``None``) will
+            result in the value of
+            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
 
         Returns
         -------

nibabel/arrayproxy.py

@@ -120,7 +120,7 @@ def __init__(self, file_like, spec, mmap=True, keep_file_open=None):
             True gives the same behavior as ``mmap='c'``.  If `file_like`
             cannot be memory-mapped, ignore `mmap` value and read array from
             file.
-        keep_file_open : { 'auto', True, False }, optional, keyword only
+        keep_file_open : { None, 'auto', 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
@@ -130,8 +130,8 @@ def __init__(self, file_like, spec, mmap=True, keep_file_open=None):
             present, a single file handle is created and persisted. If
             ``indexed_gzip`` is not available, behaviour is the same as if
             ``keep_file_open is False``. If ``file_like`` is an open file
-            handle, this setting has no effect. The default value is set to
-            the value of ``KEEP_FILE_OPEN_DEFAULT``.
+            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'}")
@@ -211,8 +211,8 @@ def _should_keep_file_open(self, file_like, keep_file_open):
         if isinstance(keep_file_open, bool):
             return keep_file_open
         if keep_file_open != 'auto':
-            raise ValueError(
-                'keep_file_open should be one of {\'auto\', True, False }')
+            raise ValueError('keep_file_open should be one of {None, '
+                             '\'auto\', True, False}')
 
         # file_like is a handle - keep_file_open is irrelevant
         if hasattr(file_like, 'read') and hasattr(file_like, 'seek'):
@@ -257,7 +257,6 @@ def _get_fileobj(self):
         The specific behaviour depends on the value of the ``keep_file_open``
         flag that was passed to ``__init__``.
 
-
         Yields
         ------
         ImageOpener

nibabel/fileslice.py

@@ -18,7 +18,9 @@
 
 
 class _NullLock(object):
-    """The ``_NullLock`` is an object which can be used in place of a
+    """Can be used as no-function dummy object in place of ``threading.lock``.
+
+    The ``_NullLock`` is an object which can be used in place of a
     ``threading.Lock`` object, but doesn't actually do anything.
 
     It is used by the ``read_segments`` function in the event that a
@@ -648,12 +650,14 @@ def read_segments(fileobj, segments, n_bytes, lock=None):
         absolute file offset in bytes and number of bytes to read
     n_bytes : int
         total number of bytes that will be read
-    lock : threading.Lock
+    lock : {None, threading.Lock, lock-like} optional
         If provided, used to ensure that paired calls to ``seek`` and ``read``
         cannot be interrupted by another thread accessing the same ``fileobj``.
         Each thread which accesses the same file via ``read_segments`` must
         share a lock in order to ensure that the file access is thread-safe.
-        A lock does not need to be provided for single-threaded access.
+        A lock does not need to be provided for single-threaded access. The
+        default value (``None``) results in a lock-like object  (a
+        ``_NullLock``) which does not do anything.
 
     Returns
     -------
@@ -763,9 +767,14 @@ def fileslice(fileobj, sliceobj, shape, dtype, offset=0, order='C',
         returning one of 'full', 'contiguous', None.  See
         :func:`optimize_slicer` and see :func:`threshold_heuristic` for an
         example.
-    lock: threading.Lock, optional
+    lock : {None, threading.Lock, lock-like} optional
         If provided, used to ensure that paired calls to ``seek`` and ``read``
         cannot be interrupted by another thread accessing the same ``fileobj``.
+        Each thread which accesses the same file via ``read_segments`` must
+        share a lock in order to ensure that the file access is thread-safe.
+        A lock does not need to be provided for single-threaded access. The
+        default value (``None``) results in a lock-like object  (a
+        ``_NullLock``) which does not do anything.
 
     Returns
     -------
@@ -779,8 +788,8 @@ def fileslice(fileobj, sliceobj, shape, dtype, offset=0, order='C',
     segments, sliced_shape, post_slicers = calc_slicedefs(
         sliceobj, shape, itemsize, offset, order)
     n_bytes = reduce(operator.mul, sliced_shape, 1) * itemsize
-    bytes = read_segments(fileobj, segments, n_bytes, lock)
-    sliced = np.ndarray(sliced_shape, dtype, buffer=bytes, order=order)
+    arr_data = read_segments(fileobj, segments, n_bytes, lock)
+    sliced = np.ndarray(sliced_shape, dtype, buffer=arr_data, order=order)
     return sliced[post_slicers]
 
 

nibabel/freesurfer/mghformat.py

@@ -491,7 +491,7 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             `mmap` value of True gives the same behavior as ``mmap='c'``.  If
             image data file cannot be memory-mapped, ignore `mmap` value and
             read array from file.
-        keep_file_open : { 'auto', True, False }, optional, keyword only
+        keep_file_open : { None, 'auto', 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
@@ -501,8 +501,9 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             present, a single file handle is created and persisted. If
             ``indexed_gzip`` is not available, behaviour is the same as if
             ``keep_file_open is False``. If ``file_map`` refers to an open
-            file handle, this setting has no effect. The default value is
-            set to the value of ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT``.
+            file handle, this setting has no effect. The default value
+            (``None``) will result in the value of
+            ``nibabel.arrayproxy.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'}")
@@ -536,7 +537,7 @@ def from_filename(klass, filename, mmap=True, keep_file_open=None):
             `mmap` value of True gives the same behavior as ``mmap='c'``.  If
             image data file cannot be memory-mapped, ignore `mmap` value and
             read array from file.
-        keep_file_open : { 'auto', True, False }, optional, keyword only
+        keep_file_open : { None, 'auto', 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
@@ -545,8 +546,9 @@ def from_filename(klass, filename, mmap=True, keep_file_open=None):
             ``'auto'``, and the optional ``indexed_gzip`` dependency is
             present, a single file handle is created and persisted. If
             ``indexed_gzip`` is not available, behaviour is the same as if
-            ``keep_file_open is False``. The default value is set to the value
-            of ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT``.
+            ``keep_file_open is False``. The default value (``None``) will
+            result in the value of
+            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
 
         Returns
         -------

nibabel/spm99analyze.py

@@ -261,7 +261,7 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             `mmap` value of True gives the same behavior as ``mmap='c'``.  If
             image data file cannot be memory-mapped, ignore `mmap` value and
             read array from file.
-        keep_file_open : { 'auto', True, False }, optional, keyword only
+        keep_file_open : { None, 'auto', 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
@@ -271,8 +271,9 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             present, a single file handle is created and persisted. If
             ``indexed_gzip`` is not available, behaviour is the same as if
             ``keep_file_open is False``. If ``file_map`` refers to an open
-            file handle, this setting has no effect. The default value is
-            set to the value of ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT``.
+            file handle, this setting has no effect. The default value
+            (``None``) will result in the value of
+            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
 
         Returns
         -------