Table of Contents

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

int

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

int

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

int

MAGIC_LEN

The magic string's length, version bytes included (NumPy's MAGIC_LEN).

public const int MAGIC_LEN = 8

Field Value

int

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

IReadOnlyCollection<string>

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

descr string

The 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

descr is null.

TypeError

Not a dtype NumPy understands (data type 'garbage' not understood), as NumPy's numpy.dtype raises.

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

dtype DType

The descriptor.

Returns

DType

dtype.

Exceptions

ArgumentNullException

dtype is 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

dtype DType

The descriptor.

Returns

string

The descr string.

Exceptions

ArgumentNullException

dtype is 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

array NDArray

The array.

Returns

IDictionary<string, object>

A new dictionary (its shape a new long[], 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

array is 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

major int

The major version, 0 <= major < 256.

minor int

The minor version, 0 <= minor < 256.

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

fp Stream

The stream, positioned at the start of the file.

allow_pickle bool

Whether a pickled payload may be read (a trusted file).

max_header_size long

The longest header accepted (ignored when allow_pickle declares the file trusted, as NumPy's).

Returns

NDArray

A new array.

Exceptions

ArgumentNullException

fp is null.

ValueError

A malformed file, or a pickled payload with allow_pickle false (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

fp Stream

The stream.

max_header_size long

The 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

fp is null.

ValueError

A malformed header (NumPy's texts).

NotSupportedException

A descr NumSharp cannot represent (the '|O' a StringDType file 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

fp Stream

The stream, positioned just past the magic string.

max_header_size long

The longest header accepted.

Returns

(long[] shape, bool fortran_order, DType dtype)

The shape, the Fortran-order flag and the descriptor.

Exceptions

ArgumentNullException

fp is 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

fp Stream

The stream, positioned at the start of a .npy file.

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

fp is 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

fp Stream

The stream to write to.

array NDArray

The array.

version (int major, int minor)?

The format version, or null for the oldest one that fits the header.

allow_pickle bool

Whether a pickled payload (a StringDType array) may be written.

Exceptions

ArgumentNullException

fp or array is 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 a StringDType array with allow_pickle false.

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

fp Stream

The stream to write to.

d IDictionary<string, object>

The header dictionary (descr, fortran_order, shape).

Exceptions

ArgumentNullException

fp or d is null.

ArgumentException

d has no shape, or one that is not a long[] / 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

fp Stream

The stream to write to.

d IDictionary<string, object>

The header dictionary.

Exceptions

ArgumentNullException

fp or d is null.

ArgumentException

d has no usable shape.