[3.14] gh-150285: Fix too long docstrings in some Python modules (GH-150366) (GH-150375) (GH-150519)

(cherry picked from commit 01c6d3d)
(cherry picked from commit 03244b9)

Co-authored-by: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>

Author: serhiy-storchaka

Lib/_collections_abc.py

@@ -461,8 +461,8 @@ def __subclasshook__(cls, C):
 class _CallableGenericAlias(GenericAlias):
     """ Represent `Callable[argtypes, resulttype]`.
 
-    This sets ``__args__`` to a tuple containing the flattened ``argtypes``
-    followed by ``resulttype``.
+    This sets ``__args__`` to a tuple containing the flattened
+    ``argtypes`` followed by ``resulttype``.
 
     Example: ``Callable[[int, str], float]`` sets ``__args__`` to
     ``(int, str, float)``.
@@ -927,8 +927,9 @@ def __delitem__(self, key):
     __marker = object()
 
     def pop(self, key, default=__marker):
-        '''D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
-          If key is not found, d is returned if given, otherwise KeyError is raised.
+        '''D.pop(k[,d]) -> v, remove specified key and return the corresponding
+        value.  If key is not found, d is returned if given, otherwise
+        KeyError is raised.
         '''
         try:
             value = self[key]
@@ -962,9 +963,12 @@ def clear(self):
 
     def update(self, other=(), /, **kwds):
         ''' D.update([E, ]**F) -> None.  Update D from mapping/iterable E and F.
-            If E present and has a .keys() method, does:     for k in E.keys(): D[k] = E[k]
-            If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
-            In either case, this is followed by: for k, v in F.items(): D[k] = v
+            If E present and has a .keys() method, does:
+                for k in E.keys(): D[k] = E[k]
+            If E present and lacks .keys() method, does:
+                for (k, v) in E: D[k] = v
+            In either case, this is followed by:
+                for k, v in F.items(): D[k] = v
         '''
         if isinstance(other, Mapping):
             for key in other:
@@ -1029,8 +1033,8 @@ def __reversed__(self):
             yield self[i]
 
     def index(self, value, start=0, stop=None):
-        '''S.index(value, [start, [stop]]) -> integer -- return first index of value.
-           Raises ValueError if the value is not present.
+        '''S.index(value, [start, [stop]]) -> integer -- return first index of
+           value.  Raises ValueError if the value is not present.
 
            Supporting start and stop arguments is optional, but
            recommended.
@@ -1138,15 +1142,16 @@ def reverse(self):
             self[i], self[n-i-1] = self[n-i-1], self[i]
 
     def extend(self, values):
-        'S.extend(iterable) -- extend sequence by appending elements from the iterable'
+        """S.extend(iterable) -- extend sequence by appending elements from the
+        iterable"""
         if values is self:
             values = list(values)
         for v in values:
             self.append(v)
 
     def pop(self, index=-1):
-        '''S.pop([index]) -> item -- remove and return item at index (default last).
-           Raise IndexError if list is empty or index is out of range.
+        '''S.pop([index]) -> item -- remove and return item at index (default
+        last).  Raise IndexError if list is empty or index is out of range.
         '''
         v = self[index]
         del self[index]

Lib/enum.py

@@ -678,26 +678,27 @@ def __call__(cls, value, names=_not_given, *values, module=None, qualname=None,
         """
         Either returns an existing member, or creates a new enum class.
 
-        This method is used both when an enum class is given a value to match
-        to an enumeration member (i.e. Color(3)) and for the functional API
-        (i.e. Color = Enum('Color', names='RED GREEN BLUE')).
+        This method is used both when an enum class is given a value to
+        match to an enumeration member (i.e. Color(3)) and for the
+        functional API (i.e. Color = Enum('Color', names='RED GREEN BLUE')).
 
         The value lookup branch is chosen if the enum is final.
 
         When used for the functional API:
 
         `value` will be the name of the new class.
 
-        `names` should be either a string of white-space/comma delimited names
-        (values will start at `start`), or an iterator/mapping of name, value pairs.
+        `names` should be either a string of white-space/comma delimited
+        names (values will start at `start`), or an iterator/mapping of
+        name, value pairs.
 
         `module` should be set to the module this class is being created in;
-        if it is not set, an attempt to find that module will be made, but if
-        it fails the class will not be picklable.
+        if it is not set, an attempt to find that module will be made, but
+        if it fails the class will not be picklable.
 
