88
99Memory-mapped file objects behave like both strings and like file objects.
1010Unlike normal string objects, however, these are mutable. You can use mmap
11- objects in most places where strings are expected; for example, you can use the
12- :mod: `re ` module to search through a memory-mapped file. Since they're mutable,
13- you can change a single character by doing ``obj[index] = 'a' ``, or change a
14- substring by assigning to a slice: ``obj[i1:i2] = '...' ``. You can also read
15- and write data starting at the current file position, and :meth: ` seek ` through
16- the file to different positions.
17-
18- A memory-mapped file is created by the :class: `mmap ` constructor, which is different
19- on Unix and on Windows. In either case you must provide a file descriptor for a
20- file opened for update. If you wish to map an existing Python file object, use
21- its :meth: `fileno ` method to obtain the correct value for the * fileno *
22- parameter. Otherwise, you can open the file using the :func: ` os.open ` function,
23- which returns a file descriptor directly (the file still needs to be closed when
24- done).
11+ objects in most places where strings are expected; for example, you can use
12+ the :mod: `re ` module to search through a memory-mapped file. Since they're
13+ mutable, you can change a single character by doing ``obj[index] = 'a' ``, or
14+ change a substring by assigning to a slice: ``obj[i1:i2] = '...' ``. You can
15+ also read and write data starting at the current file position, and
16+ :meth: ` seek ` through the file to different positions.
17+
18+ A memory-mapped file is created by the :class: `mmap ` constructor, which is
19+ different on Unix and on Windows. In either case you must provide a file
20+ descriptor for a file opened for update. If you wish to map an existing Python
21+ file object, use its :meth: `fileno ` method to obtain the correct value for the
22+ * fileno * parameter. Otherwise, you can open the file using the
23+ :func: ` os.open ` function, which returns a file descriptor directly (the file
24+ still needs to be closed when done).
2525
2626For both the Unix and Windows versions of the constructor, *access * may be
2727specified as an optional keyword parameter. *access * accepts one of three
28- values: :const: `ACCESS_READ `, :const: `ACCESS_WRITE `, or :const: `ACCESS_COPY ` to
29- specify readonly , write-through or copy-on-write memory respectively. * access *
30- can be used on both Unix and Windows. If *access * is not specified, Windows
31- mmap returns a write-through mapping. The initial memory values for all three
32- access types are taken from the specified file. Assignment to an
33- :const: `ACCESS_READ ` memory map raises a :exc: `TypeError ` exception. Assignment
34- to an :const: `ACCESS_WRITE ` memory map affects both memory and the underlying
35- file. Assignment to an :const: `ACCESS_COPY ` memory map affects memory but does
36- not update the underlying file.
28+ values: :const: `ACCESS_READ `, :const: `ACCESS_WRITE `, or :const: `ACCESS_COPY `
29+ to specify read-only , write-through or copy-on-write memory respectively.
30+ * access * can be used on both Unix and Windows. If *access * is not specified,
31+ Windows mmap returns a write-through mapping. The initial memory values for
32+ all three access types are taken from the specified file. Assignment to an
33+ :const: `ACCESS_READ ` memory map raises a :exc: `TypeError ` exception.
34+ Assignment to an :const: `ACCESS_WRITE ` memory map affects both memory and the
35+ underlying file. Assignment to an :const: `ACCESS_COPY ` memory map affects
36+ memory but does not update the underlying file.
3737
3838To map anonymous memory, -1 should be passed as the fileno along with the length.
3939
4040.. class :: mmap(fileno, length[, tagname[, access[, offset]]])
4141
42- **(Windows version) ** Maps *length * bytes from the file specified by the file
43- handle *fileno *, and creates a mmap object. If *length * is larger than the
44- current size of the file, the file is extended to contain *length * bytes. If
45- *length * is ``0 ``, the maximum length of the map is the current size of the
46- file, except that if the file is empty Windows raises an exception (you cannot
47- create an empty mapping on Windows).
42+ **(Windows version) ** Maps *length * bytes from the file specified by the
43+ file handle *fileno *, and creates a mmap object. If *length * is larger
44+ than the current size of the file, the file is extended to contain *length *
45+ bytes. If *length * is ``0 ``, the maximum length of the map is the current
46+ size of the file, except that if the file is empty Windows raises an
47+ exception (you cannot create an empty mapping on Windows).
4848
49- *tagname *, if specified and not ``None ``, is a string giving a tag name for the
50- mapping. Windows allows you to have many different mappings against the same
51- file. If you specify the name of an existing tag, that tag is opened, otherwise
52- a new tag of this name is created. If this parameter is omitted or ``None ``,
53- the mapping is created without a name. Avoiding the use of the tag parameter
54- will assist in keeping your code portable between Unix and Windows.
49+ *tagname *, if specified and not ``None ``, is a string giving a tag name for
50+ the mapping. Windows allows you to have many different mappings against
51+ the same file. If you specify the name of an existing tag, that tag is
52+ opened, otherwise a new tag of this name is created. If this parameter is
53+ omitted or ``None ``, the mapping is created without a name. Avoiding the
54+ use of the tag parameter will assist in keeping your code portable between
55+ Unix and Windows.
5556
56- *offset * may be specified as a non-negative integer offset. mmap references will
57- be relative to the offset from the beginning of the file. *offset * defaults to 0.
58- *offset * must be a multiple of the ALLOCATIONGRANULARITY.
57+ *offset * may be specified as a non-negative integer offset. mmap references
58+ will be relative to the offset from the beginning of the file. *offset *
59+ defaults to 0. *offset * must be a multiple of the ALLOCATIONGRANULARITY.
5960
6061
6162.. class :: mmap(fileno, length[, flags[, prot[, access[, offset]]]])
6263 :noindex:
6364
6465 **(Unix version) ** Maps *length * bytes from the file specified by the file
6566 descriptor *fileno *, and returns a mmap object. If *length * is ``0 ``, the
66- maximum length of the map will be the current size of the file when :class: ` mmap `
67- is called.
67+ maximum length of the map will be the current size of the file when
68+ :class: ` mmap ` is called.
6869
6970 *flags * specifies the nature of the mapping. :const: `MAP_PRIVATE ` creates a
70- private copy-on-write mapping, so changes to the contents of the mmap object
71- will be private to this process, and :const: `MAP_SHARED ` creates a mapping
72- that's shared with all other processes mapping the same areas of the file. The
73- default value is :const: `MAP_SHARED `.
74-
75- *prot *, if specified, gives the desired memory protection; the two most useful
76- values are :const: `PROT_READ ` and :const: `PROT_WRITE `, to specify that the pages
77- may be read or written. *prot * defaults to :const: `PROT_READ \| PROT_WRITE `.
78-
79- *access * may be specified in lieu of *flags * and *prot * as an optional keyword
80- parameter. It is an error to specify both *flags *, *prot * and *access *. See
81- the description of *access * above for information on how to use this parameter.
82-
83- *offset * may be specified as a non-negative integer offset. mmap references will
84- be relative to the offset from the beginning of the file. *offset * defaults to 0.
85- *offset * must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY.
71+ private copy-on-write mapping, so changes to the contents of the mmap
72+ object will be private to this process, and :const: `MAP_SHARED ` creates a
73+ mapping that's shared with all other processes mapping the same areas of
74+ the file. The default value is :const: `MAP_SHARED `.
75+
76+ *prot *, if specified, gives the desired memory protection; the two most
77+ useful values are :const: `PROT_READ ` and :const: `PROT_WRITE `, to specify
78+ that the pages may be read or written. *prot * defaults to
79+ :const: `PROT_READ \| PROT_WRITE `.
80+
81+ *access * may be specified in lieu of *flags * and *prot * as an optional
82+ keyword parameter. It is an error to specify both *flags *, *prot * and
83+ *access *. See the description of *access * above for information on how to
84+ use this parameter.
85+
86+ *offset * may be specified as a non-negative integer offset. mmap references
87+ will be relative to the offset from the beginning of the file. *offset *
88+ defaults to 0. *offset * must be a multiple of the PAGESIZE or
89+ ALLOCATIONGRANULARITY.
8690
8791 This example shows a simple way of using :class: `mmap `::
8892
@@ -132,32 +136,38 @@ Memory-mapped file objects support the following methods:
132136
133137.. method :: mmap.close()
134138
135- Close the file. Subsequent calls to other methods of the object will result in
136- an exception being raised.
139+ Close the file. Subsequent calls to other methods of the object will
140+ result in an exception being raised.
137141
138142
139143.. method :: mmap.find(string[, start[, end]])
140144
141- Returns the lowest index in the object where the substring *string * is found,
142- such that *string * is contained in the range [*start *, *end *]. Optional
143- arguments *start * and *end * are interpreted as in slice notation.
145+ Returns the lowest index in the object where the substring *string * is
146+ found, such that *string * is contained in the range [*start *, *end *].
147+ Optional arguments *start * and *end * are interpreted as in slice notation.
144148 Returns ``-1 `` on failure.
145149
146150
147151.. method :: mmap.flush([offset, size])
148152
149- Flushes changes made to the in-memory copy of a file back to disk. Without use
150- of this call there is no guarantee that changes are written back before the
151- object is destroyed. If *offset * and *size * are specified, only changes to the
152- given range of bytes will be flushed to disk; otherwise, the whole extent of the
153- mapping is flushed.
153+ Flushes changes made to the in-memory copy of a file back to disk. Without
154+ use of this call there is no guarantee that changes are written back before
155+ the object is destroyed. If *offset * and *size * are specified, only
156+ changes to the given range of bytes will be flushed to disk; otherwise, the
157+ whole extent of the mapping is flushed.
158+
159+ **(Windows version) ** A nonzero value returned indicates success; zero
160+ indicates failure.
161+
162+ **(Unix version) ** A zero value is returned to indicate success. An
163+ exception is raised when the call failed.
154164
155165
156166.. method :: mmap.move(dest, src, count)
157167
158- Copy the *count * bytes starting at offset *src * to the destination index * dest *.
159- If the mmap was created with :const: `ACCESS_READ `, then calls to move will throw
160- a :exc: `TypeError ` exception.
168+ Copy the *count * bytes starting at offset *src * to the destination index
169+ * dest *. If the mmap was created with :const: `ACCESS_READ `, then calls to
170+ move will throw a :exc: `TypeError ` exception.
161171
162172
163173.. method :: mmap.read(num)
@@ -175,31 +185,31 @@ Memory-mapped file objects support the following methods:
175185
176186.. method :: mmap.readline()
177187
178- Returns a single line, starting at the current file position and up to the next
179- newline.
188+ Returns a single line, starting at the current file position and up to the
189+ next newline.
180190
181191
182192.. method :: mmap.resize(newsize)
183193
184- Resizes the map and the underlying file, if any. If the mmap was created with
185- :const: `ACCESS_READ ` or :const: `ACCESS_COPY `, resizing the map will throw a
186- :exc: `TypeError ` exception.
194+ Resizes the map and the underlying file, if any. If the mmap was created
195+ with :const: `ACCESS_READ ` or :const: `ACCESS_COPY `, resizing the map will
196+ throw a :exc: `TypeError ` exception.
187197
188198
189199.. method :: mmap.rfind(string[, start[, end]])
190200
191201 Returns the highest index in the object where the substring *string * is
192- found, such that *string * is contained in the range [*start *,
193- * end *]. Optional arguments *start * and *end * are interpreted as in slice
194- notation. Returns ``-1 `` on failure.
202+ found, such that *string * is contained in the range [*start *, * end *].
203+ Optional arguments *start * and *end * are interpreted as in slice notation.
204+ Returns ``-1 `` on failure.
195205
196206
197207.. method :: mmap.seek(pos[, whence])
198208
199- Set the file's current position. *whence * argument is optional and defaults to
200- ``os.SEEK_SET `` or ``0 `` (absolute file positioning); other values are
201- ``os.SEEK_CUR `` or ``1 `` (seek relative to the current position) and
202- ``os.SEEK_END `` or ``2 `` (seek relative to the file's end).
209+ Set the file's current position. *whence * argument is optional and
210+ defaults to ``os.SEEK_SET `` or ``0 `` (absolute file positioning); other
211+ values are ``os.SEEK_CUR `` or ``1 `` (seek relative to the current position)
212+ and ``os.SEEK_END `` or ``2 `` (seek relative to the file's end).
203213
204214
205215.. method :: mmap.size()
@@ -217,15 +227,15 @@ Memory-mapped file objects support the following methods:
217227
218228 Write the bytes in *string * into memory at the current position of the file
219229 pointer; the file position is updated to point after the bytes that were
220- written. If the mmap was created with :const: `ACCESS_READ `, then writing to it
221- will throw a :exc: `TypeError ` exception.
230+ written. If the mmap was created with :const: `ACCESS_READ `, then writing to
231+ it will throw a :exc: `TypeError ` exception.
222232
223233
224234.. method :: mmap.write_byte(byte)
225235
226- Write the single-character string *byte * into memory at the current position of
227- the file pointer; the file position is advanced by ``1 ``. If the mmap was
228- created with :const: `ACCESS_READ `, then writing to it will throw a
229- :exc: `TypeError ` exception.
236+ Write the single-character string *byte * into memory at the current
237+ position of the file pointer; the file position is advanced by ``1 ``. If
238+ the mmap was created with :const: `ACCESS_READ `, then writing to it will
239+ throw a :exc: `TypeError ` exception.
230240
231241
0 commit comments