DOC: Clarification in read_segments doc, and inline comments in

openers._gzip_open function

Author: pauldmccarthy

nibabel/fileslice.py

@@ -637,7 +637,9 @@ def read_segments(fileobj, segments, n_bytes, lock=None):
     lock : threading.Lock
         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.
 
     Returns
     -------
@@ -647,11 +649,14 @@ def read_segments(fileobj, segments, n_bytes, lock=None):
     """
     # Make a dummy lock-like thing to make the code below a bit nicer
     if lock is None:
+
         class DummyLock(object):
             def __enter__(self):
                 pass
+
             def __exit__(self, exc_type, exc_val, exc_tb):
                 return False
+
         lock = DummyLock()
 
     if len(segments) == 0:

nibabel/openers.py

@@ -72,6 +72,8 @@ def _gzip_open(fileish, mode='rb', compresslevel=9):
     # is this a file? if not we assume it is a string
     is_file = hasattr(fileish, 'read') and hasattr(fileish, 'write') and \
               hasattr(fileish, 'mode')
+
+    # If we've been given a file object, we can't change its mode.
     if is_file:
         mode = fileish.mode
 
@@ -82,6 +84,9 @@ def _gzip_open(fileish, mode='rb', compresslevel=9):
             gzip_file = SafeIndexedGzipFile(fid=fileish, **kwargs)
         else:
             gzip_file = SafeIndexedGzipFile(filename=fileish, **kwargs)
+
+    # Fall-back to built-in GzipFile (wrapped with the BufferedGzipFile class
+    # defined above)
     else:
         gzip_file = BufferedGzipFile(fileish, mode, compresslevel)