diff --git a/Lib/test/test_clinic.py b/Lib/test/test_clinic.py index cb4507dcac2336d..5817b7239cb8fc4 100644 --- a/Lib/test/test_clinic.py +++ b/Lib/test/test_clinic.py @@ -1066,6 +1066,18 @@ def checkDocstring(self, fn, expected): self.assertEqual(dedent(expected).strip(), fn.docstring.strip()) + def parse_warnings(self, block): + """Parse a block and return what Argument Clinic warned about.""" + with support.captured_stdout() as stdout: + self.parse(block) + return stdout.getvalue() + + def too_long_warning(self, full_name, max_width): + """The warning emitted for a too long docstring body line.""" + return (f"Warning in file {'clinic_tests'!r}:\n" + f"Docstring lines for {full_name!r} are too long!\n" + f"Lines should be no longer than {max_width} characters.\n\n") + def test_trivial(self): parser = DSLParser(_make_clinic()) block = Block(""" @@ -2499,6 +2511,126 @@ def test_docstring_explicit_params_placement(self): (Note the added newline) """) + def test_long_summary_line(self): + # The summary line must fit in 72 characters for a function. + block = f""" + module m + m.f + {'x' * 73} + """ + err = ("Summary line for 'm.f' is too long!\n" + "The summary line must be no longer than 72 characters.") + self.expect_failure(block, err) + + def test_long_summary_line_permitted(self): + block = f""" + @permit_long_summary + module m + m.f + {'x' * 73} + """ + self.assertEqual(self.parse_warnings(block), "") + + def test_long_parameter_docstring(self): + # gh-155228: a parameter description is part of the docstring body, + # even though it is only substituted for the {parameters} marker + # after the width check. Descriptions are indented by 4 spaces. + expected = self.too_long_warning('m.f', 72) + for length, warning in (68, ""), (69, expected): + with self.subTest(length=length): + block = f""" + module m + m.f + a: int + {'x' * length} + The summary line. + """ + self.assertEqual(self.parse_warnings(block), warning) + + def test_long_parameter_docstring_method(self): + # Methods get 4 characters less than functions. + expected = self.too_long_warning('m.C.f', 68) + for length, warning in (64, ""), (65, expected): + with self.subTest(length=length): + block = f""" + module m + class m.C "void *" "" + m.C.f + a: int + {'x' * length} + The summary line. + """ + self.assertEqual(self.parse_warnings(block), warning) + + def test_long_parameter_docstring_indented_marker(self): + # linear_format() indents the substituted parameters by the + # indentation of the {parameters} marker line, which counts + # towards the width as well. + expected = self.too_long_warning('m.f', 72) + for length, warning in (66, ""), (67, expected): + with self.subTest(length=length): + block = f""" + module m + m.f + a: int + {'x' * length} + The summary line. + + {{parameters}} + """ + self.assertEqual(self.parse_warnings(block), warning) + + def test_long_parameter_docstring_permitted(self): + block = f""" + @permit_long_docstring_body + module m + m.f + a: int + {'x' * 69} + The summary line. + """ + self.assertEqual(self.parse_warnings(block), "") + + def test_permit_long_docstring_body_not_needed(self): + block = f""" + @permit_long_docstring_body + module m + m.f + a: int + {'x' * 68} + The summary line. + """ + expected = ( + f"Warning in file {'clinic_tests'!r}:\n" + "Remove the @permit_long_docstring_body decorator from 'm.f'!\n\n\n" + ) + self.assertEqual(self.parse_warnings(block), expected) + + def test_long_parameter_docstring_cloned(self): + # gh-155228: a clone inherits the parameter descriptions of the + # function it clones, so it must be reported as well. + # The clone lives in its own block, as it does in the source tree. + blocks = ( + f""" + module m + m.f + a: int + {'x' * 69} + The summary line. + """, + """ + m.g = m.f + The other summary line. + """, + ) + parser = DSLParser(_make_clinic()) + with support.captured_stdout() as stdout: + for text in blocks: + parser.parse(Block(text)) + expected = "".join(self.too_long_warning(f'm.{name}', 72) + for name in ("f", "g")) + self.assertEqual(stdout.getvalue(), expected) + def test_indent_stack_no_tabs(self): block = """ module foo diff --git a/Misc/NEWS.d/next/Tools-Demos/2026-08-05-21-49-10.gh-issue-155228.YbOZZi.rst b/Misc/NEWS.d/next/Tools-Demos/2026-08-05-21-49-10.gh-issue-155228.YbOZZi.rst new file mode 100644 index 000000000000000..aa85c3e77faf63c --- /dev/null +++ b/Misc/NEWS.d/next/Tools-Demos/2026-08-05-21-49-10.gh-issue-155228.YbOZZi.rst @@ -0,0 +1,3 @@ +Argument Clinic now checks the length of parameter descriptions, which were +previously left out of the docstring line width check. Too long parameter +descriptions of 30 functions were rewrapped. diff --git a/Modules/_lzmamodule.c b/Modules/_lzmamodule.c index 4335a8bb162414d..4304cef99930eba 100644 --- a/Modules/_lzmamodule.c +++ b/Modules/_lzmamodule.c @@ -1186,20 +1186,20 @@ _lzma.LZMADecompressor.__new__ format: int(c_default="FORMAT_AUTO") = FORMAT_AUTO Specifies the container format of the input stream. If this is - FORMAT_AUTO (the default), the decompressor will automatically detect - whether the input is FORMAT_XZ or FORMAT_ALONE. Streams created with - FORMAT_RAW cannot be autodetected. + FORMAT_AUTO (the default), the decompressor will automatically + detect whether the input is FORMAT_XZ or FORMAT_ALONE. Streams + created with FORMAT_RAW cannot be autodetected. memlimit: object = None - Limit the amount of memory used by the decompressor. This will cause - decompression to fail if the input cannot be decompressed within the - given limit. + Limit the amount of memory used by the decompressor. This will + cause decompression to fail if the input cannot be decompressed + within the given limit. filters: object = None - A custom filter chain. This argument is required for FORMAT_RAW, and - not accepted with any other format. When provided, this should be a - sequence of dicts, each indicating the ID and options for a single - filter. + A custom filter chain. This argument is required for FORMAT_RAW, + and not accepted with any other format. When provided, this + should be a sequence of dicts, each indicating the ID and options + for a single filter. Create a decompressor object for decompressing data incrementally. @@ -1209,7 +1209,7 @@ For one-shot decompression, use the decompress() function instead. static PyObject * _lzma_LZMADecompressor_impl(PyTypeObject *type, int format, PyObject *memlimit, PyObject *filters) -/*[clinic end generated code: output=2d46d5e70f10bc7f input=ca40cd1cb1202b0d]*/ +/*[clinic end generated code: output=2d46d5e70f10bc7f input=a9b1c4db9f5acb69]*/ { Decompressor *self; const uint32_t decoder_flags = LZMA_TELL_ANY_CHECK | LZMA_TELL_NO_CHECK; diff --git a/Modules/_sqlite/clinic/connection.c.h b/Modules/_sqlite/clinic/connection.c.h index b645bf3464bcea1..a8d8f6a9cffc144 100644 --- a/Modules/_sqlite/clinic/connection.c.h +++ b/Modules/_sqlite/clinic/connection.c.h @@ -1634,7 +1634,8 @@ PyDoc_STRVAR(setconfig__doc__, "Set a boolean connection configuration option.\n" "\n" " op\n" -" The configuration verb; one of the sqlite3.SQLITE_DBCONFIG codes."); +" The configuration verb;\n" +" one of the sqlite3.SQLITE_DBCONFIG codes."); #define SETCONFIG_METHODDEF \ {"setconfig", _PyCFunction_CAST(setconfig), METH_FASTCALL, setconfig__doc__}, @@ -1677,7 +1678,8 @@ PyDoc_STRVAR(getconfig__doc__, "Query a boolean connection configuration option.\n" "\n" " op\n" -" The configuration verb; one of the sqlite3.SQLITE_DBCONFIG codes."); +" The configuration verb;\n" +" one of the sqlite3.SQLITE_DBCONFIG codes."); #define GETCONFIG_METHODDEF \ {"getconfig", (PyCFunction)getconfig, METH_O, getconfig__doc__}, @@ -1725,4 +1727,4 @@ getconfig(PyObject *self, PyObject *arg) #ifndef DESERIALIZE_METHODDEF #define DESERIALIZE_METHODDEF #endif /* !defined(DESERIALIZE_METHODDEF) */ -/*[clinic end generated code: output=1418b72751ef68fc input=a9049054013a1b77]*/ +/*[clinic end generated code: output=317aee0f4574b989 input=a9049054013a1b77]*/ diff --git a/Modules/_sqlite/connection.c b/Modules/_sqlite/connection.c index 892740b05e55c98..85fa4755bea2d7e 100644 --- a/Modules/_sqlite/connection.c +++ b/Modules/_sqlite/connection.c @@ -2539,7 +2539,8 @@ is_int_config(const int op) _sqlite3.Connection.setconfig as setconfig op: int - The configuration verb; one of the sqlite3.SQLITE_DBCONFIG codes. + The configuration verb; + one of the sqlite3.SQLITE_DBCONFIG codes. enable: bool = True / @@ -2548,7 +2549,7 @@ Set a boolean connection configuration option. static PyObject * setconfig_impl(pysqlite_Connection *self, int op, int enable) -/*[clinic end generated code: output=c60b13e618aff873 input=a10f1539c2d7da6b]*/ +/*[clinic end generated code: output=c60b13e618aff873 input=8f00e4c0d499abcb]*/ { if (!pysqlite_check_thread(self) || !pysqlite_check_connection(self)) { return NULL; @@ -2574,7 +2575,8 @@ setconfig_impl(pysqlite_Connection *self, int op, int enable) _sqlite3.Connection.getconfig as getconfig -> bool op: int - The configuration verb; one of the sqlite3.SQLITE_DBCONFIG codes. + The configuration verb; + one of the sqlite3.SQLITE_DBCONFIG codes. / Query a boolean connection configuration option. @@ -2582,7 +2584,7 @@ Query a boolean connection configuration option. static int getconfig_impl(pysqlite_Connection *self, int op) -/*[clinic end generated code: output=25ac05044c7b78a3 input=b0526d7e432e3f2f]*/ +/*[clinic end generated code: output=25ac05044c7b78a3 input=835b01bdd9069c02]*/ { if (!pysqlite_check_thread(self) || !pysqlite_check_connection(self)) { return -1; diff --git a/Modules/_sre/clinic/sre.c.h b/Modules/_sre/clinic/sre.c.h index b49bf4e058b69b6..1f105457cf76083 100644 --- a/Modules/_sre/clinic/sre.c.h +++ b/Modules/_sre/clinic/sre.c.h @@ -1157,8 +1157,8 @@ PyDoc_STRVAR(_sre_template__doc__, "\n" "\n" " template\n" -" A list containing interleaved literal strings (str or bytes) and group\n" -" indices (int), as returned by re._parser.parse_template():\n" +" A list containing interleaved literal strings (str or bytes) and\n" +" group indices (int), as returned by re._parser.parse_template():\n" " [literal1, group1, ..., literalN, groupN]"); #define _SRE_TEMPLATE_METHODDEF \ @@ -1568,4 +1568,4 @@ _sre_SRE_Scanner_search(PyObject *self, PyTypeObject *cls, PyObject *const *args #ifndef _SRE_SRE_PATTERN__FAIL_AFTER_METHODDEF #define _SRE_SRE_PATTERN__FAIL_AFTER_METHODDEF #endif /* !defined(_SRE_SRE_PATTERN__FAIL_AFTER_METHODDEF) */ -/*[clinic end generated code: output=0c867efb64e020aa input=a9049054013a1b77]*/ +/*[clinic end generated code: output=e6a6c09db286a372 input=a9049054013a1b77]*/ diff --git a/Modules/_sre/sre.c b/Modules/_sre/sre.c index e742a25e4891fce..54f24ea5ed60367 100644 --- a/Modules/_sre/sre.c +++ b/Modules/_sre/sre.c @@ -1862,8 +1862,8 @@ _sre.template pattern: object template: object(subclass_of="&PyList_Type") - A list containing interleaved literal strings (str or bytes) and group - indices (int), as returned by re._parser.parse_template(): + A list containing interleaved literal strings (str or bytes) and + group indices (int), as returned by re._parser.parse_template(): [literal1, group1, ..., literalN, groupN] / @@ -1871,7 +1871,7 @@ _sre.template static PyObject * _sre_template_impl(PyObject *module, PyObject *pattern, PyObject *template) -/*[clinic end generated code: output=d51290e596ebca86 input=af55380b27f02942]*/ +/*[clinic end generated code: output=d51290e596ebca86 input=e015cbc1c71d0d20]*/ { /* template is a list containing interleaved literal strings (str or bytes) * and group indices (int), as returned by _parser.parse_template: diff --git a/Modules/_winapi.c b/Modules/_winapi.c index a649d84a7925a04..04136dd440443ce 100644 --- a/Modules/_winapi.c +++ b/Modules/_winapi.c @@ -3012,8 +3012,9 @@ _winapi_CopyFile2_impl(PyObject *module, LPCWSTR existing_file_name, _winapi.RegisterEventSource -> HANDLE unc_server_name: LPCWSTR(accept={str, NoneType}) - The UNC name of the server on which the event source should be registered. - If None, registers the event source on the local computer. + The UNC name of the server on which the event source should be + registered. If None, registers the event source on the local + computer. source_name: LPCWSTR The name of the event source to register. / @@ -3024,7 +3025,7 @@ Retrieves a registered handle to the specified event log. static HANDLE _winapi_RegisterEventSource_impl(PyObject *module, LPCWSTR unc_server_name, LPCWSTR source_name) -/*[clinic end generated code: output=e376c8950a89ae8f input=9d01059ac2156d0c]*/ +/*[clinic end generated code: output=e376c8950a89ae8f input=ca9cb7b8959582dd]*/ { HANDLE handle; diff --git a/Modules/_zstd/_zstdmodule.c b/Modules/_zstd/_zstdmodule.c index 94246dd93b17de1..936b48102d52182 100644 --- a/Modules/_zstd/_zstdmodule.c +++ b/Modules/_zstd/_zstdmodule.c @@ -342,7 +342,8 @@ _zstd.finalize_dict dict_size: Py_ssize_t The size of the dictionary. compression_level: int - Optimize for a specific Zstandard compression level, 0 means default. + Optimize for a specific Zstandard compression level, + 0 means default. / Finalize a Zstandard dictionary. @@ -353,7 +354,7 @@ _zstd_finalize_dict_impl(PyObject *module, PyBytesObject *custom_dict_bytes, PyBytesObject *samples_bytes, PyObject *samples_sizes, Py_ssize_t dict_size, int compression_level) -/*[clinic end generated code: output=f91821ba5ae85bda input=3c7e2480aa08fb56]*/ +/*[clinic end generated code: output=f91821ba5ae85bda input=954d58d6f20c85c2]*/ { Py_ssize_t chunks_number; size_t *chunk_sizes = NULL; diff --git a/Modules/_zstd/clinic/_zstdmodule.c.h b/Modules/_zstd/clinic/_zstdmodule.c.h index 766e1cfa776767b..421543fe72df5ff 100644 --- a/Modules/_zstd/clinic/_zstdmodule.c.h +++ b/Modules/_zstd/clinic/_zstdmodule.c.h @@ -84,7 +84,8 @@ PyDoc_STRVAR(_zstd_finalize_dict__doc__, " dict_size\n" " The size of the dictionary.\n" " compression_level\n" -" Optimize for a specific Zstandard compression level, 0 means default."); +" Optimize for a specific Zstandard compression level,\n" +" 0 means default."); #define _ZSTD_FINALIZE_DICT_METHODDEF \ {"finalize_dict", _PyCFunction_CAST(_zstd_finalize_dict), METH_FASTCALL, _zstd_finalize_dict__doc__}, @@ -426,4 +427,4 @@ _zstd_set_parameter_types(PyObject *module, PyObject *const *args, Py_ssize_t na exit: return return_value; } -/*[clinic end generated code: output=437b084f149e68e5 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=2ef60ca57f676751 input=a9049054013a1b77]*/ diff --git a/Modules/_zstd/clinic/compressor.c.h b/Modules/_zstd/clinic/compressor.c.h index 6775ba4826a652b..c7f857d9a1903e0 100644 --- a/Modules/_zstd/clinic/compressor.c.h +++ b/Modules/_zstd/clinic/compressor.c.h @@ -260,7 +260,8 @@ PyDoc_STRVAR(_zstd_ZstdCompressor_set_pledged_input_size__doc__, "Set the uncompressed content size to be written into the frame header.\n" "\n" " size\n" -" The size of the uncompressed data to be provided to the compressor.\n" +" The size of the uncompressed data to be provided to the\n" +" compressor.\n" "\n" "This method can be used to ensure the header of the frame about to\n" "be written includes the size of the data, unless the\n" @@ -292,4 +293,4 @@ _zstd_ZstdCompressor_set_pledged_input_size(PyObject *self, PyObject *arg) exit: return return_value; } -/*[clinic end generated code: output=1a5e21476885866c input=a9049054013a1b77]*/ +/*[clinic end generated code: output=b304ed0ec81a2119 input=a9049054013a1b77]*/ diff --git a/Modules/_zstd/compressor.c b/Modules/_zstd/compressor.c index 894568fce28d0d5..df185b0e161b7c7 100644 --- a/Modules/_zstd/compressor.c +++ b/Modules/_zstd/compressor.c @@ -696,7 +696,8 @@ _zstd_ZstdCompressor_flush_impl(ZstdCompressor *self, int mode) _zstd.ZstdCompressor.set_pledged_input_size size: zstd_contentsize - The size of the uncompressed data to be provided to the compressor. + The size of the uncompressed data to be provided to the + compressor. / Set the uncompressed content size to be written into the frame header. @@ -714,7 +715,7 @@ may be corrupted and the final chunk written may be lost. static PyObject * _zstd_ZstdCompressor_set_pledged_input_size_impl(ZstdCompressor *self, unsigned long long size) -/*[clinic end generated code: output=3a09e55cc0e3b4f9 input=714cd7a9aa10e2a8]*/ +/*[clinic end generated code: output=3a09e55cc0e3b4f9 input=2996f63a521943dc]*/ { // Error occurred while converting argument, should be unreachable assert(size != ZSTD_CONTENTSIZE_ERROR); diff --git a/Modules/binascii.c b/Modules/binascii.c index 0e7af135a6f6ce4..8613dd853db800c 100644 --- a/Modules/binascii.c +++ b/Modules/binascii.c @@ -732,8 +732,9 @@ binascii.a2b_base64 * strict_mode: bool(c_default="-1", py_default="") = False When set to true, bytes that are not part of the base64 standard are - not allowed. The same applies to excess data after padding (= / ==). - Set to True by default if ignorechars is specified, False otherwise. + not allowed. The same applies to excess data after padding + (= / ==). Set to True by default if ignorechars is specified, + False otherwise. padded: bool = True When set to false, padding in input is not required. alphabet: PyBytesObject(c_default="NULL") = BASE64_ALPHABET @@ -741,7 +742,8 @@ binascii.a2b_base64 A byte string containing characters to ignore from the input when strict_mode is true. canonical: bool = False - When set to true, reject non-zero padding bits per RFC 4648 section 3.5. + When set to true, reject non-zero padding bits + per RFC 4648 section 3.5. Decode a line of base64 data. [clinic start generated code]*/ @@ -750,7 +752,7 @@ static PyObject * binascii_a2b_base64_impl(PyObject *module, Py_buffer *data, int strict_mode, int padded, PyBytesObject *alphabet, Py_buffer *ignorechars, int canonical) -/*[clinic end generated code: output=77c46dcbf4239527 input=c99096d071deeec8]*/ +/*[clinic end generated code: output=77c46dcbf4239527 input=da635e0c9a1deb1f]*/ { assert(data->len >= 0); @@ -1648,7 +1650,8 @@ binascii.a2b_base32 ignorechars: Py_buffer = b'' A byte string containing characters to ignore from the input. canonical: bool = False - When set to true, reject non-zero padding bits per RFC 4648 section 3.5. + When set to true, reject non-zero padding bits + per RFC 4648 section 3.5. Decode a line of base32 data. [clinic start generated code]*/ @@ -1657,7 +1660,7 @@ static PyObject * binascii_a2b_base32_impl(PyObject *module, Py_buffer *data, int padded, PyBytesObject *alphabet, Py_buffer *ignorechars, int canonical) -/*[clinic end generated code: output=bc70f2bb6001fb55 input=5bfe6d1ea2f30e3b]*/ +/*[clinic end generated code: output=bc70f2bb6001fb55 input=6b823712b3ab1322]*/ { const unsigned char *ascii_data = data->buf; Py_ssize_t ascii_len = data->len; diff --git a/Modules/clinic/_lzmamodule.c.h b/Modules/clinic/_lzmamodule.c.h index bba107e8f806daf..1031219f815eb80 100644 --- a/Modules/clinic/_lzmamodule.c.h +++ b/Modules/clinic/_lzmamodule.c.h @@ -174,18 +174,18 @@ PyDoc_STRVAR(_lzma_LZMADecompressor__doc__, "\n" " format\n" " Specifies the container format of the input stream. If this is\n" -" FORMAT_AUTO (the default), the decompressor will automatically detect\n" -" whether the input is FORMAT_XZ or FORMAT_ALONE. Streams created with\n" -" FORMAT_RAW cannot be autodetected.\n" +" FORMAT_AUTO (the default), the decompressor will automatically\n" +" detect whether the input is FORMAT_XZ or FORMAT_ALONE. Streams\n" +" created with FORMAT_RAW cannot be autodetected.\n" " memlimit\n" -" Limit the amount of memory used by the decompressor. This will cause\n" -" decompression to fail if the input cannot be decompressed within the\n" -" given limit.\n" +" Limit the amount of memory used by the decompressor. This will\n" +" cause decompression to fail if the input cannot be decompressed\n" +" within the given limit.\n" " filters\n" -" A custom filter chain. This argument is required for FORMAT_RAW, and\n" -" not accepted with any other format. When provided, this should be a\n" -" sequence of dicts, each indicating the ID and options for a single\n" -" filter.\n" +" A custom filter chain. This argument is required for FORMAT_RAW,\n" +" and not accepted with any other format. When provided, this\n" +" should be a sequence of dicts, each indicating the ID and options\n" +" for a single filter.\n" "\n" "For one-shot decompression, use the decompress() function instead."); @@ -334,4 +334,4 @@ _lzma__decode_filter_properties(PyObject *module, PyObject *const *args, Py_ssiz return return_value; } -/*[clinic end generated code: output=ffc6d673d858048c input=a9049054013a1b77]*/ +/*[clinic end generated code: output=15bc2c0e6d969ca8 input=a9049054013a1b77]*/ diff --git a/Modules/clinic/_winapi.c.h b/Modules/clinic/_winapi.c.h index 031a0783aef60bb..8bdce5795dc2230 100644 --- a/Modules/clinic/_winapi.c.h +++ b/Modules/clinic/_winapi.c.h @@ -2191,8 +2191,9 @@ PyDoc_STRVAR(_winapi_RegisterEventSource__doc__, "Retrieves a registered handle to the specified event log.\n" "\n" " unc_server_name\n" -" The UNC name of the server on which the event source should be registered.\n" -" If None, registers the event source on the local computer.\n" +" The UNC name of the server on which the event source should be\n" +" registered. If None, registers the event source on the local\n" +" computer.\n" " source_name\n" " The name of the event source to register."); @@ -2379,4 +2380,4 @@ _winapi_GetTickCount64(PyObject *module, PyObject *Py_UNUSED(ignored)) #ifndef _WINAPI_GETSHORTPATHNAME_METHODDEF #define _WINAPI_GETSHORTPATHNAME_METHODDEF #endif /* !defined(_WINAPI_GETSHORTPATHNAME_METHODDEF) */ -/*[clinic end generated code: output=713a8ce97185b017 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=54e30e2214214ed4 input=a9049054013a1b77]*/ diff --git a/Modules/clinic/binascii.c.h b/Modules/clinic/binascii.c.h index 29fa9e87de87c7a..de68c26ebde59e4 100644 --- a/Modules/clinic/binascii.c.h +++ b/Modules/clinic/binascii.c.h @@ -126,15 +126,17 @@ PyDoc_STRVAR(binascii_a2b_base64__doc__, "\n" " strict_mode\n" " When set to true, bytes that are not part of the base64 standard are\n" -" not allowed. The same applies to excess data after padding (= / ==).\n" -" Set to True by default if ignorechars is specified, False otherwise.\n" +" not allowed. The same applies to excess data after padding\n" +" (= / ==). Set to True by default if ignorechars is specified,\n" +" False otherwise.\n" " padded\n" " When set to false, padding in input is not required.\n" " ignorechars\n" " A byte string containing characters to ignore from the input when\n" " strict_mode is true.\n" " canonical\n" -" When set to true, reject non-zero padding bits per RFC 4648 section 3.5."); +" When set to true, reject non-zero padding bits\n" +" per RFC 4648 section 3.5."); #define BINASCII_A2B_BASE64_METHODDEF \ {"a2b_base64", _PyCFunction_CAST(binascii_a2b_base64), METH_FASTCALL|METH_KEYWORDS, binascii_a2b_base64__doc__}, @@ -816,7 +818,8 @@ PyDoc_STRVAR(binascii_a2b_base32__doc__, " ignorechars\n" " A byte string containing characters to ignore from the input.\n" " canonical\n" -" When set to true, reject non-zero padding bits per RFC 4648 section 3.5."); +" When set to true, reject non-zero padding bits\n" +" per RFC 4648 section 3.5."); #define BINASCII_A2B_BASE32_METHODDEF \ {"a2b_base32", _PyCFunction_CAST(binascii_a2b_base32), METH_FASTCALL|METH_KEYWORDS, binascii_a2b_base32__doc__}, @@ -1685,4 +1688,4 @@ binascii_b2a_qp(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObj return return_value; } -/*[clinic end generated code: output=42dd48f323cbb118 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=2ed68937eeab7766 input=a9049054013a1b77]*/ diff --git a/Modules/clinic/gcmodule.c.h b/Modules/clinic/gcmodule.c.h index aa743c8f40a565f..db1880e86e92666 100644 --- a/Modules/clinic/gcmodule.c.h +++ b/Modules/clinic/gcmodule.c.h @@ -162,7 +162,8 @@ PyDoc_STRVAR(gc_set_debug__doc__, " DEBUG_COLLECTABLE - Print collectable objects found.\n" " DEBUG_UNCOLLECTABLE - Print unreachable but uncollectable objects\n" " found.\n" -" DEBUG_SAVEALL - Save objects to gc.garbage rather than freeing them.\n" +" DEBUG_SAVEALL - Save objects to gc.garbage rather than\n" +" freeing them.\n" " DEBUG_LEAK - Debug leaking programs (everything but STATS).\n" "\n" "Debugging information is written to sys.stderr."); @@ -584,4 +585,4 @@ gc_get_freeze_count(PyObject *module, PyObject *Py_UNUSED(ignored)) exit: return return_value; } -/*[clinic end generated code: output=756c0e7719b76971 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=34642af2e85b6715 input=a9049054013a1b77]*/ diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h index ac9b63dec9eb440..391e54e6ed6b963 100644 --- a/Modules/clinic/posixmodule.c.h +++ b/Modules/clinic/posixmodule.c.h @@ -3940,8 +3940,8 @@ PyDoc_STRVAR(os_posix_spawn__doc__, " resetids\n" " If the value is `true` the POSIX_SPAWN_RESETIDS will be activated.\n" " setsid\n" -" If the value is `true` the POSIX_SPAWN_SETSID or POSIX_SPAWN_SETSID_NP\n" -" will be activated.\n" +" If the value is `true` the POSIX_SPAWN_SETSID or\n" +" POSIX_SPAWN_SETSID_NP will be activated.\n" " setsigmask\n" " The sigmask to use with the POSIX_SPAWN_SETSIGMASK flag.\n" " setsigdef\n" @@ -4094,8 +4094,8 @@ PyDoc_STRVAR(os_posix_spawnp__doc__, " resetids\n" " If the value is `True` the POSIX_SPAWN_RESETIDS will be activated.\n" " setsid\n" -" If the value is `True` the POSIX_SPAWN_SETSID or POSIX_SPAWN_SETSID_NP\n" -" will be activated.\n" +" If the value is `True` the POSIX_SPAWN_SETSID or\n" +" POSIX_SPAWN_SETSID_NP will be activated.\n" " setsigmask\n" " The sigmask to use with the POSIX_SPAWN_SETSIGMASK flag.\n" " setsigdef\n" @@ -6874,7 +6874,8 @@ PyDoc_STRVAR(os_timerfd_create__doc__, "\n" " os.TFD_NONBLOCK\n" " If *TFD_NONBLOCK* is set as a flag, read doesn\'t blocks.\n" -" If *TFD_NONBLOCK* is not set as a flag, read block until the timer fires.\n" +" If *TFD_NONBLOCK* is not set as a flag, read block until\n" +" the timer fires.\n" "\n" " os.TFD_CLOEXEC\n" " If *TFD_CLOEXEC* is set as a flag, enable the close-on-exec flag"); @@ -13734,4 +13735,4 @@ os__emscripten_log(PyObject *module, PyObject *const *args, Py_ssize_t nargs, Py #ifndef OS__EMSCRIPTEN_LOG_METHODDEF #define OS__EMSCRIPTEN_LOG_METHODDEF #endif /* !defined(OS__EMSCRIPTEN_LOG_METHODDEF) */ -/*[clinic end generated code: output=d641f02a97057666 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=6fdef8d3b0bc5468 input=a9049054013a1b77]*/ diff --git a/Modules/clinic/selectmodule.c.h b/Modules/clinic/selectmodule.c.h index c1c8ad40e724f53..7005b5f8d1c89e5 100644 --- a/Modules/clinic/selectmodule.c.h +++ b/Modules/clinic/selectmodule.c.h @@ -81,7 +81,8 @@ PyDoc_STRVAR(select_poll_register__doc__, "Register a file descriptor with the polling object.\n" "\n" " fd\n" -" either an integer, or an object with a fileno() method returning an int\n" +" either an integer, or an object with a fileno() method\n" +" returning an int\n" " eventmask\n" " an optional bitmask describing the type of events to check for"); @@ -212,8 +213,8 @@ PyDoc_STRVAR(select_poll_poll__doc__, "Polls the set of registered file descriptors.\n" "\n" " timeout\n" -" The maximum time to wait in milliseconds, or else None (or a negative\n" -" value) to wait indefinitely.\n" +" The maximum time to wait in milliseconds, or else None (or a\n" +" negative value) to wait indefinitely.\n" "\n" "Returns a list containing any descriptors that have events or errors\n" "to report, as a list of (fd, event) 2-tuples."); @@ -550,13 +551,14 @@ PyDoc_STRVAR(select_epoll__doc__, "Returns an epolling object.\n" "\n" " sizehint\n" -" The expected number of events to be registered. It must be positive,\n" -" or -1 to use the default. It is only used on older systems where\n" -" epoll_create1() is not available; otherwise it has no effect (though its\n" -" value is still checked).\n" +" The expected number of events to be registered. It must be\n" +" positive, or -1 to use the default. It is only used on older\n" +" systems where epoll_create1() is not available; otherwise it has no\n" +" effect (though its value is still checked).\n" " flags\n" -" Deprecated and completely ignored. However, when supplied, its value\n" -" must be 0 or select.EPOLL_CLOEXEC, otherwise OSError is raised."); +" Deprecated and completely ignored. However, when supplied, its\n" +" value must be 0 or select.EPOLL_CLOEXEC, otherwise OSError is\n" +" raised."); static PyObject * select_epoll_impl(PyTypeObject *type, int sizehint, int flags); @@ -1257,13 +1259,13 @@ PyDoc_STRVAR(select_kqueue_control__doc__, "Calls the kernel kevent function.\n" "\n" " changelist\n" -" Must be an iterable of kevent objects describing the changes to be made\n" -" to the kernel\'s watch list or None.\n" +" Must be an iterable of kevent objects describing the changes to\n" +" be made to the kernel\'s watch list or None.\n" " maxevents\n" " The maximum number of events that the kernel will return.\n" " timeout\n" -" The maximum time to wait in seconds, or else None to wait forever.\n" -" This accepts non-integers for smaller timeouts, too."); +" The maximum time to wait in seconds, or else None to wait\n" +" forever. This accepts non-integers for smaller timeouts, too."); #define SELECT_KQUEUE_CONTROL_METHODDEF \ {"control", _PyCFunction_CAST(select_kqueue_control), METH_FASTCALL, select_kqueue_control__doc__}, @@ -1400,4 +1402,4 @@ select_kqueue_control(PyObject *self, PyObject *const *args, Py_ssize_t nargs) #ifndef SELECT_KQUEUE_CONTROL_METHODDEF #define SELECT_KQUEUE_CONTROL_METHODDEF #endif /* !defined(SELECT_KQUEUE_CONTROL_METHODDEF) */ -/*[clinic end generated code: output=a1ac666294fd14bd input=a9049054013a1b77]*/ +/*[clinic end generated code: output=c264b5fa0dca38e1 input=a9049054013a1b77]*/ diff --git a/Modules/clinic/zlibmodule.c.h b/Modules/clinic/zlibmodule.c.h index 620e483d5a759a7..c1d6f5625c92371 100644 --- a/Modules/clinic/zlibmodule.c.h +++ b/Modules/clinic/zlibmodule.c.h @@ -222,14 +222,14 @@ PyDoc_STRVAR(zlib_compressobj__doc__, " method\n" " The compression algorithm. If given, this must be DEFLATED.\n" " wbits\n" -" +9 to +15: The base-two logarithm of the window size. Include a zlib\n" -" container.\n" +" +9 to +15: The base-two logarithm of the window size.\n" +" Include a zlib container.\n" " -9 to -15: Generate a raw stream.\n" " +25 to +31: Include a gzip container.\n" " memLevel\n" " Controls the amount of memory used for internal compression state.\n" -" Valid values range from 1 to 9. Higher values result in higher memory\n" -" usage, faster compression, and smaller output.\n" +" Valid values range from 1 to 9. Higher values result in higher\n" +" memory usage, faster compression, and smaller output.\n" " strategy\n" " Used to tune the compression algorithm. Possible values are\n" " Z_DEFAULT_STRATEGY, Z_FILTERED, and Z_HUFFMAN_ONLY.\n" @@ -1018,8 +1018,8 @@ PyDoc_STRVAR(zlib__ZlibDecompressor__doc__, " (such as a bytes object) containing subsequences that are expected\n" " to occur frequently in the data that is to be compressed. Those\n" " subsequences that are expected to be most common should come at the\n" -" end of the dictionary. This must be the same dictionary as used by the\n" -" compressor that produced the input data."); +" end of the dictionary. This must be the same dictionary as used by\n" +" the compressor that produced the input data."); static PyObject * zlib__ZlibDecompressor_impl(PyTypeObject *type, int wbits, PyObject *zdict); @@ -1403,4 +1403,4 @@ zlib_crc32_combine(PyObject *module, PyObject *const *args, Py_ssize_t nargs) #ifndef ZLIB_DECOMPRESS___DEEPCOPY___METHODDEF #define ZLIB_DECOMPRESS___DEEPCOPY___METHODDEF #endif /* !defined(ZLIB_DECOMPRESS___DEEPCOPY___METHODDEF) */ -/*[clinic end generated code: output=c9a60fe6600a2e4d input=a9049054013a1b77]*/ +/*[clinic end generated code: output=22bab4a51025d11e input=a9049054013a1b77]*/ diff --git a/Modules/gcmodule.c b/Modules/gcmodule.c index e2df31556f3c372..37d5a21e5f203ba 100644 --- a/Modules/gcmodule.c +++ b/Modules/gcmodule.c @@ -102,7 +102,8 @@ gc.set_debug DEBUG_COLLECTABLE - Print collectable objects found. DEBUG_UNCOLLECTABLE - Print unreachable but uncollectable objects found. - DEBUG_SAVEALL - Save objects to gc.garbage rather than freeing them. + DEBUG_SAVEALL - Save objects to gc.garbage rather than + freeing them. DEBUG_LEAK - Debug leaking programs (everything but STATS). / @@ -113,7 +114,7 @@ Debugging information is written to sys.stderr. static PyObject * gc_set_debug_impl(PyObject *module, int flags) -/*[clinic end generated code: output=7c8366575486b228 input=5e5ce15e84fbed15]*/ +/*[clinic end generated code: output=7c8366575486b228 input=e7c3321830e0abe3]*/ { GCState *gcstate = get_gc_state(); gcstate->debug = flags; diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index db65d5862440655..bb12d7f1d7e2390 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -8070,8 +8070,8 @@ os.posix_spawn resetids: bool = False If the value is `true` the POSIX_SPAWN_RESETIDS will be activated. setsid: bool = False - If the value is `true` the POSIX_SPAWN_SETSID or POSIX_SPAWN_SETSID_NP - will be activated. + If the value is `true` the POSIX_SPAWN_SETSID or + POSIX_SPAWN_SETSID_NP will be activated. setsigmask: object(c_default='NULL') = () The sigmask to use with the POSIX_SPAWN_SETSIGMASK flag. setsigdef: object(c_default='NULL') = () @@ -8088,7 +8088,7 @@ os_posix_spawn_impl(PyObject *module, path_t *path, PyObject *argv, PyObject *setpgroup, int resetids, int setsid, PyObject *setsigmask, PyObject *setsigdef, PyObject *scheduler) -/*[clinic end generated code: output=14a1098c566bc675 input=c7592dcbc96e8114]*/ +/*[clinic end generated code: output=14a1098c566bc675 input=ddf326d12aa98d13]*/ { return py_posix_spawn(0, module, path, argv, env, file_actions, setpgroup, resetids, setsid, setsigmask, setsigdef, @@ -8117,8 +8117,8 @@ os.posix_spawnp resetids: bool = False If the value is `True` the POSIX_SPAWN_RESETIDS will be activated. setsid: bool = False - If the value is `True` the POSIX_SPAWN_SETSID or POSIX_SPAWN_SETSID_NP - will be activated. + If the value is `True` the POSIX_SPAWN_SETSID or + POSIX_SPAWN_SETSID_NP will be activated. setsigmask: object(c_default='NULL') = () The sigmask to use with the POSIX_SPAWN_SETSIGMASK flag. setsigdef: object(c_default='NULL') = () @@ -8135,7 +8135,7 @@ os_posix_spawnp_impl(PyObject *module, path_t *path, PyObject *argv, PyObject *setpgroup, int resetids, int setsid, PyObject *setsigmask, PyObject *setsigdef, PyObject *scheduler) -/*[clinic end generated code: output=7b9aaefe3031238d input=43ccc1452cae2be3]*/ +/*[clinic end generated code: output=7b9aaefe3031238d input=2fa6fb7dabd3dedd]*/ { return py_posix_spawn(1, module, path, argv, env, file_actions, setpgroup, resetids, setsid, setsigmask, setsigdef, @@ -11417,7 +11417,8 @@ os.timerfd_create os.TFD_NONBLOCK If *TFD_NONBLOCK* is set as a flag, read doesn't blocks. - If *TFD_NONBLOCK* is not set as a flag, read block until the timer fires. + If *TFD_NONBLOCK* is not set as a flag, read block until + the timer fires. os.TFD_CLOEXEC If *TFD_CLOEXEC* is set as a flag, enable the close-on-exec flag @@ -11427,7 +11428,7 @@ Create and return a timer file descriptor. static PyObject * os_timerfd_create_impl(PyObject *module, int clockid, int flags) -/*[clinic end generated code: output=1caae80fb168004a input=64b7020c5ac0b8f4]*/ +/*[clinic end generated code: output=1caae80fb168004a input=41ec2d5ea5c041a5]*/ { int fd; diff --git a/Modules/selectmodule.c b/Modules/selectmodule.c index b9fb7762e3dacdf..f4b490b302f16cb 100644 --- a/Modules/selectmodule.c +++ b/Modules/selectmodule.c @@ -481,7 +481,8 @@ update_ufd_array(pollObject *self) select.poll.register fd: fildes - either an integer, or an object with a fileno() method returning an int + either an integer, or an object with a fileno() method + returning an int eventmask: unsigned_short(c_default="POLLIN | POLLPRI | POLLOUT") = select.POLLIN | select.POLLPRI | select.POLLOUT an optional bitmask describing the type of events to check for / @@ -491,7 +492,7 @@ Register a file descriptor with the polling object. static PyObject * select_poll_register_impl(pollObject *self, int fd, unsigned short eventmask) -/*[clinic end generated code: output=0dc7173c800a4a65 input=c475e029ce6c2830]*/ +/*[clinic end generated code: output=0dc7173c800a4a65 input=56be3dc0bd0d7858]*/ { PyObject *key, *value; int err; @@ -610,8 +611,8 @@ select_poll_unregister_impl(pollObject *self, int fd) select.poll.poll timeout as timeout_obj: object = None - The maximum time to wait in milliseconds, or else None (or a negative - value) to wait indefinitely. + The maximum time to wait in milliseconds, or else None (or a + negative value) to wait indefinitely. / Polls the set of registered file descriptors. @@ -622,7 +623,7 @@ to report, as a list of (fd, event) 2-tuples. static PyObject * select_poll_poll_impl(pollObject *self, PyObject *timeout_obj) -/*[clinic end generated code: output=876e837d193ed7e4 input=e0a9c0aa283de8c8]*/ +/*[clinic end generated code: output=876e837d193ed7e4 input=ce649b435fccd6a6]*/ { PyObject *result_list = NULL; int poll_result, i, j; @@ -1386,20 +1387,21 @@ newPyEpoll_Object(PyTypeObject *type, int sizehint, SOCKET fd) select.epoll.__new__ sizehint: int = -1 - The expected number of events to be registered. It must be positive, - or -1 to use the default. It is only used on older systems where - epoll_create1() is not available; otherwise it has no effect (though its - value is still checked). + The expected number of events to be registered. It must be + positive, or -1 to use the default. It is only used on older + systems where epoll_create1() is not available; otherwise it has no + effect (though its value is still checked). flags: int = 0 - Deprecated and completely ignored. However, when supplied, its value - must be 0 or select.EPOLL_CLOEXEC, otherwise OSError is raised. + Deprecated and completely ignored. However, when supplied, its + value must be 0 or select.EPOLL_CLOEXEC, otherwise OSError is + raised. Returns an epolling object. [clinic start generated code]*/ static PyObject * select_epoll_impl(PyTypeObject *type, int sizehint, int flags) -/*[clinic end generated code: output=c87404e705013bb5 input=303e3295e7975e43]*/ +/*[clinic end generated code: output=c87404e705013bb5 input=8a00db8f43da1805]*/ { if (sizehint == -1) { sizehint = FD_SETSIZE - 1; @@ -2320,13 +2322,13 @@ select_kqueue_fromfd_impl(PyTypeObject *type, int fd) select.kqueue.control changelist: object - Must be an iterable of kevent objects describing the changes to be made - to the kernel's watch list or None. + Must be an iterable of kevent objects describing the changes to + be made to the kernel's watch list or None. maxevents: int The maximum number of events that the kernel will return. timeout as otimeout: object = None - The maximum time to wait in seconds, or else None to wait forever. - This accepts non-integers for smaller timeouts, too. + The maximum time to wait in seconds, or else None to wait + forever. This accepts non-integers for smaller timeouts, too. / Calls the kernel kevent function. @@ -2335,7 +2337,7 @@ Calls the kernel kevent function. static PyObject * select_kqueue_control_impl(kqueue_queue_Object *self, PyObject *changelist, int maxevents, PyObject *otimeout) -/*[clinic end generated code: output=81324ff5130db7ae input=be969d2bc6f84205]*/ +/*[clinic end generated code: output=81324ff5130db7ae input=4871319486c4d5a4]*/ { int gotevents = 0; int nchanges = 0; diff --git a/Modules/zlibmodule.c b/Modules/zlibmodule.c index 0a6732835eb51f5..051a839ceb64720 100644 --- a/Modules/zlibmodule.c +++ b/Modules/zlibmodule.c @@ -539,14 +539,14 @@ zlib.compressobj method: int(c_default="DEFLATED") = DEFLATED The compression algorithm. If given, this must be DEFLATED. wbits: int(c_default="MAX_WBITS") = MAX_WBITS - +9 to +15: The base-two logarithm of the window size. Include a zlib - container. + +9 to +15: The base-two logarithm of the window size. + Include a zlib container. -9 to -15: Generate a raw stream. +25 to +31: Include a gzip container. memLevel: int(c_default="DEF_MEM_LEVEL") = DEF_MEM_LEVEL Controls the amount of memory used for internal compression state. - Valid values range from 1 to 9. Higher values result in higher memory - usage, faster compression, and smaller output. + Valid values range from 1 to 9. Higher values result in higher + memory usage, faster compression, and smaller output. strategy: int(c_default="Z_DEFAULT_STRATEGY") = Z_DEFAULT_STRATEGY Used to tune the compression algorithm. Possible values are Z_DEFAULT_STRATEGY, Z_FILTERED, and Z_HUFFMAN_ONLY. @@ -560,7 +560,7 @@ Return a compressor object. static PyObject * zlib_compressobj_impl(PyObject *module, int level, int method, int wbits, int memLevel, int strategy, Py_buffer *zdict) -/*[clinic end generated code: output=8b5bed9c8fc3814d input=1a6f61d8a8885c0d]*/ +/*[clinic end generated code: output=8b5bed9c8fc3814d input=fc941e14bc50ddf3]*/ { zlibstate *state = get_zlib_state(module); if (zdict->buf != NULL && (size_t)zdict->len > UINT_MAX) { @@ -1727,15 +1727,15 @@ zlib._ZlibDecompressor.__new__ (such as a bytes object) containing subsequences that are expected to occur frequently in the data that is to be compressed. Those subsequences that are expected to be most common should come at the - end of the dictionary. This must be the same dictionary as used by the - compressor that produced the input data. + end of the dictionary. This must be the same dictionary as used by + the compressor that produced the input data. Create a decompressor object for decompressing data incrementally. [clinic start generated code]*/ static PyObject * zlib__ZlibDecompressor_impl(PyTypeObject *type, int wbits, PyObject *zdict) -/*[clinic end generated code: output=1065607df0d33baa input=9ebad0be6de226e2]*/ +/*[clinic end generated code: output=1065607df0d33baa input=c174bee81ce1209c]*/ { assert(type != NULL && type->tp_alloc != NULL); zlibstate *state = PyType_GetModuleState(type); diff --git a/Objects/bytearrayobject.c b/Objects/bytearrayobject.c index d009877dc09fac0..edc86c5eb65a951 100644 --- a/Objects/bytearrayobject.c +++ b/Objects/bytearrayobject.c @@ -1556,14 +1556,15 @@ bytearray_resize_impl(PyByteArrayObject *self, Py_ssize_t size) @critical_section bytearray.take_bytes n: object = None - Bytes to take, negative indexes from end. None indicates all bytes. + Bytes to take, negative indexes from end. + None indicates all bytes. / Take *n* bytes from the bytearray and return them as a bytes object. [clinic start generated code]*/ static PyObject * bytearray_take_bytes_impl(PyByteArrayObject *self, PyObject *n) -/*[clinic end generated code: output=3147fbc0bbbe8d94 input=b15b5172cdc6deda]*/ +/*[clinic end generated code: output=3147fbc0bbbe8d94 input=d171cf2075fbd6ba]*/ { Py_ssize_t to_take; Py_ssize_t size = Py_SIZE(self); @@ -1813,7 +1814,8 @@ bytearray.split sep: object = None The delimiter according which to split the bytearray. None (the default value) means split on ASCII whitespace - characters (space, tab, return, newline, formfeed, vertical tab). + characters (space, tab, return, newline, formfeed, + vertical tab). maxsplit: Py_ssize_t = -1 Maximum number of splits to do. -1 (the default value) means no limit. @@ -1824,7 +1826,7 @@ Return a list of the sections in the bytearray, using sep as the delimiter. static PyObject * bytearray_split_impl(PyByteArrayObject *self, PyObject *sep, Py_ssize_t maxsplit) -/*[clinic end generated code: output=833e2cf385d9a04d input=45605178023b52ac]*/ +/*[clinic end generated code: output=833e2cf385d9a04d input=ca467495c4370fb3]*/ { PyObject *list = NULL; diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index ef35dad82e8aaea..deea76d91476a1b 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -1855,7 +1855,8 @@ bytes.split sep: object = None The delimiter according which to split the bytes. None (the default value) means split on ASCII whitespace - characters (space, tab, return, newline, formfeed, vertical tab). + characters (space, tab, return, newline, formfeed, + vertical tab). maxsplit: Py_ssize_t = -1 Maximum number of splits to do. -1 (the default value) means no limit. @@ -1865,7 +1866,7 @@ Return a list of the sections in the bytes, using sep as the delimiter. static PyObject * bytes_split_impl(PyBytesObject *self, PyObject *sep, Py_ssize_t maxsplit) -/*[clinic end generated code: output=52126b5844c1d8ef input=330ff95d92544b05]*/ +/*[clinic end generated code: output=52126b5844c1d8ef input=5696b84d8fb109f9]*/ { Py_ssize_t len = PyBytes_GET_SIZE(self), n; const char *s = PyBytes_AS_STRING(self), *sub; diff --git a/Objects/clinic/bytearrayobject.c.h b/Objects/clinic/bytearrayobject.c.h index 41ce82c05c57d97..7b027110923e891 100644 --- a/Objects/clinic/bytearrayobject.c.h +++ b/Objects/clinic/bytearrayobject.c.h @@ -640,7 +640,8 @@ PyDoc_STRVAR(bytearray_take_bytes__doc__, "Take *n* bytes from the bytearray and return them as a bytes object.\n" "\n" " n\n" -" Bytes to take, negative indexes from end. None indicates all bytes."); +" Bytes to take, negative indexes from end.\n" +" None indicates all bytes."); #define BYTEARRAY_TAKE_BYTES_METHODDEF \ {"take_bytes", _PyCFunction_CAST(bytearray_take_bytes), METH_FASTCALL, bytearray_take_bytes__doc__}, @@ -903,7 +904,8 @@ PyDoc_STRVAR(bytearray_split__doc__, " sep\n" " The delimiter according which to split the bytearray.\n" " None (the default value) means split on ASCII whitespace\n" -" characters (space, tab, return, newline, formfeed, vertical tab).\n" +" characters (space, tab, return, newline, formfeed,\n" +" vertical tab).\n" " maxsplit\n" " Maximum number of splits to do.\n" " -1 (the default value) means no limit."); @@ -1060,7 +1062,8 @@ PyDoc_STRVAR(bytearray_rsplit__doc__, " sep\n" " The delimiter according which to split the bytearray.\n" " None (the default value) means split on ASCII whitespace\n" -" characters (space, tab, return, newline, formfeed, vertical tab).\n" +" characters (space, tab, return, newline, formfeed,\n" +" vertical tab).\n" " maxsplit\n" " Maximum number of splits to do.\n" " -1 (the default value) means no limit.\n" @@ -1882,4 +1885,4 @@ bytearray_sizeof(PyObject *self, PyObject *Py_UNUSED(ignored)) { return bytearray_sizeof_impl((PyByteArrayObject *)self); } -/*[clinic end generated code: output=6dc315d35de3e670 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=430e4855ba3f7af4 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/bytesobject.c.h b/Objects/clinic/bytesobject.c.h index ee2b737f9e63f97..34d2ef4627d7914 100644 --- a/Objects/clinic/bytesobject.c.h +++ b/Objects/clinic/bytesobject.c.h @@ -36,7 +36,8 @@ PyDoc_STRVAR(bytes_split__doc__, " sep\n" " The delimiter according which to split the bytes.\n" " None (the default value) means split on ASCII whitespace\n" -" characters (space, tab, return, newline, formfeed, vertical tab).\n" +" characters (space, tab, return, newline, formfeed,\n" +" vertical tab).\n" " maxsplit\n" " Maximum number of splits to do.\n" " -1 (the default value) means no limit."); @@ -204,7 +205,8 @@ PyDoc_STRVAR(bytes_rsplit__doc__, " sep\n" " The delimiter according which to split the bytes.\n" " None (the default value) means split on ASCII whitespace\n" -" characters (space, tab, return, newline, formfeed, vertical tab).\n" +" characters (space, tab, return, newline, formfeed,\n" +" vertical tab).\n" " maxsplit\n" " Maximum number of splits to do.\n" " -1 (the default value) means no limit.\n" @@ -1455,4 +1457,4 @@ bytes_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) exit: return return_value; } -/*[clinic end generated code: output=c20458db7a2123db input=a9049054013a1b77]*/ +/*[clinic end generated code: output=c1914771783c124c input=a9049054013a1b77]*/ diff --git a/Objects/clinic/longobject.c.h b/Objects/clinic/longobject.c.h index 52ecaffa1f4cf35..0bb668cacef1095 100644 --- a/Objects/clinic/longobject.c.h +++ b/Objects/clinic/longobject.c.h @@ -268,9 +268,9 @@ PyDoc_STRVAR(int_to_bytes__doc__, " byteorder\n" " The byte order used to represent the integer. If byteorder is\n" " \'big\', the most significant byte is at the beginning of the byte\n" -" array. If byteorder is \'little\', the most significant byte is at\n" -" the end of the byte array. To request the native byte order of\n" -" the host system, use sys.byteorder as the byte order value.\n" +" array. If byteorder is \'little\', the most significant byte is\n" +" at the end of the byte array. To request the native byte order\n" +" of the host system, use sys.byteorder as the byte order value.\n" " Default is to use \'big\'.\n" " signed\n" " Determines whether two\'s complement is used to represent the\n" @@ -385,14 +385,14 @@ PyDoc_STRVAR(int_from_bytes__doc__, " bytes\n" " Holds the array of bytes to convert. The argument must either\n" " support the buffer protocol or be an iterable object producing\n" -" bytes. Bytes and bytearray are examples of built-in objects that\n" -" support the buffer protocol.\n" +" bytes. Bytes and bytearray are examples of built-in objects\n" +" that support the buffer protocol.\n" " byteorder\n" " The byte order used to represent the integer. If byteorder is\n" " \'big\', the most significant byte is at the beginning of the byte\n" -" array. If byteorder is \'little\', the most significant byte is at\n" -" the end of the byte array. To request the native byte order of\n" -" the host system, use sys.byteorder as the byte order value.\n" +" array. If byteorder is \'little\', the most significant byte is\n" +" at the end of the byte array. To request the native byte order\n" +" of the host system, use sys.byteorder as the byte order value.\n" " Default is to use \'big\'.\n" " signed\n" " Indicates whether two\'s complement is used to represent the\n" @@ -493,4 +493,4 @@ int_is_integer(PyObject *self, PyObject *Py_UNUSED(ignored)) { return int_is_integer_impl(self); } -/*[clinic end generated code: output=d95766fb7ff46963 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=447dd48eaf0c6bf1 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/unicodeobject.c.h b/Objects/clinic/unicodeobject.c.h index d0753b38843fccf..740b1ff44dd13af 100644 --- a/Objects/clinic/unicodeobject.c.h +++ b/Objects/clinic/unicodeobject.c.h @@ -204,9 +204,10 @@ PyDoc_STRVAR(unicode_encode__doc__, " errors\n" " The error handling scheme to use for encoding errors.\n" " The default is \'strict\' meaning that encoding errors raise a\n" -" UnicodeEncodeError. Other possible values are \'ignore\', \'replace\'\n" -" and \'xmlcharrefreplace\' as well as any other name registered with\n" -" codecs.register_error that can handle UnicodeEncodeErrors."); +" UnicodeEncodeError. Other possible values are \'ignore\',\n" +" \'replace\' and \'xmlcharrefreplace\' as well as any other name\n" +" registered with codecs.register_error that can handle\n" +" UnicodeEncodeErrors."); #define UNICODE_ENCODE_METHODDEF \ {"encode", _PyCFunction_CAST(unicode_encode), METH_FASTCALL|METH_KEYWORDS, unicode_encode__doc__}, @@ -1916,4 +1917,4 @@ unicode_new(PyTypeObject *type, PyObject *args, PyObject *kwargs) exit: return return_value; } -/*[clinic end generated code: output=9d243c63e951e31d input=a9049054013a1b77]*/ +/*[clinic end generated code: output=4cdf44de2d63aa5e input=a9049054013a1b77]*/ diff --git a/Objects/longobject.c b/Objects/longobject.c index 7a38ae8ea5a36f0..ddddca168e22ca2 100644 --- a/Objects/longobject.c +++ b/Objects/longobject.c @@ -6373,9 +6373,9 @@ int.to_bytes byteorder: unicode(c_default="NULL") = "big" The byte order used to represent the integer. If byteorder is 'big', the most significant byte is at the beginning of the byte - array. If byteorder is 'little', the most significant byte is at - the end of the byte array. To request the native byte order of - the host system, use sys.byteorder as the byte order value. + array. If byteorder is 'little', the most significant byte is + at the end of the byte array. To request the native byte order + of the host system, use sys.byteorder as the byte order value. Default is to use 'big'. * signed as is_signed: bool = False @@ -6389,7 +6389,7 @@ Return an array of bytes representing an integer. static PyObject * int_to_bytes_impl(PyObject *self, Py_ssize_t length, PyObject *byteorder, int is_signed) -/*[clinic end generated code: output=89c801df114050a3 input=c74a93c07b2f6526]*/ +/*[clinic end generated code: output=89c801df114050a3 input=55c648698a882302]*/ { int little_endian; if (byteorder == NULL) @@ -6426,14 +6426,14 @@ int.from_bytes bytes as bytes_obj: object Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing - bytes. Bytes and bytearray are examples of built-in objects that - support the buffer protocol. + bytes. Bytes and bytearray are examples of built-in objects + that support the buffer protocol. byteorder: unicode(c_default="NULL") = "big" The byte order used to represent the integer. If byteorder is 'big', the most significant byte is at the beginning of the byte - array. If byteorder is 'little', the most significant byte is at - the end of the byte array. To request the native byte order of - the host system, use sys.byteorder as the byte order value. + array. If byteorder is 'little', the most significant byte is + at the end of the byte array. To request the native byte order + of the host system, use sys.byteorder as the byte order value. Default is to use 'big'. * signed as is_signed: bool = False @@ -6446,7 +6446,7 @@ Return the integer represented by the given array of bytes. static PyObject * int_from_bytes_impl(PyTypeObject *type, PyObject *bytes_obj, PyObject *byteorder, int is_signed) -/*[clinic end generated code: output=efc5d68e31f9314f input=95801e50b942e164]*/ +/*[clinic end generated code: output=efc5d68e31f9314f input=2e87fb52a6c4f41a]*/ { int little_endian; PyObject *long_obj, *bytes; diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 45d61c8b8b765a6..24cb2b1b88a2885 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -11910,16 +11910,17 @@ str.encode as unicode_encode errors: str(c_default="NULL") = 'strict' The error handling scheme to use for encoding errors. The default is 'strict' meaning that encoding errors raise a - UnicodeEncodeError. Other possible values are 'ignore', 'replace' - and 'xmlcharrefreplace' as well as any other name registered with - codecs.register_error that can handle UnicodeEncodeErrors. + UnicodeEncodeError. Other possible values are 'ignore', + 'replace' and 'xmlcharrefreplace' as well as any other name + registered with codecs.register_error that can handle + UnicodeEncodeErrors. Encode the string using the codec registered for encoding. [clinic start generated code]*/ static PyObject * unicode_encode_impl(PyObject *self, const char *encoding, const char *errors) -/*[clinic end generated code: output=bf78b6e2a9470e3c input=b85a9645cb33b729]*/ +/*[clinic end generated code: output=bf78b6e2a9470e3c input=7279de0853abd720]*/ { return PyUnicode_AsEncodedString(self, encoding, errors); } diff --git a/PC/clinic/winreg.c.h b/PC/clinic/winreg.c.h index 92cf6e8a9be1876..d29fe9126e1bd2e 100644 --- a/PC/clinic/winreg.c.h +++ b/PC/clinic/winreg.c.h @@ -1468,7 +1468,8 @@ PyDoc_STRVAR(winreg_SetValueEx__doc__, " An integer that specifies the type of the data, one of:\n" " REG_BINARY -- Binary data in any form.\n" " REG_DWORD -- A 32-bit number.\n" -" REG_DWORD_LITTLE_ENDIAN -- A 32-bit number in little-endian format. Equivalent to REG_DWORD\n" +" REG_DWORD_LITTLE_ENDIAN -- A 32-bit number in little-endian\n" +" format. Equivalent to REG_DWORD\n" " REG_DWORD_BIG_ENDIAN -- A 32-bit number in big-endian format.\n" " REG_EXPAND_SZ -- A null-terminated string that contains unexpanded\n" " references to environment variables (for example,\n" @@ -1479,7 +1480,8 @@ PyDoc_STRVAR(winreg_SetValueEx__doc__, " this termination automatically.\n" " REG_NONE -- No defined value type.\n" " REG_QWORD -- A 64-bit number.\n" -" REG_QWORD_LITTLE_ENDIAN -- A 64-bit number in little-endian format. Equivalent to REG_QWORD.\n" +" REG_QWORD_LITTLE_ENDIAN -- A 64-bit number in little-endian\n" +" format. Equivalent to REG_QWORD.\n" " REG_RESOURCE_LIST -- A device-driver resource list.\n" " REG_SZ -- A null-terminated string.\n" " value\n" @@ -1636,8 +1638,8 @@ PyDoc_STRVAR(winreg_DeleteTree__doc__, " key\n" " An already open key, or any one of the predefined HKEY_* constants.\n" " sub_key\n" -" A string that names the subkey to delete. If None, deletes all subkeys\n" -" and values of the specified key.\n" +" A string that names the subkey to delete. If None, deletes all\n" +" subkeys and values of the specified key.\n" "\n" "This function deletes a key and all its descendants. If sub_key is None,\n" "all subkeys and values of the specified key are deleted."); @@ -1836,4 +1838,4 @@ winreg_QueryReflectionKey(PyObject *module, PyObject *arg) #ifndef WINREG_QUERYREFLECTIONKEY_METHODDEF #define WINREG_QUERYREFLECTIONKEY_METHODDEF #endif /* !defined(WINREG_QUERYREFLECTIONKEY_METHODDEF) */ -/*[clinic end generated code: output=97295995db2c24e9 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=1d295f62e99a1d2d input=a9049054013a1b77]*/ diff --git a/PC/winreg.c b/PC/winreg.c index 26bcd259efd9879..96088e14144f46f 100644 --- a/PC/winreg.c +++ b/PC/winreg.c @@ -1809,7 +1809,8 @@ winreg.SetValueEx An integer that specifies the type of the data, one of: REG_BINARY -- Binary data in any form. REG_DWORD -- A 32-bit number. - REG_DWORD_LITTLE_ENDIAN -- A 32-bit number in little-endian format. Equivalent to REG_DWORD + REG_DWORD_LITTLE_ENDIAN -- A 32-bit number in little-endian + format. Equivalent to REG_DWORD REG_DWORD_BIG_ENDIAN -- A 32-bit number in big-endian format. REG_EXPAND_SZ -- A null-terminated string that contains unexpanded references to environment variables (for example, @@ -1820,7 +1821,8 @@ winreg.SetValueEx this termination automatically. REG_NONE -- No defined value type. REG_QWORD -- A 64-bit number. - REG_QWORD_LITTLE_ENDIAN -- A 64-bit number in little-endian format. Equivalent to REG_QWORD. + REG_QWORD_LITTLE_ENDIAN -- A 64-bit number in little-endian + format. Equivalent to REG_QWORD. REG_RESOURCE_LIST -- A device-driver resource list. REG_SZ -- A null-terminated string. value: object @@ -1843,7 +1845,7 @@ the configuration registry to help the registry perform efficiently. static PyObject * winreg_SetValueEx_impl(PyObject *module, HKEY key, const wchar_t *value_name, PyObject *reserved, DWORD type, PyObject *value) -/*[clinic end generated code: output=295db04deb456d9e input=900a9e3990bfb196]*/ +/*[clinic end generated code: output=295db04deb456d9e input=b585d77ff4afaf31]*/ { LONG rc; BYTE *data = NULL; @@ -1988,8 +1990,8 @@ winreg.DeleteTree key: HKEY An already open key, or any one of the predefined HKEY_* constants. sub_key: Py_UNICODE(accept={str, NoneType}) = None - A string that names the subkey to delete. If None, deletes all subkeys - and values of the specified key. + A string that names the subkey to delete. If None, deletes all + subkeys and values of the specified key. / Deletes the specified key and all its subkeys and values recursively. @@ -2000,7 +2002,7 @@ all subkeys and values of the specified key are deleted. static PyObject * winreg_DeleteTree_impl(PyObject *module, HKEY key, const wchar_t *sub_key) -/*[clinic end generated code: output=c34395ee59290501 input=419ef9bb8b06e4bf]*/ +/*[clinic end generated code: output=c34395ee59290501 input=bcddd25bfe6f040b]*/ { LONG rc; diff --git a/Python/_warnings.c b/Python/_warnings.c index 4f6de50efa14a8e..70c5287881f439d 100644 --- a/Python/_warnings.c +++ b/Python/_warnings.c @@ -1150,14 +1150,15 @@ warn as warnings_warn category: object = None The Warning category subclass. Defaults to UserWarning. stacklevel: Py_ssize_t = 1 - How far up the call stack to make this warning appear. A value of 2 for - example attributes the warning to the caller of the code calling warn(). + How far up the call stack to make this warning appear. A value of 2 + for example attributes the warning to the caller of the code calling + warn(). source: object = None If supplied, the destroyed object which emitted a ResourceWarning * skip_file_prefixes: object(type='PyTupleObject *', subclass_of='&PyTuple_Type') = NULL - An optional tuple of module filename prefixes indicating frames to skip - during stacklevel computations for stack frame attribution. + An optional tuple of module filename prefixes indicating frames to + skip during stacklevel computations for stack frame attribution. Issue a warning, or maybe ignore it or raise an exception. [clinic start generated code]*/ @@ -1166,7 +1167,7 @@ static PyObject * warnings_warn_impl(PyObject *module, PyObject *message, PyObject *category, Py_ssize_t stacklevel, PyObject *source, PyTupleObject *skip_file_prefixes) -/*[clinic end generated code: output=a68e0f6906c65f80 input=eb37c6a18bec4ea1]*/ +/*[clinic end generated code: output=a68e0f6906c65f80 input=cc690f3ad09042a8]*/ { category = get_category(message, category); if (category == NULL) diff --git a/Python/clinic/_warnings.c.h b/Python/clinic/_warnings.c.h index 8bda830ccb924eb..75990c506a9307f 100644 --- a/Python/clinic/_warnings.c.h +++ b/Python/clinic/_warnings.c.h @@ -55,13 +55,14 @@ PyDoc_STRVAR(warnings_warn__doc__, " category\n" " The Warning category subclass. Defaults to UserWarning.\n" " stacklevel\n" -" How far up the call stack to make this warning appear. A value of 2 for\n" -" example attributes the warning to the caller of the code calling warn().\n" +" How far up the call stack to make this warning appear. A value of 2\n" +" for example attributes the warning to the caller of the code calling\n" +" warn().\n" " source\n" " If supplied, the destroyed object which emitted a ResourceWarning\n" " skip_file_prefixes\n" -" An optional tuple of module filename prefixes indicating frames to skip\n" -" during stacklevel computations for stack frame attribution."); +" An optional tuple of module filename prefixes indicating frames to\n" +" skip during stacklevel computations for stack frame attribution."); #define WARNINGS_WARN_METHODDEF \ {"warn", _PyCFunction_CAST(warnings_warn), METH_FASTCALL|METH_KEYWORDS, warnings_warn__doc__}, @@ -284,4 +285,4 @@ warnings_filters_mutated_lock_held(PyObject *module, PyObject *Py_UNUSED(ignored { return warnings_filters_mutated_lock_held_impl(module); } -/*[clinic end generated code: output=610ed5764bf40bb5 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=2be7de582544b099 input=a9049054013a1b77]*/ diff --git a/Tools/clinic/libclinic/dsl_parser.py b/Tools/clinic/libclinic/dsl_parser.py index 4dcbc815cc6f25b..47467f80739c5f1 100644 --- a/Tools/clinic/libclinic/dsl_parser.py +++ b/Tools/clinic/libclinic/dsl_parser.py @@ -1568,12 +1568,27 @@ def format_docstring(self) -> str: # between it and the {parameters} we're about to add. lines.append('') + parameters_marker_count = len(f.docstring.split('{parameters}')) - 1 + if parameters_marker_count > 1: + fail('You may not specify {parameters} more than once in a docstring!') + + params = f.render_parameters + parameters = self.format_docstring_parameters(params) + + # The parameter descriptions are part of the docstring body, even + # though they are only substituted for the {parameters} marker below. + # linear_format() indents the substituted lines by the indentation of + # the marker line, so take that into account as well. + marker_indent = next((line.partition('{parameters}')[0] + for line in lines if '{parameters}' in line), '') + body = [line for line in lines[1:] if '{parameters}' not in line] + body += [marker_indent + line for line in parameters.splitlines()] + # Fail if the summary line is too long. # Warn if any of the body lines are too long. - # Existing violations are recorded in OVERLONG_{SUMMARY,BODY}. max_width = f.docstring_line_width summary_len = len(lines[0]) - max_body = max(map(len, lines[1:])) + max_body = max(map(len, body), default=0) if summary_len > max_width: if not self.permit_long_summary: fail(f"Summary line for {f.full_name!r} is too long!\n" @@ -1581,20 +1596,19 @@ def format_docstring(self) -> str: else: if self.permit_long_summary: warn("Remove the @permit_long_summary decorator from " - f"{f.full_name!r}!\n") + f"{f.full_name!r}!\n", + filename=self.clinic.filename) if max_body > max_width: if not self.permit_long_docstring_body: warn(f"Docstring lines for {f.full_name!r} are too long!\n" - f"Lines should be no longer than {max_width} characters.") + f"Lines should be no longer than {max_width} characters.", + filename=self.clinic.filename) else: if self.permit_long_docstring_body: warn("Remove the @permit_long_docstring_body decorator from " - f"{f.full_name!r}!\n") - - parameters_marker_count = len(f.docstring.split('{parameters}')) - 1 - if parameters_marker_count > 1: - fail('You may not specify {parameters} more than once in a docstring!') + f"{f.full_name!r}!\n", + filename=self.clinic.filename) # insert signature at front and params after the summary line if not parameters_marker_count: @@ -1602,8 +1616,6 @@ def format_docstring(self) -> str: lines.insert(0, '{signature}') # finalize docstring - params = f.render_parameters - parameters = self.format_docstring_parameters(params) signature = self.format_docstring_signature(f, params) docstring = "\n".join(lines) return libclinic.linear_format(docstring,