bpo-27497: Add return value to csv.DictWriter.writeheader (GH-12306)

csv.DictWriter.writeheader() now returns the return value of the
underlying csv.Writer.writerow() method.

Patch contributed by Ashish Nitin Patil.

Doc/library/csv.rst

@@ -443,7 +443,8 @@ read CSV files (assuming they support complex numbers at all).
 .. method:: csvwriter.writerow(row)
 
    Write the *row* parameter to the writer's file object, formatted according to
-   the current dialect.
+   the current dialect. Return the return value of the call to the *write* method
+   of the underlying file object.
 
    .. versionchanged:: 3.5
       Added support of arbitrary iterables.
@@ -467,9 +468,14 @@ DictWriter objects have the following public method:
 
 .. method:: DictWriter.writeheader()
 
-   Write a row with the field names (as specified in the constructor).
+   Write a row with the field names (as specified in the constructor) to
+   the writer's file object, formatted according to the current dialect. Return
+   the return value of the :meth:`csvwriter.writerow` call used internally.
 
    .. versionadded:: 3.2
+   .. versionchanged:: 3.8
+      :meth:`writeheader` now also returns the value returned by
+      the :meth:`csvwriter.writerow` method it uses internally.
 
 
 .. _csv-examples:

Lib/csv.py

@@ -140,7 +140,7 @@ def __init__(self, f, fieldnames, restval="", extrasaction="raise",
 
     def writeheader(self):
         header = dict(zip(self.fieldnames, self.fieldnames))
-        self.writerow(header)
+        return self.writerow(header)
 
     def _dict_to_list(self, rowdict):
         if self.extrasaction == "raise":

Lib/test/test_csv.py

@@ -608,6 +608,12 @@ def test_read_escape_fieldsep(self):
 class TestDictFields(unittest.TestCase):
     ### "long" means the row is longer than the number of fieldnames
     ### "short" means there are fewer elements in the row than fieldnames
+    def test_writeheader_return_value(self):
+        with TemporaryFile("w+", newline='') as fileobj:
+            writer = csv.DictWriter(fileobj, fieldnames = ["f1", "f2", "f3"])
+            writeheader_return_value = writer.writeheader()
+            self.assertEqual(writeheader_return_value, 10)
+
     def test_write_simple_dict(self):
         with TemporaryFile("w+", newline='') as fileobj:
             writer = csv.DictWriter(fileobj, fieldnames = ["f1", "f2", "f3"])

Misc/NEWS.d/next/Library/2019-03-13-10-57-41.bpo-27497.JDmIe_.rst

@@ -0,0 +1,3 @@
+:meth:`csv.DictWriter.writeheader` now returns the return value of the
+underlying :meth:`csv.Writer.writerow` method. Patch contributed by Ashish
+Nitin Patil.