8000 gh-114123: migrate docstring from _csv to csv by smontanaro · Pull Request #114124 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-114123: migrate docstring from _csv to csv #114124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jan 18, 2024
Merged

gh-114123: migrate docstring from _csv to csv #114124

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ac1e4ca
migrate docstring from _csv to csv
smontanaro Jan 16, 2024
b2a5e66
two suggestions by AA-Turner
smontanaro Jan 16, 2024
64301bd
move __version__ from _csv to csv, remove from csv.__all__
smontanaro Jan 17, 2024
998a944
+ NEWS item
smontanaro Jan 17, 2024
bef4811
markup
smontanaro Jan 17, 2024
3e540c6
restore test__all__
smontanaro Jan 18, 2024
4d4d2b4
Update the docstring title
AA-Turner Jan 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 68 additions & 6 deletions Lib/csv.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,90 @@

"""
r"""
csv.py - read/write/investigate CSV files

This module provides classes that assist in the reading and writing
of Comma Separated Value (CSV) files, and implements the interface
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
of Comma Separated Value (CSV) files, and implements the interface
of comma-separated values files, and implements the interface

described by PEP 305. Although many CSV files are simple to parse,
the format is not formally defined by a stable specification and
is subtle enough that parsing lines of a CSV file with something
like line.split(",") is bound to fail. The module supports three
basic APIs: reading, writing, and registration of dialects.


DIALECT REGISTRATION:

Readers and writers support a dialect argument, which is a convenient
handle on a group of settings. When the dialect argument is a string,
it identifies one of the dialects previously registered with the module.
If it is a class or instance, the attributes of the argument are used as
the settings for the reader or writer:

class excel:
delimiter = ','
quotechar = '"'
escapechar = None
doublequote = True
skipinitialspace = False
lineterminator = '\r\n'
quoting = QUOTE_MINIMAL

SETTINGS:

* quotechar - specifies a one-character string to use as the
quoting character. It defaults to '"'.
* delimiter - specifies a one-character string to use as the
field separator. It defaults to ','.
* skipinitialspace - specifies how to interpret spaces which
immediately follow a delimiter. It defaults to False, which
means that spaces immediately following a delimiter is part
of the following field.
* lineterminator - specifies the character sequence which should
terminate rows.
* quoting - controls when quotes should be generated by the writer.
It can take on any of the following module constants:

csv.QUOTE_MINIMAL means only when required, for example, when a
field contains either the quotechar or the delimiter
csv.QUOTE_ALL means that quotes are always placed around fields.
csv.QUOTE_NONNUMERIC means that quotes are always placed around
fields which do not parse as integers or floating point
numbers.
csv.QUOTE_STRINGS means that quotes are always placed around
fields which are strings. Note that the Python value None
is not a string.
csv.QUOTE_NOTNULL means that quotes are only placed around fields
that are not the Python value None.
csv.QUOTE_NONE means that quotes are never placed around fields.
* escapechar - specifies a one-character string used to escape
the delimiter when quoting is set to QUOTE_NONE.
* doublequote - controls the handling of quotes inside fields. When
True, two consecutive quotes are interpreted as one during read,
and when writing, each quote character embedded in the data is
written as two quotes
"""

import re
import types
from _csv import Error, __version__, writer, reader, register_dialect, \
from _csv import Error, writer, reader, register_dialect, \
unregister_dialect, get_dialect, list_dialects, \
field_size_limit, \
QUOTE_MINIMAL, QUOTE_ALL, QUOTE_NONNUMERIC, QUOTE_NONE, \
QUOTE_STRINGS, QUOTE_NOTNULL, \
__doc__
QUOTE_STRINGS, QUOTE_NOTNULL
from _csv import Dialect as _Dialect

from io import StringIO

__all__ = ["QUOTE_MINIMAL", "QUOTE_ALL", "QUOTE_NONNUMERIC", "QUOTE_NONE",
"QUOTE_STRINGS", "QUOTE_NOTNULL",
"Error", "Dialect", "__doc__", "excel", "excel_tab",
"Error", "Dialect", "excel", "excel_tab",
"field_size_limit", "reader", "writer",
"register_dialect", "get_dialect", "list_dialects", "Sniffer",
"unregister_dialect", "__version__", "DictReader", "DictWriter",
"unregister_dialect", "DictReader", "DictWriter",
"unix_dialect"]

__version__ = "1.0"


class Dialect:
"""Describe a CSV dialect.

Expand Down
4 changes: 0 additions & 4 deletions Lib/test/test_csv.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1415,10 +1415,6 @@ def test_ordered_dict_reader(self):


class MiscTestCase(unittest.TestCase):
def test__all__(self):
extra = {'__doc__', '__version__'}
support.check__all__(self, csv, ('csv', '_csv'), extra=extra)

Copy link
Member
@AA-Turner AA-Turner Jan 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think test__all__ should be kept?

