17
18
class memmap(ndarray):
19
"""Create a memory-map to an array stored in a file on disk.
21
Memory-mapped files are used for accessing small segments of large files
22
on disk, without reading the entire file into memory. Numpy's memmaps are
23
array-like objects. This differs from python's mmap module which are
28
filename : string or file-like object
29
The file name or file object to be used as the array data
31
dtype : data-type, optional
32
The data-type used to interpret the file contents.
34
mode : {'r', 'r+', 'w+', 'c'}, optional
35
The mode to open the file.
36
'r', open existing file for read-only
37
'r+', open existing file for read-write
38
'w+', create or overwrite existing file and open for read-write
39
'c', copy-on-write, assignments effect data in memory, but changes
40
are not saved to disk. File on disk is read-only.
42
offset : integer, optional
43
Byte offset into the file to start the array data. Should be a
44
multiple of the data-type of the data. Requires shape=None.
46
shape : tuple, optional
47
The desired shape of the array. If None, the returned array will be 1-D
48
with the number of elements determined by file size and data-type.
50
order : {'C', 'F'}, optional
51
Specify the order of the N-D array, C or Fortran ordered. This only
52
has an effect if the shape is greater than 2-D.
57
close : close the memmap file
58
flush : flush any changes in memory to file on disk
59
When you delete a memmap object, flush is called first to write
60
changes to disk before removing the object.
64
memmap : array-like memmap object
65
The memmap object can be used anywhere an ndarray is accepted.
66
If fp is a memmap, isinstance(fp, numpy.ndarray) will return True.
70
>>> import numpy as np
71
>>> data = np.arange(12, dtype='float32')
72
>>> data.resize((3,4))
74
>>> # Using a tempfile so doctest doesn't write files to your directory.
75
>>> # You would use a 'normal' filename.
76
>>> from tempfile import mkdtemp
77
>>> import os.path as path
78
>>> filename = path.join(mkdtemp(), 'newfile.dat')
80
>>> # Create a memmap with dtype and shape that matches our data
81
>>> fp = np.memmap(filename, dtype='float32', mode='w+', shape=(3,4))
83
memmap([[ 0., 0., 0., 0.],
85
[ 0., 0., 0., 0.]], dtype=float32)
87
>>> # Write data to memmap array
90
memmap([[ 0., 1., 2., 3.],
92
[ 8., 9., 10., 11.]], dtype=float32)
94
>>> # Deletion flushes memory changes to disk before removing the object.
96
>>> # Load the memmap and verify data was stored
97
>>> newfp = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))
99
memmap([[ 0., 1., 2., 3.],
101
[ 8., 9., 10., 11.]], dtype=float32)
103
>>> # read-only memmap
104
>>> fpr = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))
105
>>> fpr.flags.writeable
107
>>> # Cannot assign to read-only, obviously
109
Traceback (most recent call last):
111
RuntimeError: array is not writeable
113
>>> # copy-on-write memmap
114
>>> fpc = np.memmap(filename, dtype='float32', mode='c', shape=(3,4))
115
>>> fpc.flags.writeable
117
>>> # Can assign to copy-on-write array, but values are only written
118
>>> # into the memory copy of the array, and not written to disk.
120
memmap([[ 0., 1., 2., 3.],
122
[ 8., 9., 10., 11.]], dtype=float32)
125
memmap([[ 0., 0., 0., 0.],
127
[ 8., 9., 10., 11.]], dtype=float32)
128
>>> # file on disk is unchanged
130
memmap([[ 0., 1., 2., 3.],
132
[ 8., 9., 10., 11.]], dtype=float32)
134
>>> # offset into a memmap
135
>>> fpo = np.memmap(filename, dtype='float32', mode='r', offset=16)
137
memmap([ 4., 5., 6., 7., 8., 9., 10., 11.], dtype=float32)
18
141
__array_priority__ = -100.0
19
def __new__(subtype, name, dtype=uint8, mode='r+', offset=0,
142
def __new__(subtype, filename, dtype=uint8, mode='r+', offset=0,
20
143
shape=None, order='C'):
22
145
mode = mode_equivalents[mode]
72
198
self._offset = offset
201
self._name = filename
79
204
def __array_finalize__(self, obj):
80
if obj is not None and not isinstance(obj, memmap):
81
raise ValueError, "Cannot create a memmap array that way"
205
if hasattr(obj, '_mmap'):
206
self._mmap = obj._mmap
211
"""Flush any changes in the array to the file on disk."""
212
if self._mmap is not None:
216
"""Flush any changes in the array to the file on disk."""
217
warnings.warn("Use ``flush``.", DeprecationWarning)
221
"""Close the memmap file. Only do this when deleting the object."""
222
if self.base is self._mmap:
226
# DEV NOTE: This error is raised on the deletion of each row
227
# in a view of this memmap. Python traps exceptions in
228
# __del__ and prints them to stderr. Suppressing this for now
229
# until memmap code is cleaned up and and better tested for
230
# numpy v1.1 Objects that do not have a python mmap instance
231
# as their base data array, should not do anything in the
233
#elif self._mmap is not None:
234
#raise ValueError, "Cannot close a memmap that is being used " \
235
# "by another object."
238
"""Close the memmap file. Does nothing."""
239
warnings.warn("``close`` is deprecated on memmap arrays. Use del",
87
242
def __del__(self):
88
243
if self._mmap is not None:
245
# First run tell() to see whether file is open
250
# flush any changes to disk, even if it's a view
added
removed
numpy/core/memmap.py
