Jun 9, 2022 · May 13, 2022 · May 13, 2022 · May 16, 2022 · May 16, 2022 · May 14, 2022
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst

      * ``"utf-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
      * ``"ascii"`` if Python detects that ``nl_langinfo(CODESET)`` announces
        the ASCII encoding (or Roman8 encoding on HP-UX), whereas the
        ``mbstowcs()`` function decodes from a different encoding (usually
        Latin1).
        the ASCII encoding, whereas the ``mbstowcs()`` function
        decodes from a different encoding (usually Latin1).
      * ``"utf-8"`` if ``nl_langinfo(CODESET)`` returns an empty string.
      * Otherwise, use the :term:`locale encoding`:
        ``nl_langinfo(CODESET)`` result.
diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst
 How do I copy a file?
 ---------------------

 The :mod:`shutil` module contains a :func:`~shutil.copyfile` function.  Note
 that on MacOS 9 it doesn't copy the resource fork and Finder info.
 The :mod:`shutil` module contains a :func:`~shutil.copyfile` function.
 Note that on Windows NTFS volumes, it does not copy
 `alternate data streams
 <https://en.wikipedia.org/wiki/NTFS#Alternate_data_stream_(ADS)>`_
 nor `resource forks <https://en.wikipedia.org/wiki/Resource_fork>`__
 on macOS HFS+ volumes, though both are now rarely used.
 It also doesn't copy file permissions and metadata, though using
 :func:`shutil.copy2` instead will preserve most (though not all) of it.


 How do I read (or write) binary data?
diff --git a/Doc/howto/sockets.rst b/Doc/howto/sockets.rst
 -----------

 It is perfectly possible to send binary data over a socket. The major problem is
 that not all machines use the same formats for binary data. For example, a
 Motorola chip will represent a 16 bit integer with the value 1 as the two hex
 bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00.
 that not all machines use the same formats for binary data. For example,
 `network byte order <https://en.wikipedia.org/wiki/Endianness#Networking>`_
 is big-endian, with the most significant byte first,
 so a 16 bit integer with the value ``1`` would be the two hex bytes ``00 01``.
 However, most common processors (x86/AMD64, ARM, RISC-V), are little-endian,
 with the least significant byte first - that same ``1`` would be ``01 00``.

 Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl,
 htonl, ntohs, htons`` where "n" means *network* and "h" means *host*, "s" means
 *short* and "l" means *long*. Where network order is host order, these do
 nothing, but where the machine is byte-reversed, these swap the bytes around
 appropriately.

 In these days of32bit machines, theascii representation of binary data is
 In these days of64-bit machines, theASCII representation of binary data is
 frequently smaller than the binary representation. That's because a surprising
 amount of the time, all those longs have the value 0, or maybe 1. The string "0"
 would be two bytes, while binary is four. Of course, this doesn't fit well with
 fixed-length messages. Decisions, decisions.
 amount of the time, most integers have the value 0, or maybe 1.
 The string ``"0"`` would be two bytes, while a full 64-bit integer would be 8.
 Of course, this doesn't fit well with fixed-length messages.
 Decisions, decisions.


 Disconnecting
diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst

   To ensure validity of the created memory mapping the file specified
   by the descriptor *fileno* is internally automatically synchronized
   with physical backing store on macOS and OpenVMS.
   withthephysical backing store on macOS.

   This example shows a simple way of using :class:`~mmap.mmap`::

diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst

 .. function:: machine()

   Returns the machine type, e.g. ``'i386'``. An empty string is returned if the
   Returns the machine type, e.g. ``'AMD64'``. An empty string is returned if the
   value cannot be determined.


diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst

 .. sectionauthor:: Steve Clift <clift@mail.anacapa.net>

 Several operating systems (including AIX, HP-UX and Solaris) provide
 Several operating systems (including AIX and Solaris) provide
 support for files that are larger than 2 GiB from a C programming model where
 :c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished
 by defining the relevant size and offset types as 64-bit values. Such files are
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst

 Native byte order is big-endian or little-endian, depending on the host
 system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
 Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature
 switchable endianness (bi-endian). Use ``sys.byteorder`` to check the
 endianness of your system.
 IBM z and most legacy architectures are big-endian;
 and ARM, RISC-V and IBM Power feature switchable endianness
 (bi-endian, though the former two are nearly always little-endian in practice).
 Use ``sys.byteorder`` to check the endianness of your system.

 Native size and alignment are determined using the C compiler's
 ``sizeof`` expression.  This is always combined with native byte order.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -735,9 +735,8 @@ PyConfig

		* ``"utf-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
		* ``"ascii"`` if Python detects that ``nl_langinfo(CODESET)`` announces
		the ASCII encoding (or Roman8 encoding on HP-UX), whereas the
		``mbstowcs()`` function decodes from a different encoding (usually
		Latin1).
		the ASCII encoding, whereas the ``mbstowcs()`` function
		decodes from a different encoding (usually Latin1).
		* ``"utf-8"`` if ``nl_langinfo(CODESET)`` returns an empty string.
		* Otherwise, use the :term:`locale encoding`:
		``nl_langinfo(CODESET)`` result.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -483,8 +483,14 @@ including :func:`~shutil.copyfile`, :func:`~shutil.copytree`, and
		How do I copy a file?
		---------------------

		The :mod:`shutil` module contains a :func:`~shutil.copyfile` function. Note
		that on MacOS 9 it doesn't copy the resource fork and Finder info.
		The :mod:`shutil` module contains a :func:`~shutil.copyfile` function.
