greg/cpython
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

gh-137986: Fix and improve the csv functions docstrings (GH-137987)

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

Co-authored-by: maurycy <5383+maurycy@users.noreply.github.com>
This commit is contained in:
Serhiy Storchaka
2025-08-24 11:13:31 +03:00
committed by GitHub
parent 6fcac09401
commit aa1dbd4dde
3 changed files with 40 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
Doc/library/csv.rst
View File

@@ -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

67
Modules/_csv.c
View File

@@ -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),

16
Modules/clinic/_csv.c.h generated
View File

@@ -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 @@ skip_optional_pos:
exit:
return return_value;
}
/*[clinic end generated code: output=1fb09d5e7667ad0d input=a9049054013a1b77]*/
/*[clinic end generated code: output=ed77cb69fad9f3b4 input=a9049054013a1b77]*/