-        `qualname` should be set to the actual location this class can be found
-        at in its module; by default it is set to the global scope.  If this is
-        not correct, unpickling will fail in some circumstances.
+        `qualname` should be set to the actual location this class can be
+        found at in its module; by default it is set to the global scope.
+        If this is not correct, unpickling will fail in some circumstances.
 
         `type`, if set, will be mixed in as the first base class.
         """
@@ -791,8 +792,8 @@ def __members__(cls):
         """
         Returns a mapping of member name->value.
 
-        This mapping lists all enum members, including aliases. Note that this
-        is a read-only view of the internal mapping.
+        This mapping lists all enum members, including aliases.  Note that
+        this is a read-only view of the internal mapping.
         """
         return MappingProxyType(cls._member_map_)
 

Lib/functools.py

@@ -556,16 +556,16 @@ def lru_cache(maxsize=128, typed=False):
     If *maxsize* is set to None, the LRU features are disabled and the cache
     can grow without bound.
 
-    If *typed* is True, arguments of different types will be cached separately.
-    For example, f(decimal.Decimal("3.0")) and f(3.0) will be treated as
-    distinct calls with distinct results. Some types such as str and int may
-    be cached separately even when typed is false.
+    If *typed* is True, arguments of different types will be cached
+    separately.  For example, f(decimal.Decimal("3.0")) and f(3.0) will be
+    treated as distinct calls with distinct results.  Some types such as
+    str and int may be cached separately even when typed is false.
 
     Arguments to the cached function must be hashable.
 
     View the cache statistics named tuple (hits, misses, maxsize, currsize)
-    with f.cache_info().  Clear the cache and statistics with f.cache_clear().
-    Access the underlying function with f.__wrapped__.
+    with f.cache_info().  Clear the cache and statistics with
+    f.cache_clear().  Access the underlying function with f.__wrapped__.
 
     See:  https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)
 

Lib/glob.py

@@ -25,17 +25,17 @@ def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
     The order of the returned list is undefined. Sort it if you need a
     particular order.
 
-    If `root_dir` is not None, it should be a path-like object specifying the
-    root directory for searching. It has the same effect as changing the
-    current directory before calling it (without actually
-    changing it). If pathname is relative, the result will contain
-    paths relative to `root_dir`.
+    If `root_dir` is not None, it should be a path-like object specifying
+    the root directory for searching.  It has the same effect as changing
+    the current directory before calling it (without actually changing it).
+    If pathname is relative, the result will contain paths relative to
+    `root_dir`.
 
     If `dir_fd` is not None, it should be a file descriptor referring to a
     directory, and paths will then be relative to that directory.
 
-    If `include_hidden` is true, the patterns '*', '?', '**'  will match hidden
-    directories.
+    If `include_hidden` is true, the patterns '*', '?', '**'  will match
+    hidden directories.
 
     If `recursive` is true, the pattern '**' will match any files and
     zero or more directories and subdirectories.
@@ -56,16 +56,16 @@ def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
     particular order.
 
     If `root_dir` is not None, it should be a path-like object specifying
-    the root directory for searching. It has the same effect as changing
-    the current directory before calling it (without actually
-    changing it). If pathname is relative, the result will contain
-    paths relative to `root_dir`.
+    the root directory for searching.  It has the same effect as changing
+    the current directory before calling it (without actually changing it).
+    If pathname is relative, the result will contain paths relative to
+    `root_dir`.
 
     If `dir_fd` is not None, it should be a file descriptor referring to a
     directory, and paths will then be relative to that directory.
 
-    If `include_hidden` is true, the patterns '*', '?', '**'  will match hidden
-    directories.
+    If `include_hidden` is true, the patterns '*', '?', '**'  will match
+    hidden directories.
 
     If `recursive` is true, the pattern '**' will match any files and
     zero or more directories and subdirectories.
@@ -294,15 +294,15 @@ def escape(pathname):
 def translate(pat, *, recursive=False, include_hidden=False, seps=None):
     """Translate a pathname with shell wildcards to a regular expression.
 
-    If `recursive` is true, the pattern segment '**' will match any number of
-    path segments.
+    If `recursive` is true, the pattern segment '**' will match any number
+    of path segments.
 
     If `include_hidden` is true, wildcards can match path segments beginning
     with a dot ('.').
 
     If a sequence of separator characters is given to `seps`, they will be
-    used to split the pattern into segments and match path separators. If not
-    given, os.path.sep and os.path.altsep (where available) are used.
+    used to split the pattern into segments and match path separators.  If
+    not given, os.path.sep and os.path.altsep (where available) are used.
     """
     if not seps:
         if os.path.altsep:

Lib/gzip.py

@@ -34,16 +34,16 @@ def open(filename, mode="rb", compresslevel=_COMPRESS_LEVEL_BEST,
          encoding=None, errors=None, newline=None):
     """Open a gzip-compressed file in binary or text mode.
 
-    The filename argument can be an actual filename (a str or bytes object), or
-    an existing file object to read from or write to.
+    The filename argument can be an actual filename (a str or bytes object),
+    or an existing file object to read from or write to.
 
-    The mode argument can be "r", "rb", "w", "wb", "x", "xb", "a" or "ab" for
-    binary mode, or "rt", "wt", "xt" or "at" for text mode. The default mode is
-    "rb", and the default compresslevel is 9.
+    The mode argument can be "r", "rb", "w", "wb", "x", "xb", "a" or "ab"
+    for binary mode, or "rt", "wt", "xt" or "at" for text mode.  The default
+    mode is "rb", and the default compresslevel is 9.
 
-    For binary mode, this function is equivalent to the GzipFile constructor:
-    GzipFile(filename, mode, compresslevel). In this case, the encoding, errors
-    and newline arguments must not be provided.
+    For binary mode, this function is equivalent to the GzipFile
+    constructor: GzipFile(filename, mode, compresslevel).  In this case,
+    the encoding, errors and newline arguments must not be provided.
 
     For text mode, a GzipFile object is created, and wrapped in an
     io.TextIOWrapper instance with the specified encoding, error handling
@@ -148,8 +148,8 @@ class GzipFile(_streams.BaseStream):
     """The GzipFile class simulates most of the methods of a file object with
     the exception of the truncate() method.
 
-    This class only supports opening files in binary mode. If you need to open a
-    compressed file in text mode, use the gzip.open() function.
+    This class only supports opening files in binary mode.  If you need to
+    open a compressed file in text mode, use the gzip.open() function.
 
     """
 