serhiy-storchaka marked this conversation as resolved. Show resolvedHide resolved
		Note that on Windows NTFS volumes, it does not copy
		`alternate data streams
		<https://en.wikipedia.org/wiki/NTFS#Alternate_data_stream_(ADS)>`_
		nor `resource forks <https://en.wikipedia.org/wiki/Resource_fork>`__
		on macOS HFS+ volumes, though both are now rarely used.
		It also doesn't copy file permissions and metadata, though using
		:func:`shutil.copy2` instead will preserve most (though not all) of it.


		How do I read (or write) binary data?
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -252,20 +252,25 @@ Binary Data
		-----------

		It is perfectly possible to send binary data over a socket. The major problem is
		that not all machines use the same formats for binary data. For example, a
		Motorola chip will represent a 16 bit integer with the value 1 as the two hex
		bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00.
		that not all machines use the same formats for binary data. For example,
		`network byte order <https://en.wikipedia.org/wiki/Endianness#Networking>`_
		is big-endian, with the most significant byte first,
		so a 16 bit integer with the value ``1`` would be the two hex bytes ``00 01``.
		However, most common processors (x86/AMD64, ARM, RISC-V), are little-endian,
		with the least significant byte first - that same ``1`` would be ``01 00``.

		Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl,
		htonl, ntohs, htons`` where "n" means network and "h" means host, "s" means
		short and "l" means long. Where network order is host order, these do
		nothing, but where the machine is byte-reversed, these swap the bytes around
		appropriately.

		In these days of32bit machines, theascii representation of binary data is
		In these days of64-bit machines, theASCII representation of binary data is
		frequently smaller than the binary representation. That's because a surprising
		amount of the time, all those longs have the value 0, or maybe 1. The string "0"
		would be two bytes, while binary is four. Of course, this doesn't fit well with
		fixed-length messages. Decisions, decisions.
		amount of the time, most integers have the value 0, or maybe 1.
		The string ``"0"`` would be two bytes, while a full 64-bit integer would be 8.
		Of course, this doesn't fit well with fixed-length messages.
		Decisions, decisions.


		Disconnecting
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -102,7 +102,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length

		To ensure validity of the created memory mapping the file specified
		by the descriptor fileno is internally automatically synchronized
		with physical backing store on macOS and OpenVMS.
		withthephysical backing store on macOS.

		This example shows a simple way of using :class:`~mmap.mmap`::

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -53,7 +53,7 @@ Cross Platform

		.. function:: machine()

		Returns the machine type, e.g. ``'i386'``. An empty string is returned if the
		Returns the machine type, e.g. ``'AMD64'``. An empty string is returned if the
Copy link Member serhiy-storchakaMay 14, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Is it what returned on the AMD processors? On my computer it is 'x86_64'. Update also the docstring of platform.machine(). Copy link MemberAuthor CAM-GerlachMay 16, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. The original 'proper' name of what is also called the "x86-64" architecture is AMD64, as it was created by AMD and later adopted by Intel when Intel's IA-64 (Itanium) architecture failed in the market. What is returned depends (AFAIK) on the OS, not the CPU; Windows and many (most?) Linux distros call it`AMD64` internally, while Apple and some others call it`x86-64`. Running a freshly built from`main` Python, as well as 3.9 and 3.10 release builds,`platform.machine()` returns`AMD64` on my Windows system with a stock Intel i7-3730. Update also the docstring of platform.machine(). I can, but as this PR currently only modifies the docs, I'd rather do that separately; there are other places in the codebase that should be updated too, for consistency. Copy link Member serhiy-storchakaMay 16, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Docstrings are a part of the docs. If we do not update them together with the rst files, they are left desynchronized. AlexWaygood and erlend-aasland reacted with thumbs up emoji Copy link MemberAuthor CAM-GerlachMay 16, 2022• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. This only affects the choice of one specific example, both of which are equally accurate and valid, and which will be synchronized if and when I do a similar pass through the codebase itself. Several of the other`platform` functions, e.g.`system()`, have differing examples on each. And given the rest of this PR scrupulously avoids touching the code, adding this one trivial change has non-trivial cost, of triggering and requiring a whole suite of extra builds/CIs, and increasing risk for backporting. Given the change was minor and not strictly required in the first place, and I almost didn't make it, if this is going to be a big issue I'll just drop this change instead, since its not at all worth the cost. Copy link Member serhiy-storchakaMay 30, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Either way the docstrings and the documentation should be consistent. AlexWaygood reacted with thumbs up emoji
		value cannot be determined.


Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -37,7 +37,7 @@ Large File Support

		.. sectionauthor:: Steve Clift <clift@mail.anacapa.net>

		Several operating systems (including AIX, HP-UX and Solaris) provide
		Several operating systems (including AIX and Solaris) provide
		support for files that are larger than 2 GiB from a C programming model where
		:c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished
		by defining the relevant size and offset types as 64-bit values. Such files are
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -146,9 +146,10 @@ If the first character is not one of these, ``'@'`` is assumed.

		Native byte order is big-endian or little-endian, depending on the host
		system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
		Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature
		switchable endianness (bi-endian). Use ``sys.byteorder`` to check the
		endianness of your system.
		IBM z and most legacy architectures are big-endian;
		and ARM, RISC-V and IBM Power feature switchable endianness
		(bi-endian, though the former two are nearly always little-endian in practice).
		Use ``sys.byteorder`` to check the endianness of your system.

		Native size and alignment are determined using the C compiler's
		``sizeof`` expression. This is always combined with native byte order.
Expand Down