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.