@@ -165,31 +165,33 @@ def __init__(self, filename=None, mode=None,
         non-trivial value.
 
         The new class instance is based on fileobj, which can be a regular
-        file, an io.BytesIO object, or any other object which simulates a file.
-        It defaults to None, in which case filename is opened to provide
-        a file object.
+        file, an io.BytesIO object, or any other object which simulates
+        a file.  It defaults to None, in which case filename is opened to
+        provide a file object.
 
         When fileobj is not None, the filename argument is only used to be
         included in the gzip file header, which may include the original
         filename of the uncompressed file.  It defaults to the filename of
         fileobj, if discernible; otherwise, it defaults to the empty string,
-        and in this case the original filename is not included in the header.
-
-        The mode argument can be any of 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x', or
-        'xb' depending on whether the file will be read or written.  The default
-        is the mode of fileobj if discernible; otherwise, the default is 'rb'.
-        A mode of 'r' is equivalent to one of 'rb', and similarly for 'w' and
-        'wb', 'a' and 'ab', and 'x' and 'xb'.
-
-        The compresslevel argument is an integer from 0 to 9 controlling the
-        level of compression; 1 is fastest and produces the least compression,
-        and 9 is slowest and produces the most compression. 0 is no compression
-        at all. The default is 9.
-
-        The optional mtime argument is the timestamp requested by gzip. The time
-        is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970.
-        If mtime is omitted or None, the current time is used. Use mtime = 0
-        to generate a compressed stream that does not depend on creation time.
+        and in this case the original filename is not included in the
+        header.
+
+        The mode argument can be any of 'r', 'rb', 'a', 'ab', 'w', 'wb',
+        'x', or 'xb' depending on whether the file will be read or written.
+        The default is the mode of fileobj if discernible; otherwise, the
+        default is 'rb'.  A mode of 'r' is equivalent to one of 'rb', and
+        similarly for 'w' and 'wb', 'a' and 'ab', and 'x' and 'xb'.
+
+        The compresslevel argument is an integer from 0 to 9 controlling
+        the level of compression; 1 is fastest and produces the least
+        compression, and 9 is slowest and produces the most compression.
+        0 is no compression at all. The default is 9.
+
+        The optional mtime argument is the timestamp requested by gzip.
+        The time is in Unix format, i.e., seconds since 00:00:00 UTC,
+        January 1, 1970.  If mtime is omitted or None, the current time
+        is used.  Use mtime = 0 to generate a compressed stream that does
+        not depend on creation time.
 
         """
 

Lib/ntpath.py

@@ -152,12 +152,14 @@ def splitdrive(p):
     It is always true that:
         result[0] + result[1] == p
 
-    If the path contained a drive letter, drive_or_unc will contain everything
-    up to and including the colon.  e.g. splitdrive("c:/dir") returns ("c:", "/dir")
+    If the path contained a drive letter, drive_or_unc will contain
+    everything up to and including the colon.  e.g. splitdrive("c:/dir")
+    returns ("c:", "/dir")
 
-    If the path contained a UNC path, the drive_or_unc will contain the host name
-    and share up to but not including the fourth directory separator character.
-    e.g. splitdrive("//host/computer/dir") returns ("//host/computer", "/dir")
+    If the path contained a UNC path, the drive_or_unc will contain the
+    host name and share up to but not including the fourth directory
+    separator character.  e.g. splitdrive("//host/computer/dir") returns
+    ("//host/computer", "/dir")
 
     Paths cannot contain both a drive letter and a UNC path.
 
@@ -222,8 +224,8 @@ def splitroot(p):
 def split(p):
     """Split a pathname.
 
-    Return tuple (head, tail) where tail is everything after the final slash.
-    Either part may be empty."""
+    Return tuple (head, tail) where tail is everything after the final
+    slash.  Either part may be empty."""
     p = os.fspath(p)
     seps = _get_bothseps(p)
     d, r, p = splitroot(p)

Lib/tarfile.py

@@ -899,19 +899,23 @@ class TarInfo(object):
         size = 'Size in bytes.',
         mtime = 'Time of last modification.',
         chksum = 'Header checksum.',
-        type = ('File type. type is usually one of these constants: '
-                'REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, '
-                'CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE.'),
+        type = ('File type.  type is usually one of these constants: '
+                'REGTYPE,\n'
+                'AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, '
+                'CONTTYPE, CHRTYPE,\n'
+                'BLKTYPE, GNUTYPE_SPARSE.'),
         linkname = ('Name of the target file name, which is only present '
-                    'in TarInfo objects of type LNKTYPE and SYMTYPE.'),
+                    'in TarInfo\n'
+                    'objects of type LNKTYPE and SYMTYPE.'),
         uname = 'User name.',
         gname = 'Group name.',
         devmajor = 'Device major number.',
         devminor = 'Device minor number.',
         offset = 'The tar header starts here.',
         offset_data = "The file's data starts here.",
         pax_headers = ('A dictionary containing key-value pairs of an '
-                       'associated pax extended header.'),
+                       'associated pax\n'
+                       'extended header.'),
         sparse = 'Sparse member information.',
         _tarfile = None,
         _sparse_structs = None,
@@ -2273,10 +2277,11 @@ def gettarinfo(self, name=None, arcname=None, fileobj=None):
         return tarinfo
 
     def list(self, verbose=True, *, members=None):
-        """Print a table of contents to sys.stdout. If 'verbose' is False, only
-           the names of the members are printed. If it is True, an 'ls -l'-like
-           output is produced. 'members' is optional and must be a subset of the
-           list returned by getmembers().
+        """Print a table of contents to sys.stdout.
+
+        If 'verbose' is False, only the names of the members are printed.
+        If it is True, an 'ls -l'-like output is produced.  'members' is
+        optional and must be a subset of the list returned by getmembers().
         """
         # Convert tarinfo type to stat type.
         type2mode = {REGTYPE: stat.S_IFREG, SYMTYPE: stat.S_IFLNK,
@@ -2367,10 +2372,12 @@ def add(self, name, arcname=None, recursive=True, *, filter=None):
             self.addfile(tarinfo)
 
     def addfile(self, tarinfo, fileobj=None):
-        """Add the TarInfo object 'tarinfo' to the archive. If 'tarinfo' represents
-           a non zero-size regular file, the 'fileobj' argument should be a binary file,
-           and tarinfo.size bytes are read from it and added to the archive.
-           You can create TarInfo objects directly, or by using gettarinfo().
+        """Add the TarInfo object 'tarinfo' to the archive.
+
+        If 'tarinfo' represents a non zero-size regular file, the 'fileobj'
+        argument should be a binary file, and tarinfo.size bytes are read
+        from it and added to the archive. You can create TarInfo objects
+        directly, or by using gettarinfo().
         """
         self._check("awx")