From 6032ecb31ecdb9c2e45e415e98dad76a59e0a8a6 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Fri, 13 May 2022 18:21:10 -0500 Subject: [PATCH 1/4] Doc: Update/elide mentions of EoL OSes that Python no longer supports --- Doc/c-api/init_config.rst | 5 ++--- Doc/faq/library.rst | 3 +-- Doc/library/mmap.rst | 2 +- Doc/library/posix.rst | 2 +- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index cc223a7fa4b940..e4936915887802 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -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. diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index b9e541c150dc43..04acc415b3105e 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -483,8 +483,7 @@ 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. How do I read (or write) binary data? diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst index d19580cd7ee5ce..36c15e9d1d92d1 100644 --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -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. + with the physical backing store on macOS. This example shows a simple way of using :class:`~mmap.mmap`:: diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst index ad417a17879c1f..90be191aa2f8d7 100644 --- a/Doc/library/posix.rst +++ b/Doc/library/posix.rst @@ -37,7 +37,7 @@ Large File Support .. sectionauthor:: Steve Clift -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 From 534de62862f1f3fabf0a22de13dd692d82070098 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Fri, 13 May 2022 18:23:16 -0500 Subject: [PATCH 2/4] Doc: Update several old explainations/examples for modern 64-bit arches --- Doc/howto/sockets.rst | 17 ++++++++++------- Doc/library/platform.rst | 2 +- Doc/library/struct.rst | 7 ++++--- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/Doc/howto/sockets.rst b/Doc/howto/sockets.rst index e58f78a7cb0245..36ecfd0469f610 100644 --- a/Doc/howto/sockets.rst +++ b/Doc/howto/sockets.rst @@ -252,20 +252,23 @@ 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 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 of 32 bit machines, the ascii representation of binary data is +In these days of 64-bit machines, the ASCII 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, all those integers have the value 0, or maybe 1. +The string ``"0"`` would be two bytes, while a full 64-bit word would be 8. +Of course, this doesn't fit well with fixed-length messages. +Decisions, decisions. Disconnecting diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index 346063d66afab9..dc2d871b47d5ef 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -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 value cannot be determined. diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index eccba20fb8fe7e..978eeabe37b1a3 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -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. From 2a67a2a172c0596bb3d4498a96b791b9f5065e23 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 16 May 2022 02:29:23 -0500 Subject: [PATCH 3/4] Doc: Add note to FAQ about copying file ADS/forks & metadata --- Doc/faq/library.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index 04acc415b3105e..85b04c963f5906 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -484,6 +484,13 @@ How do I copy a file? --------------------- The :mod:`shutil` module contains a :func:`~shutil.copyfile` function. +Note that on Windows NTFS volumes, it does not copy +`alternate data streams +`_ +nor `resource forks `__ +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? From 7fc91e7d84c5fa80bb1a3fea8a225c5e82934de6 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 16 May 2022 03:46:37 -0500 Subject: [PATCH 4/4] Doc: Further clarity integer/byte order details in socket howto --- Doc/howto/sockets.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/howto/sockets.rst b/Doc/howto/sockets.rst index 36ecfd0469f610..0bbf97da39768d 100644 --- a/Doc/howto/sockets.rst +++ b/Doc/howto/sockets.rst @@ -253,10 +253,12 @@ 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, -network byte order is big-endian, with the most significant byte first, +`network byte order `_ +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 @@ -265,8 +267,8 @@ appropriately. In these days of 64-bit machines, the ASCII representation of binary data is frequently smaller than the binary representation. That's because a surprising -amount of the time, all those integers have the value 0, or maybe 1. -The string ``"0"`` would be two bytes, while a full 64-bit word would be 8. +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.