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. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy