General I/O Utility methods

Utilities for parsing slice input.

sarpy.io.general.slice_parsing.validate_slice_int(the_int: int, bound: int, include: bool = True) → int

Ensure that the given integer makes sense as a slice entry, and move to a normalized form.

Parameters:

  • the_int (int) –

  • bound (int) –

  • include (bool) –

Return type:

int

sarpy.io.general.slice_parsing.verify_slice(item: None | int | slice | Tuple[int, ...], max_element: int) → slice

Verify a given slice against a bound.

New in version 1.3.0.

Parameters:

  • item (None|int|slice|Tuple[int, ...]) –

  • max_element (int) –

Returns:

This will certainly have start and step populated, and will have stop populated unless step < 0 and stop must be None.

Return type:

slice

sarpy.io.general.slice_parsing.verify_subscript(subscript: None | int | slice | Sequence[int | slice | Tuple[int, ...]], corresponding_shape: Tuple[int, ...]) → Tuple[slice, ...]

Verify a subscript like item against a corresponding shape.

New in version 1.3.0

Parameters:

  • subscript (None|int|slice|Sequence[int|slice|Tuple[int, ...]]) –

  • corresponding_shape (Tuple[int, ...]) –

Return type:

Tuple[slice, …]

sarpy.io.general.slice_parsing.get_slice_result_size(slice_in: slice) → int

Gets the size of the slice result. This assumes a normalized slice definition.

New in version 1.3.0.

Parameters:

slice_in (slice) –

Return type:

int

sarpy.io.general.slice_parsing.get_subscript_result_size(subscript: None | int | slice | Sequence[int | slice | Tuple[int, ...]], corresponding_shape: Tuple[int, ...]) → Tuple[Tuple[slice, ...], Tuple[int, ...]]

Validate the given subscript against the corresponding shape, and also determine the shape of the resultant data reading result.

New in version 1.3.0

Parameters:

  • subscript (None|int|slice|Tuple[slice, ...]) –

  • corresponding_shape (Tuple[int, ...]) –

Returns:

  • valid_subscript (Tuple[slice, …])

  • output_shape (Tuple[int, …])

Common functionality for converting metadata

sarpy.io.general.utils.is_file_like(the_input: Any) → bool

Verify whether the provided input appear to provide a “file-like object”. This term is used ubiquitously, but not all usages are identical. In this case, we mean that there exist callable attributes read, write, seek, and tell.

Note that this does not check the mode (binary/string or read/write/append), as it is not clear that there is any generally accessible way to do so.

Parameters:

the_input –

Return type:

bool

sarpy.io.general.utils.is_real_file(the_input: BinaryIO) → bool

Determine if the file-like object is associated with an actual file. This is mainly to consider suitability for establishment of a numpy.memmap.

Parameters:

the_input (BinaryIO) –

Return type:

bool

sarpy.io.general.utils.is_nitf(file_name: str | BinaryIO, return_version=False) → bool | Tuple[bool, str | None]

Test whether the given input is a NITF 2.0 or 2.1 file.

Parameters:

  • file_name (str|BinaryIO) –

  • return_version (bool) –

Returns:

  • is_nitf_file (bool) – Is the file a NITF file, based solely on checking initial bytes.

  • nitf_version (None|str) – Only returned is return_version=True. Will be None in the event that is_nitf_file=False.

sarpy.io.general.utils.is_tiff(file_name: str | BinaryIO, return_details=False) → bool | Tuple[bool, str | None, int | None]

Test whether the given input is a tiff or big_tiff file.

Parameters:

  • file_name (str|BinaryIO) –

  • return_details (bool) – Return the tiff details of endianness and magic number?

Returns:

  • is_tiff_file (bool)

  • endianness (None|str) – Only returned if return_details is True. One of [‘>’, ‘<’].

  • magic_number (None|int) – Only returned if return_details is True. One of [42, 43].

sarpy.io.general.utils.is_hdf5(file_name: str | BinaryIO) → bool

Test whether the given input is a hdf5 file.

Parameters:

file_name (str|BinaryIO) –

Return type:

bool

sarpy.io.general.utils.parse_timestring(str_in: str, precision: str = 'us') → datetime64

Parse (naively) a timestring to numpy.datetime64 of the given precision.

Parameters:

  • str_in (str) –

  • precision (str) – See numpy.datetime64 for precision options.

Return type:

numpy.datetime64

sarpy.io.general.utils.get_seconds(dt1: datetime64, dt2: datetime64, precision: str = 'us') → float

The number of seconds between two numpy.datetime64 elements.

Parameters:

  • dt1 (numpy.datetime64) –

  • dt2 (numpy.datetime64) –

  • precision (str) – one of ‘s’, ‘ms’, ‘us’, or ‘ns’.

Returns:

the number of seconds between dt2 and dt1 (i.e. dt1 - dt2).

Return type:

float

sarpy.io.general.utils.calculate_md5(the_path: str, chunk_size: int = 1048576) → str

Calculate the md5 checksum of a given file defined by a path.

Parameters:

  • the_path (str) – The path to the file

  • chunk_size (int) – The chunk size for processing

Returns:

The 32 character MD5 hex digest of the given file

Return type:

str

class sarpy.io.general.utils.MemMap(file_obj, length, offset)

Bases: object

Spoofing necessary memory map functionality to permit READ ONLY opening of a file containing compressed image data somewhere mid-file for use in the PIL interface. This is just a thin wrapper around the built-in Python memmap class which accommodates arbitrary offset (versus limited to allocation granularity).

The bare minimum of functionality is implemented to permit the intended use.