From d237652ef9c9fa0e9142ca5cbe56418518286f5f Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 24 Aug 2025 11:13:31 +0300 Subject: [PATCH] gh-137986: Fix and improve the csv functions docstrings (GH-137987) The csv.register_dialect() docstring no longer imply that it returns a dialect. All functions have now signatures. (cherry picked from commit aa1dbd4dde32951de2e7438b56d6761001604ee2) Co-authored-by: Serhiy Storchaka Co-authored-by: maurycy <5383+maurycy@users.noreply.github.com> --- Doc/library/csv.rst | 9 +++--- Modules/_csv.c | 67 +++++++++++++++++++---------------------- Modules/clinic/_csv.c.h | 16 +++------- 3 files changed, 40 insertions(+), 52 deletions(-) diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index d39c4ca4a5838b..c11c9b8b2bfbe7 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -113,7 +113,7 @@ The :mod:`csv` module defines the following functions: spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam']) -.. function:: register_dialect(name[, dialect[, **fmtparams]]) +.. function:: register_dialect(name, /, dialect='excel', **fmtparams) Associate *dialect* with *name*. *name* must be a string. The dialect can be specified either by passing a sub-class of :class:`Dialect`, or @@ -139,7 +139,8 @@ The :mod:`csv` module defines the following functions: Return the names of all registered dialects. -.. function:: field_size_limit([new_limit]) +.. function:: field_size_limit() + field_size_limit(new_limit) Returns the current maximum field size allowed by the parser. If *new_limit* is given, this becomes the new limit. @@ -526,7 +527,7 @@ out surrounded by parens. This may cause some problems for other programs which read CSV files (assuming they support complex numbers at all). -.. method:: csvwriter.writerow(row) +.. method:: csvwriter.writerow(row, /) Write the *row* parameter to the writer's file object, formatted according to the current :class:`Dialect`. Return the return value of the call to the @@ -535,7 +536,7 @@ read CSV files (assuming they support complex numbers at all). .. versionchanged:: 3.5 Added support of arbitrary iterables. -.. method:: csvwriter.writerows(rows) +.. method:: csvwriter.writerows(rows, /) Write all elements in *rows* (an iterable of *row* objects as described above) to the writer's file object, formatted according to the current diff --git a/Modules/_csv.c b/Modules/_csv.c index 2e04136e0ac657..87be7a8f1fb136 100644 --- a/Modules/_csv.c +++ b/Modules/_csv.c @@ -1304,10 +1304,11 @@ join_append_lineterminator(WriterObj *self) } PyDoc_STRVAR(csv_writerow_doc, -"writerow(iterable)\n" +"writerow($self, row, /)\n" +"--\n\n" +"Construct and write a CSV record from an iterable of fields.\n" "\n" -"Construct and write a CSV record from an iterable of fields. Non-string\n" -"elements will be converted to string."); +"Non-string elements will be converted to string."); static PyObject * csv_writerow(PyObject *op, PyObject *seq) @@ -1414,10 +1415,11 @@ csv_writerow(PyObject *op, PyObject *seq) } PyDoc_STRVAR(csv_writerows_doc, -"writerows(iterable of iterables)\n" +"writerows($self, rows, /)\n" +"--\n\n" +"Construct and write a series of iterables to a csv file.\n" "\n" -"Construct and write a series of iterables to a csv file. Non-string\n" -"elements will be converted to string."); +"Non-string elements will be converted to string."); static PyObject * csv_writerows(PyObject *self, PyObject *seqseq) @@ -1574,13 +1576,11 @@ csv_writer(PyObject *module, PyObject *args, PyObject *keyword_args) _csv.list_dialects Return a list of all known dialect names. - - names = csv.list_dialects() [clinic start generated code]*/ static PyObject * _csv_list_dialects_impl(PyObject *module) -/*[clinic end generated code: output=a5b92b215b006a6d input=8953943eb17d98ab]*/ +/*[clinic end generated code: output=a5b92b215b006a6d input=ec58040aafd6a20a]*/ { return PyDict_Keys(get_csv_state(module)->dialects); } @@ -1617,13 +1617,11 @@ _csv.unregister_dialect name: object Delete the name/dialect mapping associated with a string name. - - csv.unregister_dialect(name) [clinic start generated code]*/ static PyObject * _csv_unregister_dialect_impl(PyObject *module, PyObject *name) -/*[clinic end generated code: output=0813ebca6c058df4 input=6b5c1557bf60c7e7]*/ +/*[clinic end generated code: output=0813ebca6c058df4 input=e1cf81bfe3ba0f62]*/ { _csvstate *module_state = get_csv_state(module); int rc = PyDict_Pop(module_state->dialects, name, NULL); @@ -1643,13 +1641,11 @@ _csv.get_dialect name: object Return the dialect instance associated with name. - - dialect = csv.get_dialect(name) [clinic start generated code]*/ static PyObject * _csv_get_dialect_impl(PyObject *module, PyObject *name) -/*[clinic end generated code: output=aa988cd573bebebb input=edf9ddab32e448fb]*/ +/*[clinic end generated code: output=aa988cd573bebebb input=74865c659dcb441f]*/ { return get_dialect_from_registry(name, get_csv_state(module)); } @@ -1661,15 +1657,13 @@ _csv.field_size_limit 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 [clinic start generated code]*/ static PyObject * _csv_field_size_limit_impl(PyObject *module, PyObject *new_limit) -/*[clinic end generated code: output=f2799ecd908e250b input=cec70e9226406435]*/ +/*[clinic end generated code: output=f2799ecd908e250b input=77db7485ee3ae90a]*/ { _csvstate *module_state = get_csv_state(module); Py_ssize_t old_limit = FT_ATOMIC_LOAD_SSIZE_RELAXED(module_state->field_limit); @@ -1705,14 +1699,13 @@ PyType_Spec error_spec = { PyDoc_STRVAR(csv_module_doc, "CSV parsing and writing.\n"); PyDoc_STRVAR(csv_reader_doc, -" csv_reader = reader(iterable [, dialect='excel']\n" -" [optional keyword args])\n" -" for row in csv_reader:\n" -" process(row)\n" +"reader($module, iterable, /, dialect='excel', **fmtparams)\n" +"--\n\n" +"Return a reader object that will process lines from the given iterable.\n" "\n" "The \"iterable\" argument can be any object that returns a line\n" "of input for each iteration, such as a file object or a list. The\n" -"optional \"dialect\" parameter is discussed below. The function\n" +"optional \"dialect\" argument defines a CSV dialect. The function\n" "also accepts optional keyword arguments which override settings\n" "provided by the dialect.\n" "\n" @@ -1720,22 +1713,24 @@ PyDoc_STRVAR(csv_reader_doc, "of the CSV file (which can span multiple input lines).\n"); PyDoc_STRVAR(csv_writer_doc, -" csv_writer = csv.writer(fileobj [, dialect='excel']\n" -" [optional keyword args])\n" -" for row in sequence:\n" -" csv_writer.writerow(row)\n" +"writer($module, fileobj, /, dialect='excel', **fmtparams)\n" +"--\n\n" +"Return a writer object that will write user data on the given file object.\n" "\n" -" [or]\n" -"\n" -" csv_writer = csv.writer(fileobj [, dialect='excel']\n" -" [optional keyword args])\n" -" csv_writer.writerows(rows)\n" -"\n" -"The \"fileobj\" argument can be any object that supports the file API.\n"); +"The \"fileobj\" argument can be any object that supports the file API.\n" +"The optional \"dialect\" argument defines a CSV dialect. The function\n" +"also accepts optional keyword arguments which override settings\n" +"provided by the dialect.\n"); PyDoc_STRVAR(csv_register_dialect_doc, -"Create a mapping from a string name to a dialect class.\n" -" dialect = csv.register_dialect(name[, dialect[, **fmtparams]])"); +"register_dialect($module, name, /, dialect='excel', **fmtparams)\n" +"--\n\n" +"Create a mapping from a string name to a CVS dialect.\n" +"\n" +"The optional \"dialect\" argument specifies the base dialect instance\n" +"or the name of the registered dialect. The function also accepts\n" +"optional keyword arguments which override settings provided by the\n" +"dialect.\n"); static struct PyMethodDef csv_methods[] = { { "reader", _PyCFunction_CAST(csv_reader), diff --git a/Modules/clinic/_csv.c.h b/Modules/clinic/_csv.c.h index 416aeafccf917b..b8dd8ac35fac59 100644 --- a/Modules/clinic/_csv.c.h +++ b/Modules/clinic/_csv.c.h @@ -12,9 +12,7 @@ PyDoc_STRVAR(_csv_list_dialects__doc__, "list_dialects($module, /)\n" "--\n" "\n" -"Return a list of all known dialect names.\n" -"\n" -" names = csv.list_dialects()"); +"Return a list of all known dialect names."); #define _CSV_LIST_DIALECTS_METHODDEF \ {"list_dialects", (PyCFunction)_csv_list_dialects, METH_NOARGS, _csv_list_dialects__doc__}, @@ -32,9 +30,7 @@ PyDoc_STRVAR(_csv_unregister_dialect__doc__, "unregister_dialect($module, /, name)\n" "--\n" "\n" -"Delete the name/dialect mapping associated with a string name.\n" -"\n" -" csv.unregister_dialect(name)"); +"Delete the name/dialect mapping associated with a string name."); #define _CSV_UNREGISTER_DIALECT_METHODDEF \ {"unregister_dialect", _PyCFunction_CAST(_csv_unregister_dialect), METH_FASTCALL|METH_KEYWORDS, _csv_unregister_dialect__doc__}, @@ -92,9 +88,7 @@ PyDoc_STRVAR(_csv_get_dialect__doc__, "get_dialect($module, /, name)\n" "--\n" "\n" -"Return the dialect instance associated with name.\n" -"\n" -" dialect = csv.get_dialect(name)"); +"Return the dialect instance associated with name."); #define _CSV_GET_DIALECT_METHODDEF \ {"get_dialect", _PyCFunction_CAST(_csv_get_dialect), METH_FASTCALL|METH_KEYWORDS, _csv_get_dialect__doc__}, @@ -154,8 +148,6 @@ PyDoc_STRVAR(_csv_field_size_limit__doc__, "\n" "Sets an upper limit on parsed fields.\n" "\n" -" csv.field_size_limit([limit])\n" -"\n" "Returns old limit. If limit is not given, no new limit is set and\n" "the old limit is returned"); @@ -215,4 +207,4 @@ _csv_field_size_limit(PyObject *module, PyObject *const *args, Py_ssize_t nargs, exit: return return_value; } -/*[clinic end generated code: output=1fb09d5e7667ad0d input=a9049054013a1b77]*/ +/*[clinic end generated code: output=ed77cb69fad9f3b4 input=a9049054013a1b77]*/