From b5520a2396f87d8511cbd7534aa543b13150592c Mon Sep 17 00:00:00 2001 From: Boy Steven Benaya Aritonang Date: Wed, 15 Jul 2026 18:55:38 +0700 Subject: [PATCH 1/2] gh-151950: Fix Sphinx references in mmap documentation --- Doc/library/mmap.rst | 70 +++++++++++++++++++++++++++++++++----------- Doc/tools/.nitignore | 1 - 2 files changed, 53 insertions(+), 18 deletions(-) diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst index 774d05fdcaa3007..3a4dcfc4e7c9b89 100644 --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -14,7 +14,8 @@ where :class:`bytearray` are expected; for example, you can use the :mod:`re` module to search through a memory-mapped file. You can also change a single byte by doing ``obj[index] = 97``, or change a subsequence by assigning to a slice: ``obj[i1:i2] = b'...'``. You can also read and write data starting at -the current file position, and :meth:`seek` through the file to different positions. +the current file position, and :meth:`~mmap.mmap.seek` through the file to +different positions. A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is different on Unix and on Windows. In either case you must provide a file @@ -30,21 +31,26 @@ still needs to be closed when done). that local modifications to the buffers are actually available to the mapping. -For both the Unix and Windows versions of the constructor, *access* may be -specified as an optional keyword parameter. *access* accepts one of four -values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to -specify read-only, write-through or copy-on-write memory respectively, or -:const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both Unix -and Windows. If *access* is not specified, Windows mmap returns a -write-through mapping. The initial memory values for all three access types -are taken from the specified file. Assignment to an :const:`ACCESS_READ` -memory map raises a :exc:`TypeError` exception. Assignment to an -:const:`ACCESS_WRITE` memory map affects both memory and the underlying file. -Assignment to an :const:`ACCESS_COPY` memory map affects memory but does not -update the underlying file. - -.. versionchanged:: 3.7 - Added :const:`ACCESS_DEFAULT` constant. +.. data:: ACCESS_DEFAULT + ACCESS_READ + ACCESS_WRITE + ACCESS_COPY + + For both the Unix and Windows versions of the constructor, *access* may be + specified as an optional keyword parameter. *access* accepts one of four + values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` + to specify read-only, write-through or copy-on-write memory respectively, + or :const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both + Unix and Windows. If *access* is not specified, Windows mmap returns a + write-through mapping. The initial memory values for all three access + types are taken from the specified file. Assignment to an + :const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception. + Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and + the underlying file. Assignment to an :const:`ACCESS_COPY` memory map + affects memory but does not update the underlying file. + + .. versionchanged:: 3.7 + Added :const:`ACCESS_DEFAULT` constant. To map anonymous memory, -1 should be passed as the fileno along with the length. @@ -103,7 +109,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length *prot*, if specified, gives the desired memory protection; the two most useful values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify that the pages may be read or written. *prot* defaults to - :const:`PROT_READ \| PROT_WRITE`. + :const:`PROT_READ` \| :const:`PROT_WRITE`. *access* may be specified in lieu of *flags* and *prot* as an optional keyword parameter. It is an error to specify both *flags*, *prot* and @@ -386,6 +392,36 @@ To map anonymous memory, -1 should be passed as the fileno along with the length the mmap was created with :const:`ACCESS_READ`, then writing to it will raise a :exc:`TypeError` exception. +.. _page-size-constants: + +Page Size Constants ++++++++++++++++++++ + +.. data:: PAGESIZE + ALLOCATIONGRANULARITY + + :const:`PAGESIZE` is the system memory page size in bytes. + :const:`ALLOCATIONGRANULARITY` is the minimum alignment in bytes required + for the *offset* argument of :class:`mmap`. On Unix, + :const:`ALLOCATIONGRANULARITY` is equal to :const:`PAGESIZE`. + +.. _prot-constants: + +PROT_* Constants +++++++++++++++++ + +.. data:: PROT_READ + PROT_WRITE + PROT_EXEC + + Memory protection flags accepted by the *prot* argument of :class:`mmap`. + :const:`PROT_READ` allows pages to be read, :const:`PROT_WRITE` allows pages + to be written, and :const:`PROT_EXEC` allows pages to be executed. Values + can be combined using the bitwise OR operator. Not every option is present + on every system. + + Availability: Unix. + .. _madvise-constants: MADV_* Constants diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 38f082ca37e48d4..77289370c77abee 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -8,7 +8,6 @@ Doc/library/email.charset.rst Doc/library/email.parser.rst Doc/library/logging.config.rst Doc/library/logging.handlers.rst -Doc/library/mmap.rst Doc/library/multiprocessing.rst Doc/library/optparse.rst Doc/library/pickletools.rst From d1c44f9c384a8f8f114496dc3fc337601c7d5882 Mon Sep 17 00:00:00 2001 From: Boy Steven Benaya Aritonang Date: Tue, 20 Oct 2026 04:04:11 +0700 Subject: [PATCH 2/2] gh-151950: Reorganize mmap constant documentation Restore the introductory prose and document ACCESS_* in a separate section. Use sentence case for headings and the availability directive. --- Doc/library/mmap.rst | 63 ++++++++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 26 deletions(-) diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst index 3a4dcfc4e7c9b89..e06a702d0b59f68 100644 --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -31,26 +31,21 @@ still needs to be closed when done). that local modifications to the buffers are actually available to the mapping. -.. data:: ACCESS_DEFAULT - ACCESS_READ - ACCESS_WRITE - ACCESS_COPY - - For both the Unix and Windows versions of the constructor, *access* may be - specified as an optional keyword parameter. *access* accepts one of four - values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` - to specify read-only, write-through or copy-on-write memory respectively, - or :const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both - Unix and Windows. If *access* is not specified, Windows mmap returns a - write-through mapping. The initial memory values for all three access - types are taken from the specified file. Assignment to an - :const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception. - Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and - the underlying file. Assignment to an :const:`ACCESS_COPY` memory map - affects memory but does not update the underlying file. - - .. versionchanged:: 3.7 - Added :const:`ACCESS_DEFAULT` constant. +For both the Unix and Windows versions of the constructor, *access* may be +specified as an optional keyword parameter. *access* accepts one of four +values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to +specify read-only, write-through or copy-on-write memory respectively, or +:const:`ACCESS_DEFAULT` to defer to *prot*. *access* can be used on both Unix +and Windows. If *access* is not specified, Windows mmap returns a +write-through mapping. The initial memory values for all three access types +are taken from the specified file. Assignment to an :const:`ACCESS_READ` +memory map raises a :exc:`TypeError` exception. Assignment to an +:const:`ACCESS_WRITE` memory map affects both memory and the underlying file. +Assignment to an :const:`ACCESS_COPY` memory map affects memory but does not +update the underlying file. + +.. versionchanged:: 3.7 + Added :const:`ACCESS_DEFAULT` constant. To map anonymous memory, -1 should be passed as the fileno along with the length. @@ -392,9 +387,25 @@ To map anonymous memory, -1 should be passed as the fileno along with the length the mmap was created with :const:`ACCESS_READ`, then writing to it will raise a :exc:`TypeError` exception. +.. _access-constants: + +ACCESS_* constants +++++++++++++++++++ + +.. data:: ACCESS_DEFAULT + ACCESS_READ + ACCESS_WRITE + ACCESS_COPY + + These constants specify the access mode for a memory mapping. + :const:`ACCESS_READ` provides read-only access, :const:`ACCESS_WRITE` + provides write-through access, and :const:`ACCESS_COPY` provides + copy-on-write access. :const:`ACCESS_DEFAULT` defers to the *prot* + argument of :class:`mmap`. + .. _page-size-constants: -Page Size Constants +Page size constants +++++++++++++++++++ .. data:: PAGESIZE @@ -407,7 +418,7 @@ Page Size Constants .. _prot-constants: -PROT_* Constants +PROT_* constants ++++++++++++++++ .. data:: PROT_READ @@ -420,11 +431,11 @@ PROT_* Constants can be combined using the bitwise OR operator. Not every option is present on every system. - Availability: Unix. + .. availability:: Unix. .. _madvise-constants: -MADV_* Constants +MADV_* constants ++++++++++++++++ .. data:: MADV_NORMAL @@ -461,7 +472,7 @@ MADV_* Constants .. _map-constants: -MAP_* Constants +MAP_* constants +++++++++++++++ .. data:: MAP_SHARED @@ -508,7 +519,7 @@ MAP_* Constants .. _ms-constants: -MS_* Constants +MS_* constants ++++++++++++++ .. data:: MS_SYNC