{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The memmap object can be used anywhere an ndarray is accepted. Given a memmap " }, { "__type": "InlineCode", "__tag": 4051, "value": "fp" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "isinstance(fp, numpy.ndarray)" }, { "__type": "Text", "__tag": 4046, "value": " returns " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Memory-mapped files cannot be larger than 2GB on 32-bit systems." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When a memmap causes a file to be created or extended beyond its current size in the filesystem, the contents of the new part are unspecified. On systems with POSIX filesystem semantics, the extended part will be filled with zero bytes." } ] } ], "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "flush", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Flush any changes in memory to file on disk. When you delete a memmap object, flush is called first to write changes to disk." } ] } ] } ] } ], "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": "Create a memory-map to an array stored in a " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "binary" } ] }, { "__type": "Text", "__tag": 4046, "value": " file on disk." } ] } ], "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "filename", "annotation": "str or pathlib.Path instance", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Path to the mapped file." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "offset", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Offset position in the file." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "mode", "annotation": "str", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "File mode." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "filename", "annotation": "str, file-like object, or pathlib.Path instance", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The file name or file object to be used as the array data buffer." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "dtype", "annotation": "data-type, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The data-type used to interpret the file contents. Default is " }, { "__type": "InlineRole", "__tag": 4003, "value": "uint8", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "mode", "annotation": "{'r+', 'r', 'w+', 'c'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The file is opened in this mode:" } ] }, { "__type": "Code", "__tag": 4050, "value": "+------+-------------------------------------------------------------+\n| 'r' | Open existing file for reading only. |\n+------+-------------------------------------------------------------+\n| 'r+' | Open existing file for reading and writing. |\n+------+-------------------------------------------------------------+\n| 'w+' | Create or overwrite existing file for reading and writing. |\n| | If ``mode == 'w+'`` then `shape` must also be specified. |\n+------+-------------------------------------------------------------+\n| 'c' | Copy-on-write: assignments affect data in memory, but |\n| | changes are not saved to disk. The file on disk is |\n| | read-only. |\n+------+-------------------------------------------------------------+", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Default is 'r+'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "offset", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the file, array data starts at this offset. Since " }, { "__type": "ParamRef", "__tag": 4071, "name": "offset" }, { "__type": "Text", "__tag": 4046, "value": " is measured in bytes, it should normally be a multiple of the byte-size of " }, { "__type": "ParamRef", "__tag": 4071, "name": "dtype" }, { "__type": "Text", "__tag": 4046, "value": ". When " }, { "__type": "InlineCode", "__tag": 4051, "value": "mode != 'r'" }, { "__type": "Text", "__tag": 4046, "value": ", even positive offsets beyond end of file are valid; The file will be extended to accommodate the additional data. By default, " }, { "__type": "InlineCode", "__tag": 4051, "value": "memmap" }, { "__type": "Text", "__tag": 4046, "value": " will start at the beginning of the file, even if " }, { "__type": "InlineCode", "__tag": 4051, "value": "filename" }, { "__type": "Text", "__tag": 4046, "value": " is a file pointer " }, { "__type": "InlineCode", "__tag": 4051, "value": "fp" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "fp.tell() != 0" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "shape", "annotation": "int or sequence of ints, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The desired shape of the array. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "mode == 'r'" }, { "__type": "Text", "__tag": 4046, "value": " and the number of remaining bytes after " }, { "__type": "ParamRef", "__tag": 4071, "name": "offset" }, { "__type": "Text", "__tag": 4046, "value": " is not a multiple of the byte-size of " }, { "__type": "ParamRef", "__tag": 4071, "name": "dtype" }, { "__type": "Text", "__tag": 4046, "value": ", you must specify " }, { "__type": "ParamRef", "__tag": 4071, "name": "shape" }, { "__type": "Text", "__tag": 4046, "value": ". By default, the returned array will be 1-D with the number of elements determined by file size and data-type." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged 2.0" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The shape parameter can now be any integer sequence type, previously types were limited to tuple and int." } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "order", "annotation": "{'C', 'F'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Specify the order of the ndarray memory layout: " }, { "__type": "InlineCode", "__tag": 4051, "value": "row-major" }, { "__type": "Text", "__tag": 4046, "value": ", C-style or " }, { "__type": "InlineCode", "__tag": 4051, "value": "column-major" }, { "__type": "Text", "__tag": 4046, "value": ", Fortran-style. This only has an effect if the shape is greater than 1-D. The default order is 'C'." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Memory-mapped files are used for accessing small segments of large files on disk, without reading the entire file into memory. NumPy's memmap's are array-like objects. This differs from Python's " }, { "__type": "InlineCode", "__tag": 4051, "value": "mmap" }, { "__type": "Text", "__tag": 4046, "value": " module, which uses file-like objects." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This subclass of ndarray has some unpleasant interactions with some operations, because it doesn't quite fit properly as a subclass. An alternative to using this subclass is to create the " }, { "__type": "InlineCode", "__tag": 4051, "value": "mmap" }, { "__type": "Text", "__tag": 4046, "value": " object yourself, then create an ndarray with ndarray.__new__ directly, passing the object created in its 'buffer=' parameter." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This class may at some point be turned into a factory function which returns a view into an mmap buffer." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Flush the memmap instance to write the changes to the file. Currently there is no API to close the underlying " }, { "__type": "InlineCode", "__tag": 4051, "value": "mmap" }, { "__type": "Text", "__tag": 4046, "value": ". It is tricky to ensure the resource is actually closed, since it may be shared between different memmap instances." } ] } ], "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": "/dev/numpy/build-install/usr/lib/python3.14/site-packages/numpy/__init__.py", "item_line": null, "item_type": "class", "aliases": [ "numpy.memmap" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\ndata = np.arange(12, dtype='float32')\ndata.resize((3,4))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThis example uses a temporary file so that doctest doesn't write\nfiles to your directory. You would use a 'normal' filename.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from tempfile import mkdtemp\nimport os.path as path\nfilename = path.join(mkdtemp(), 'newfile.dat')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCreate a memmap with dtype and shape that matches our data:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fp = np.memmap(filename, dtype='float32', mode='w+', shape=(3,4))\nfp\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWrite data to memmap array:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fp[:] = data[:]\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "fp\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "fp.filename == path.abspath(filename)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFlushes memory changes to disk in order to read them back\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fp.flush()\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nLoad the memmap and verify data was stored:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "newfp = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "newfp\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nRead-only memmap:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fpr = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))\nfpr.flags.writeable\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCopy-on-write memmap:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fpc = np.memmap(filename, dtype='float32', mode='c', shape=(3,4))\nfpc.flags.writeable\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIt's possible to assign to copy-on-write array, but values are only\nwritten into the memory copy of the array, and not written to disk:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fpc\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "fpc[0,:] = 0\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "fpc\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nFile on disk is unchanged:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fpr\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nOffset into a memmap:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fpo = np.memmap(filename, dtype='float32', mode='r', offset=16)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "fpo\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "lib.format.open_memmap", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "lib.format.open_memmap" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create or load a memory-mapped " }, { "__type": "InlineCode", "__tag": 4051, "value": ".npy" }, { "__type": "Text", "__tag": 4046, "value": " file." } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "filename", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "dtype", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "" }, { "__type": "SigParam", "__tag": 4030, "name": "mode", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "r+" }, { "__type": "SigParam", "__tag": 4030, "name": "offset", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "shape", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "order", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "C" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "memmap" }, "references": null, "qa": "numpy:memmap", "arbitrary": [], "local_refs": [ "dtype", "filename", "flush", "mode", "offset", "order", "shape" ] }