FileHandle

final class tifffile.FileHandle(file, /, mode=None, *, name=None, offset=None, size=None)

Binary file handle.

A limited, special purpose binary file handle that can:

  • handle embedded files (for example, LSM within LSM files).

  • re-open closed files (for multi-file formats, such as OME-TIFF).

  • read and write NumPy arrays and records from file-like objects.

When initialized from another file handle, do not use the other handle unless this FileHandle is closed.

FileHandle instances are not thread-safe.

Parameters:
  • file (str | os.PathLike[Any] | FileHandle | IO[bytes]) – File name or seekable binary stream, such as open file, BytesIO, or fsspec OpenFile.

  • mode (Literal['r', 'r+', 'w', 'x', 'rb', 'r+b', 'wb', 'xb'] | None) – File open mode if file is file name. The default is ‘rb’. Files are always opened in binary mode.

  • name (str | None) – Name of file if file is binary stream.

  • offset (int | None) – Start position of embedded file. The default is the current file position.

  • size (int | None) – Size of embedded file. The default is the number of bytes from offset to the end of the file.

open()

Open or re-open file.

Return type:

None

close()

Close file handle.

Return type:

None

fileno()

Return underlying file descriptor if exists, else raise OSError.

Return type:

int

writable()

Return True if stream supports writing.

Return type:

bool

seekable()

Return True if stream supports random access.

Return type:

bool

tell()

Return file’s current position.

Return type:

int

seek(offset, /, whence=0)

Set file’s current position.

Parameters:
  • offset (int) – Position of file handle relative to position indicated by whence.

  • whence (int) – Relative position of offset. 0 (os.SEEK_SET) beginning of file (default). 1 (os.SEEK_CUR) current position. 2 (os.SEEK_END) end of file.

Return type:

int

read(size=-1, /)

Return bytes read from file.

Parameters:

size (int) – Number of bytes to read from file. By default, read until the end of the file.

Return type:

bytes

readinto(buffer, /)

Read bytes from file into buffer.

Parameters:

buffer (bytes) – Buffer to read into.

Returns:

Number of bytes read from file.

Return type:

int

write(buffer, /)

Write bytes to file and return number of bytes written.

Parameters:

buffer (bytes) – Bytes to write to file.

Returns:

Number of bytes written.

Return type:

int

flush()

Flush write buffers of stream if applicable.

Return type:

None

memmap_array(dtype, shape, offset=0, *, mode='r', order='C')

Return numpy.memmap of array data stored in file.

Parameters:
  • dtype (DTypeLike) – Data type of array in file.

  • shape (tuple[int, ...]) – Shape of array in file.

  • offset (int) – Start position of array-data in file.

  • mode (str) – File is opened in this mode. The default is read-only.

  • order (str) – Order of ndarray memory layout. The default is ‘C’.

Return type:

NDArray[Any]

read_array(dtype, count=-1, offset=0, *, out=None)

Return NumPy array from file in native byte order.

Parameters:
  • dtype (DTypeLike) – Data type of array to read.

  • count (int) – Number of items to read. By default, all items are read.

  • offset (int) – Start position of array-data in file.

  • out (NDArray[Any] | None) – NumPy array to read into. By default, a new array is created.

Return type:

NDArray[Any]

read_record(dtype, shape=1, *, byteorder=None)

Return NumPy record from file.

Parameters:
  • dtype (DTypeLike) – Data type of record array to read.

  • shape (tuple[int, ...] | int | None) – Shape of record array to read.

  • byteorder (Literal['S', '<', '>', '=', '|'] | None) – Byte order of record array to read.

Return type:

numpy.recarray[Any, Any]

write_empty(size, /)

Append null-bytes to file.

The file position must be at the end of the file.

Parameters:

size (int) – Number of null-bytes to write to file.

Return type:

int

write_array(data, dtype=None, /)

Write NumPy array to file in C contiguous order.

Parameters:
  • data (NDArray[Any]) – Array to write to file.

  • dtype (DTypeLike)

Return type:

int

read_segments(offsets, bytecounts, /, indices=None, *, sort=True, lock=None, buffersize=None, flat=True)

Return iterator over segments read from file and their indices.

The purpose of this function is to

  • reduce small or random reads.

  • reduce acquiring reentrant locks.

  • synchronize seeks and reads.

  • limit size of segments read into memory at once. (ThreadPoolExecutor.map is not collecting iterables lazily).

Parameters:
  • offsets (Sequence[int]) – Offsets of segments to read from file.

  • bytecounts (Sequence[int]) – Byte counts of segments to read from file.

  • indices (Sequence[int] | None) – Indices of segments in image. The default is range(len(offsets)).

  • sort (bool) – Read segments from file in order of their offsets.

  • lock (threading.RLock | NullContext | None) – Reentrant lock to synchronize seeks and reads.

  • buffersize (int | None) – Approximate number of bytes to read from file in one pass. The default is _TIFF.BUFFERSIZE.

  • flat (bool) – If True, return iterator over individual (segment, index) tuples. Else, return an iterator over a list of (segment, index) tuples that were acquired in one pass.

Yields:

Individual or lists of (segment, index) tuples.

Return type:

Iterator[tuple[bytes | None, int]] | Iterator[list[tuple[bytes | None, int]]]

property name: str

Name of file or stream.

property dirname: str

Directory in which file is stored.

property path: str

Absolute path of file.

property extension: str

File name extension of file or stream.

property size: int

Size of file in bytes.

property closed: bool

File is closed.

property lock: threading.RLock | NullContext

Reentrant lock to synchronize reads and writes.

property has_lock: bool

A reentrant lock is currently used to sync reads and writes.

property is_file: bool

File has fileno and can be memory-mapped.