Class np.lib.format
- Namespace
- NumSharp
- Assembly
- NumSharp.dll
NumPy's numpy.lib.format: the public face of the .npy format - the magic string, the header
dictionary, the header readers and writers, and whole-array reads and writes - with NumPy's names over
NumSharp's NpyFormat, which np.save / np.load already run (so the bytes are the ones those
write and read).
[ModuleName("np.lib.format")]
public static class np.lib.format
- Inheritance
-
np.lib.format
- Inherited Members
Remarks
Typed as C# sees NumPy's values: a format version is (int major, int minor), a header a dictionary
of descr (string), fortran_order (bool) and shape (long[]), a file a
Stream. Not offered: open_memmap (NumSharp has no np.memmap) and
isfileobj (a test for CPython's file objects, which a C# Stream never is). NumPy's
ValueErrors are raised as ValueError with NumPy's texts. API-parity batch 13.
Fields
ARRAY_ALIGN
The alignment of the data that follows a header, in bytes (NumPy's ARRAY_ALIGN): every
header is padded so the data starts on a multiple of it.
public const int ARRAY_ALIGN = 64
Field Value
BUFFER_SIZE
The chunk size NumPy reads and writes data in, in bytes (NumPy's BUFFER_SIZE, 2**18).
public const int BUFFER_SIZE = 262144
Field Value
GROWTH_AXIS_MAX_DIGITS
The digits a growing shape's axis is padded to in a header (NumPy's
GROWTH_AXIS_MAX_DIGITS): room for np.save-and-append writers to rewrite the header in
place.
public const int GROWTH_AXIS_MAX_DIGITS = 21
Field Value
MAGIC_LEN
The magic string's length, version bytes included (NumPy's MAGIC_LEN).
public const int MAGIC_LEN = 8
Field Value
Properties
EXPECTED_KEYS
The keys a header dictionary holds (NumPy's EXPECTED_KEYS): descr,
fortran_order, shape.
public static IReadOnlyCollection<string> EXPECTED_KEYS { get; }
Property Value
MAGIC_PREFIX
The magic prefix b'\x93NUMPY' (NumPy's MAGIC_PREFIX), as a new array on every read
(NumPy's bytes are immutable; a shared array would not be).
public static byte[] MAGIC_PREFIX { get; }
Property Value
- byte[]
Methods
descr_to_dtype(string)
NumPy's descr_to_dtype(descr): the descriptor a header's descr string names - for a
string NumPy's statement is numpy.dtype(descr), so this is np.dtype(string).
public static DType descr_to_dtype(string descr)
Parameters
descrstringThe descr (
'<f8','>f4','|b1','<U3', ...).
Returns
- DType
The descriptor, byte order included.
Remarks
NumPy's list form (a structured descr) has no counterpart: NumSharp has no structured dtypes.
Exceptions
- ArgumentNullException
descris null.- TypeError
Not a dtype NumPy understands (
data type 'garbage' not understood), as NumPy'snumpy.dtyperaises.- NotSupportedException
A NumPy dtype NumSharp cannot represent (the object dtype
'|O', datetime64, ...).
drop_metadata(DType)
NumPy's drop_metadata(dtype): the descriptor without its metadata. NumSharp's descriptors carry
none, so this is dtype itself.
public static DType drop_metadata(DType dtype)
Parameters
dtypeDTypeThe descriptor.
Returns
- DType
dtype.
Exceptions
- ArgumentNullException
dtypeis null.
dtype_to_descr(DType)
NumPy's dtype_to_descr(dtype): the descr a header stores for dtype -
its str ('<i8', '>f4', '<U3'), and '|O' for a NEP 55
StringDType (NumPy "lies that the dtype is object" and pickles the array).
public static string dtype_to_descr(DType dtype)
Parameters
dtypeDTypeThe descriptor.
Returns
- string
The descr string.
Exceptions
- ArgumentNullException
dtypeis null.- NotSupportedException
A dtype with no NumPy descr (decimal).
header_data_from_array_1_0(NDArray)
NumPy's header_data_from_array_1_0(array): the header dictionary of array:
descr, fortran_order (true only for an F-contiguous array that is not C-contiguous) and
shape.
public static IDictionary<string, object> header_data_from_array_1_0(NDArray array)
Parameters
arrayNDArrayThe array.
Returns
- IDictionary<string, object>
A new dictionary (its
shapea newlong[], never the array's own), the input write_array_header_1_0(Stream, IDictionary<string, object>) / write_array_header_2_0(Stream, IDictionary<string, object>) take.
Exceptions
- ArgumentNullException
arrayis null.- NotSupportedException
A dtype with no NumPy descr (decimal).
magic(int, int)
NumPy's magic(major, minor): the 8-byte magic string of a format version.
public static byte[] magic(int major, int minor)
Parameters
Returns
- byte[]
A new 8-byte array:
b'\x93NUMPY'then the two version bytes.
Exceptions
- ValueError
A version byte out of range (
major version must be 0 <= major < 256, then the minor's text), checked in NumPy's order.
read_array(Stream, bool, long)
NumPy's read_array(fp, allow_pickle=False, *, max_header_size=10000): reads a whole
.npy file - what np.load reads.
public static NDArray read_array(Stream fp, bool allow_pickle = false, long max_header_size = 10000)
Parameters
fpStreamThe stream, positioned at the start of the file.
allow_pickleboolWhether a pickled payload may be read (a trusted file).
max_header_sizelongThe longest header accepted (ignored when
allow_pickledeclares the file trusted, as NumPy's).
Returns
- NDArray
A new array.
Exceptions
- ArgumentNullException
fpis null.- ValueError
A malformed file, or a pickled payload with
allow_picklefalse (NumPy's texts).- NotSupportedException
A dtype NumSharp cannot represent.
read_array_header_1_0(Stream, long)
NumPy's read_array_header_1_0(fp, max_header_size=10000): reads a version 1.0 header (the stream
positioned just past the magic string) and returns what it declares.
public static (long[] shape, bool fortran_order, DType dtype) read_array_header_1_0(Stream fp, long max_header_size = 10000)
Parameters
fpStreamThe stream.
max_header_sizelongThe longest header accepted (a guard against crafted files).
Returns
- (long[] shape, bool fortran_order, DType dtype)
The shape, the Fortran-order flag and the descriptor (descr_to_dtype(string) of the header's descr, byte order included).
Exceptions
- ArgumentNullException
fpis null.- ValueError
A malformed header (NumPy's texts).
- NotSupportedException
A descr NumSharp cannot represent (the
'|O'aStringDTypefile declares, datetime64, structured).
read_array_header_2_0(Stream, long)
NumPy's read_array_header_2_0(fp, max_header_size=10000): reads a version 2.0 header (a 4-byte
header length) and returns what it declares.
public static (long[] shape, bool fortran_order, DType dtype) read_array_header_2_0(Stream fp, long max_header_size = 10000)
Parameters
fpStreamThe stream, positioned just past the magic string.
max_header_sizelongThe longest header accepted.
Returns
- (long[] shape, bool fortran_order, DType dtype)
The shape, the Fortran-order flag and the descriptor.
Exceptions
- ArgumentNullException
fpis null.- ValueError
A malformed header (NumPy's texts).
- NotSupportedException
A descr NumSharp cannot represent.
read_magic(Stream)
NumPy's read_magic(fp): reads the magic string and returns the file's format version, leaving the
stream on the header-length field.
public static (int major, int minor) read_magic(Stream fp)
Parameters
fpStreamThe stream, positioned at the start of a
.npyfile.
Returns
- (int AxisA, int AxisB)
The
(major, minor)version the file declares (not checked against the supported ones, as NumPy's does not).
Exceptions
- ArgumentNullException
fpis null.- ValueError
A wrong magic string (
the magic string is not correct; expected b'\x93NUMPY', got b'abcdef') or a stream that ends inside it.
write_array(Stream, NDArray, (int major, int minor)?, bool)
NumPy's write_array(fp, array, version=None, allow_pickle=True): writes array
as a whole .npy file - the bytes np.save writes.
public static void write_array(Stream fp, NDArray array, (int major, int minor)? version = null, bool allow_pickle = true)
Parameters
fpStreamThe stream to write to.
arrayNDArrayThe array.
version(int major, int minor)?The format version, or null for the oldest one that fits the header.
allow_pickleboolWhether a pickled payload (a
StringDTypearray) may be written.
Exceptions
- ArgumentNullException
fporarrayis null.- ValueError
An unsupported version (
we only support format version (1,0), (2,0), and (3,0), not (4, 0)), a version byte out of range, or aStringDTypearray withallow_picklefalse.- NotSupportedException
A dtype with no NumPy descr (decimal).
write_array_header_1_0(Stream, IDictionary<string, object>)
NumPy's write_array_header_1_0(fp, d): writes a version 1.0 header for the dictionary.
public static void write_array_header_1_0(Stream fp, IDictionary<string, object> d)
Parameters
fpStreamThe stream to write to.
dIDictionary<string, object>The header dictionary (
descr,fortran_order,shape).
Exceptions
- ArgumentNullException
fpordis null.- ArgumentException
dhas noshape, or one that is not along[]/int[].- ValueError
The header does not fit version 1.0's 2-byte length (
Header length 70017 too big for version=(1, 0)).
write_array_header_2_0(Stream, IDictionary<string, object>)
NumPy's write_array_header_2_0(fp, d): writes a version 2.0 header for the dictionary
(a 4-byte header length).
public static void write_array_header_2_0(Stream fp, IDictionary<string, object> d)
Parameters
fpStreamThe stream to write to.
dIDictionary<string, object>The header dictionary.
Exceptions
- ArgumentNullException
fpordis null.- ArgumentException
dhas no usableshape.