gh-137986: Fix and improve the csv functions docstrings

[serhiy-storchaka]

The csv.register_dialect() docstring no longer imply that it returns a dialect.
All functions have now signatures.

• Issue: Fix and improve the csv docstrings #137986

[serhiy-storchaka]

The diff of the pydoc output:

@@ -149,58 +149,45 @@
     field_size_limit(new_limit=<unrepresentable>)
         Sets an upper limit on parsed fields.
 
-            csv.field_size_limit([limit])
-
         Returns old limit. If limit is not given, no new limit is set and
         the old limit is returned
 
     get_dialect(name)
         Return the dialect instance associated with name.
 
-        dialect = csv.get_dialect(name)
-
     list_dialects()
         Return a list of all known dialect names.
 
-        names = csv.list_dialects()
-
-    reader(...)
-        csv_reader = reader(iterable [, dialect='excel']
-                                [optional keyword args])
-            for row in csv_reader:
-                process(row)
+    reader(iterable, /, dialect='excel', **fmtparams)
+        Return a reader object that will process lines from the given iterable.
 
         The "iterable" argument can be any object that returns a line
         of input for each iteration, such as a file object or a list.  The
-        optional "dialect" parameter is discussed below.  The function
+        optional "dialect" argument defines a CSV dialect.  The function
         also accepts optional keyword arguments which override settings
         provided by the dialect.
 
         The returned object is an iterator.  Each iteration returns a row
         of the CSV file (which can span multiple input lines).
 
-    register_dialect(...)
-        Create a mapping from a string name to a dialect class.
-        dialect = csv.register_dialect(name[, dialect[, **fmtparams]])
+    register_dialect(name, /, dialect='excel', **fmtparams)
+        Create a mapping from a string name to a CVS dialect.
+
+        The optional "dialect" argument specifies the base dialect instance
+        or the name of the registered dialect.  The function also accepts
+        optional keyword arguments which override settings provided by the
+        dialect.
 
     unregister_dialect(name)
         Delete the name/dialect mapping associated with a string name.
 
-        csv.unregister_dialect(name)
-
-    writer(...)
-        csv_writer = csv.writer(fileobj [, dialect='excel']
-                                    [optional keyword args])
-            for row in sequence:
-                csv_writer.writerow(row)
-
-            [or]
-
-            csv_writer = csv.writer(fileobj [, dialect='excel']
-                                    [optional keyword args])
-            csv_writer.writerows(rows)
+    writer(fileobj, /, dialect='excel', **fmtparams)
+        Return a writer object that will write user data on the given file object.
 
         The "fileobj" argument can be any object that supports the file API.
+        The optional "dialect" argument defines a CSV dialect.  The function
+        also accepts optional keyword arguments which override settings
+        provided by the dialect.
 

[picnixz]

Oh so the other change is part of this PR. Good.

[serhiy-storchaka]

Other changes for writerow() and writerows() methods:

@@ -128,17 +128,15 @@
      |
      |  Methods defined here:
      |
-     |  writerow(self, object, /)
-     |      writerow(iterable)
+     |  writerow(self, row, /)
+     |      Construct and write a CSV record from an iterable of fields.
      |
-     |      Construct and write a CSV record from an iterable of fields.  Non-string
-     |      elements will be converted to string.
+     |      Non-string elements will be converted to string.
      |
-     |  writerows(self, object, /)
-     |      writerows(iterable of iterables)
+     |  writerows(self, rows, /)
+     |      Construct and write a series of iterables to a csv file.
      |
-     |      Construct and write a series of iterables to a csv file.  Non-string
-     |      elements will be converted to string.
+     |      Non-string elements will be converted to string.
      |
      |  ----------------------------------------------------------------------
      |  Data descriptors defined here:

[miss-islington-app]

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[miss-islington-app]

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker aa1dbd4dde32951de2e7438b56d6761001604ee2 3.13

[bedevere-app]

GH-138107 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-138108 is a backport of this pull request to the 3.13 branch.