{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "No Docstrings" } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "build-install/usr/lib/python3.14/site-packages/numpy/lib/format.py", "item_line": 0, "item_type": "module", "aliases": [ "numpy.lib.format" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "numpy.lib.format", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Binary serialization" } ] } ], "title": [], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A simple format for saving numpy arrays to disk with the full information about them." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npy" }, { "__type": "Text", "__tag": 4046, "value": " format is the standard binary file format in NumPy for persisting a " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "single" } ] }, { "__type": "Text", "__tag": 4046, "value": " arbitrary NumPy array on disk. The format stores all of the shape and dtype information necessary to reconstruct the array correctly even on another machine with a different architecture. The format is designed to be as simple as possible while achieving its limited goals." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npz" }, { "__type": "Text", "__tag": 4046, "value": " format is the standard format for persisting " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "multiple" } ] }, { "__type": "Text", "__tag": 4046, "value": " NumPy arrays on disk. A " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npz" }, { "__type": "Text", "__tag": 4046, "value": " file is a zip file containing multiple " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npy" }, { "__type": "Text", "__tag": 4046, "value": " files, one for each array." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "NPY format" } ], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Can represent all NumPy arrays including nested record arrays and object arrays." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Represents the data in its native binary form." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Supports Fortran-contiguous arrays directly." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Stores all of the necessary information to reconstruct the array including shape and dtype on a machine of a different architecture. Both little-endian and big-endian arrays are supported, and a file with little-endian numbers will yield a little-endian array on any machine reading the file. The types are described in terms of their actual sizes. For example, if a machine with a 64-bit C \"long int\" writes out an array with \"long ints\", a reading machine with 32-bit C \"long ints\" will yield an array with 64-bit integers." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Is straightforward to reverse engineer. Datasets often live longer than the programs that created them. A competent developer should be able to create a solution in their preferred programming language to read most " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npy" }, { "__type": "Text", "__tag": 4046, "value": " files that they have been given without much documentation." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Allows memory-mapping of the data. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "open_memmap", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.lib.format:open_memmap" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Can be read from a filelike stream object instead of an actual file." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Stores object arrays, i.e. arrays containing elements that are arbitrary Python objects. Files with object arrays are not to be mmapable, but can be read and written to disk." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Capabilities" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Arbitrary subclasses of numpy.ndarray are not completely preserved. Subclasses will be accepted for writing, but only the array data will be written out. A regular numpy.ndarray object will be created upon reading the file." } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Due to limitations in the interpretation of structured dtypes, dtypes with fields with empty names will have the names replaced by 'f0', 'f1', etc. Such arrays will not round-trip through the format entirely accurately. The data is intact; only the field names will differ. We are working on a fix for this. This fix will not require a change in the file format. The arrays with such structures can still be saved and restored, and the correct dtype may be restored by using the " }, { "__type": "InlineCode", "__tag": 4051, "value": "loadedarray.view(correct_dtype)" }, { "__type": "Text", "__tag": 4046, "value": " method." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Limitations" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "We recommend using the " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npy" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npz" }, { "__type": "Text", "__tag": 4046, "value": " extensions for files saved in this format. This is by no means a requirement; applications may wish to use these file formats but use an extension specific to the application. In the absence of an obvious alternative, however, we suggest using " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npy" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npz" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "File extensions" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The version numbering of these formats is independent of NumPy version numbering. If the format is upgraded, the code in " }, { "__type": "InlineRole", "__tag": 4003, "value": "numpy.io", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " will still be able to read and write Version 1.0 files." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Version numbering" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The first 6 bytes are a magic string: exactly " }, { "__type": "InlineCode", "__tag": 4051, "value": "\\x93NUMPY" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The next 1 byte is an unsigned byte: the major version number of the file format, e.g. " }, { "__type": "InlineCode", "__tag": 4051, "value": "\\x01" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The next 1 byte is an unsigned byte: the minor version number of the file format, e.g. " }, { "__type": "InlineCode", "__tag": 4051, "value": "\\x00" }, { "__type": "Text", "__tag": 4046, "value": ". Note: the version of the file format is not tied to the version of the numpy package." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The next 2 bytes form a little-endian unsigned short int: the length of the header data HEADER_LEN." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The next HEADER_LEN bytes form the header data describing the array's format. It is an ASCII string which contains a Python literal expression of a dictionary. It is terminated by a newline (" }, { "__type": "InlineCode", "__tag": 4051, "value": "\\n" }, { "__type": "Text", "__tag": 4046, "value": ") and padded with spaces (" }, { "__type": "InlineCode", "__tag": 4051, "value": "\\x20" }, { "__type": "Text", "__tag": 4046, "value": ") to make the total of " }, { "__type": "InlineCode", "__tag": 4051, "value": "len(magic string) + 2 + len(length) + HEADER_LEN" }, { "__type": "Text", "__tag": 4046, "value": " be evenly divisible by 64 for alignment purposes." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The dictionary contains three keys:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "\"descr\"" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "\"descr\"" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "\"fortran_order\"" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "\"fortran_order\"" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "\"shape\"" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "\"shape\"" } ] } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For repeatability and readability, the dictionary keys are sorted in alphabetic order. This is for convenience only. A writer SHOULD implement this if possible. A reader MUST NOT depend on this." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Following the header comes the array data. If the dtype contains Python objects (i.e. " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype.hasobject is True" }, { "__type": "Text", "__tag": 4046, "value": "), then the data is a Python pickle of the array. Otherwise the data is the contiguous (either C- or Fortran-, depending on " }, { "__type": "InlineCode", "__tag": 4051, "value": "fortran_order" }, { "__type": "Text", "__tag": 4046, "value": ") bytes of the array. Consumers can figure out the number of bytes by multiplying the number of elements given by the shape (noting that " }, { "__type": "InlineCode", "__tag": 4051, "value": "shape=()" }, { "__type": "Text", "__tag": 4046, "value": " means there is 1 element) by " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype.itemsize" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Format Version 1.0" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The version 1.0 format only allowed the array header to have a total size of 65535 bytes. This can be exceeded by structured arrays with a large number of columns. The version 2.0 format extends the header size to 4 GiB. " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.save", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:save" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " will automatically save in 2.0 format if the data requires it, else it will always use the more compatible 1.0 format." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The description of the fourth element of the header therefore has become: \"The next 4 bytes form a little-endian unsigned int: the length of the header data HEADER_LEN.\"" } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Format Version 2.0" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This version replaces the ASCII string (which in practice was latin1) with a utf8-encoded string, so supports structured types with any unicode field names." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Format Version 3.0" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npy" }, { "__type": "Text", "__tag": 4046, "value": " format, including motivation for creating it and a comparison of alternatives, is described in the " }, { "__type": "CrossRef", "__tag": 4002, "value": "\"npy-format\" NEP", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "neps:nep-0001-npy-format" }, "kind": "docs" }, { "__type": "Text", "__tag": 4046, "value": ", however details have evolved with time and this document is more current." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Notes" } ], "level": 1, "target": null } ], "local_refs": [] }