Suggested change
def test__all__(self):
extra = {'__doc__', '__version__'}
support.check__all__(self, csv, ('csv', '_csv'), extra=extra)
def test__all__(self):
support.check__all__(self, csv, {'csv', '_csv'})

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AA-Turner Isn't test__all__ a standard thing? Why is this override needed if we no longer have an extra?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

test.support.check__all__() is, but test__all__ isn't defined in unittest.TestCase, so we do need to define the test to keep it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it is not overridden, i 10000 t is added. It compares the __all__ content with the calculated expected value (all public function, classes, etc defined in the specified modules). extra is an extra.

def test_subclassable(self):
# issue 44089
class Foo(csv.Error): ...
Expand Down
7 changes: 7 additions & 0 deletions Misc/NEWS.d/next/Documentation/2024-01-17-11-40-03.gh-issue-114123.LuueXf.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
Move the :mod:`csv` module docstring to the :mod:`!csv` module
instead of reexporting it from the internal :mod:`!_csv` module,
and remove ``__doc__`` from ``csv.__all__``.

Move :attr:`!csv.__version__` to the :mod:`!csv` module
instead of reexporting it from the internal :mod:`!_csv` module,
and remove ``__version__`` from ``csv.__all__``.
71 changes: 1 addition & 70 deletions Modules/_csv.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ module instead.

*/

#define MODULE_VERSION "1.0"

// clinic/_csv.c.h uses internal pycore_modsupport.h API
#ifndef Py_BUILD_CORE_BUILTIN
# define Py_BUILD_CORE_MODULE 1
Expand Down Expand Up @@ -1607,68 +1605,7 @@ PyType_Spec error_spec = {
* MODULE
*/

PyDoc_STRVAR(csv_module_doc,
"CSV parsing and writing.\n"
"\n"
"This module provides classes that assist in the reading and writing\n"
"of Comma Separated Value (CSV) files, and implements the interface\n"
"described by PEP 305. Although many CSV files are simple to parse,\n"
"the format is not formally defined by a stable specification and\n"
"is subtle enough that parsing lines of a CSV file with something\n"
"like line.split(\",\") is bound to fail. The module supports three\n"
"basic APIs: reading, writing, and registration of dialects.\n"
"\n"
"\n"
"DIALECT REGISTRATION:\n"
"\n"
"Readers and writers support a dialect argument, which is a convenient\n"
"handle on a group of settings. When the dialect argument is a string,\n"
"it identifies one of the dialects previously registered with the module.\n"
"If it is a class or instance, the attributes of the argument are used as\n"
"the settings for the reader or writer:\n"
"\n"
" class excel:\n"
" delimiter = ','\n"
" quotechar = '\"'\n"
" escapechar = None\n"
" doublequote = True\n"
" skipinitialspace = False\n"
" lineterminator = '\\r\\n'\n"
" quoting = QUOTE_MINIMAL\n"
"\n"
"SETTINGS:\n"
"\n"
" * quotechar - specifies a one-character string to use as the\n"
" quoting character. It defaults to '\"'.\n"
" * delimiter - specifies a one-character string to use as the\n"
" field separator. It defaults to ','.\n"
" * skipinitialspace - specifies how to interpret spaces which\n"
" immediately follow a delimiter. It defaults to False, which\n"
" means that spaces immediately following a delimiter is part\n"
" of the following field.\n"
" * lineterminator - specifies the character sequence which should\n"
" terminate rows.\n"
" * quoting - controls when quotes should be generated by the writer.\n"
" It can take on any of the following module constants:\n"
"\n"
" csv.QUOTE_MINIMAL means only when required, for example, when a\n"
" field contains either the quotechar or the delimiter\n"
" csv.QUOTE_ALL means that quotes are always placed around fields.\n"
" csv.QUOTE_NONNUMERIC means that quotes are always placed around\n"
" fields which do not parse as integers or floating point\n"
" numbers.\n"
" csv.QUOTE_STRINGS means that quotes are always placed around\n"
" fields which are strings. Note that the Python value None\n"
" is not a string.\n"
" csv.QUOTE_NOTNULL means that quotes are only placed around fields\n"
" that are not the Python value None.\n"
" csv.QUOTE_NONE means that quotes are never placed around fields.\n"
" * escapechar - specifies a one-character string used to escape\n"
" the delimiter when quoting is set to QUOTE_NONE.\n"
" * doublequote - controls the handling of quotes inside fields. When\n"
" True, two consecutive quotes are interpreted as one during read,\n"
" and when writing, each quote character embedded in the data is\n"
" written as two quotes\n");
PyDoc_STRVAR(csv_module_doc, "CSV parsing and writing.\n");

PyDoc_STRVAR(csv_reader_doc,
" csv_reader = reader(iterable [, dialect='excel']\n"
Expand Down Expand Up @@ -1741,12 +1678,6 @@ csv_exec(PyObject *module) {
return -1;
}

/* Add version to the module. */
if (PyModule_AddStringConstant(module, "__version__",
MODULE_VERSION) == -1) {
return -1;
}

/* Set the field limit */
module_state->field_limit = 128 * 1024;

Expand Down
0