]> git.ipfire.org Git - thirdparty/Python/cpython.git/commitdiff
gh-150285: Fix too long docstrings in the pyexpat module (GH-150294)
authorSerhiy Storchaka <storchaka@gmail.com>
Sun, 24 May 2026 12:03:45 +0000 (15:03 +0300)
committerGitHub <noreply@github.com>
Sun, 24 May 2026 12:03:45 +0000 (15:03 +0300)
Modules/clinic/pyexpat.c.h
Modules/pyexpat.c

index ff2e28269dc927e4ee03299a552df873a3a00cef..1a07726d303ecad874501e71a48b83b3bf2d04d0 100644 (file)
@@ -218,8 +218,9 @@ PyDoc_STRVAR(pyexpat_xmlparser_GetInputContext__doc__,
 "\n"
 "Return the untranslated text of the input that caused the current event.\n"
 "\n"
-"If the event was generated by a large amount of text (such as a start tag\n"
-"for an element with many attributes), not all of the text may be available.");
+"If the event was generated by a large amount of text (such as\n"
+"a start tag for an element with many attributes), not all of the\n"
+"text may be available.");
 
 #define PYEXPAT_XMLPARSER_GETINPUTCONTEXT_METHODDEF    \
     {"GetInputContext", (PyCFunction)pyexpat_xmlparser_GetInputContext, METH_NOARGS, pyexpat_xmlparser_GetInputContext__doc__},
@@ -357,9 +358,10 @@ PyDoc_STRVAR(pyexpat_xmlparser_UseForeignDTD__doc__,
 "\n"
 "Allows the application to provide an artificial external subset if one is not specified as part of the document instance.\n"
 "\n"
-"This readily allows the use of a \'default\' document type controlled by the\n"
-"application, while still getting the advantage of providing document type\n"
-"information to the parser. \'flag\' defaults to True if not provided.");
+"This readily allows the use of a \'default\' document type controlled\n"
+"by the application, while still getting the advantage of providing\n"
+"document type information to the parser.  \'flag\' defaults to True if\n"
+"not provided.");
 
 #define PYEXPAT_XMLPARSER_USEFOREIGNDTD_METHODDEF    \
     {"UseForeignDTD", _PyCFunction_CAST(pyexpat_xmlparser_UseForeignDTD), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, pyexpat_xmlparser_UseForeignDTD__doc__},
@@ -417,14 +419,15 @@ PyDoc_STRVAR(pyexpat_xmlparser_SetBillionLaughsAttackProtectionActivationThresho
 "\n"
 "Sets the number of output bytes needed to activate protection against billion laughs attacks.\n"
 "\n"
-"The number of output bytes includes amplification from entity expansion\n"
-"and reading DTD files.\n"
+"The number of output bytes includes amplification from entity\n"
+"expansion and reading DTD files.\n"
 "\n"
-"Parser objects usually have a protection activation threshold of 8 MiB,\n"
-"but the actual default value depends on the underlying Expat library.\n"
+"Parser objects usually have a protection activation threshold of\n"
+"8 MiB, but the actual default value depends on the underlying Expat\n"
+"library.\n"
 "\n"
-"Activation thresholds below 4 MiB are known to break support for DITA 1.3\n"
-"payload and are hence not recommended.");
+"Activation thresholds below 4 MiB are known to break support for\n"
+"DITA 1.3 payload and are hence not recommended.");
 
 #define PYEXPAT_XMLPARSER_SETBILLIONLAUGHSATTACKPROTECTIONACTIVATIONTHRESHOLD_METHODDEF    \
     {"SetBillionLaughsAttackProtectionActivationThreshold", _PyCFunction_CAST(pyexpat_xmlparser_SetBillionLaughsAttackProtectionActivationThreshold), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, pyexpat_xmlparser_SetBillionLaughsAttackProtectionActivationThreshold__doc__},
@@ -479,18 +482,21 @@ PyDoc_STRVAR(pyexpat_xmlparser_SetBillionLaughsAttackProtectionMaximumAmplificat
 "\n"
 "Sets the maximum tolerated amplification factor for protection against billion laughs attacks.\n"
 "\n"
-"The amplification factor is calculated as \"(direct + indirect) / direct\"\n"
-"while parsing, where \"direct\" is the number of bytes read from the primary\n"
-"document in parsing and \"indirect\" is the number of bytes added by expanding\n"
-"entities and reading external DTD files, combined.\n"
+"The amplification factor is calculated as \"(direct + indirect) /\n"
+"direct\" while parsing, where \"direct\" is the number of bytes read\n"
+"from the primary document in parsing and \"indirect\" is the number of\n"
+"bytes added by expanding entities and reading external DTD files,\n"
+"combined.\n"
 "\n"
-"The \'max_factor\' value must be a non-NaN floating point value greater than\n"
-"or equal to 1.0. Amplification factors greater than 30,000 can be observed\n"
-"in the middle of parsing even with benign files in practice. In particular,\n"
-"the activation threshold should be carefully chosen to avoid false positives.\n"
+"The \'max_factor\' value must be a non-NaN floating point value\n"
+"greater than or equal to 1.0.  Amplification factors greater than\n"
+"30,000 can be observed in the middle of parsing even with benign\n"
+"files in practice.  In particular, the activation threshold should\n"
+"be carefully chosen to avoid false positives.\n"
 "\n"
 "Parser objects usually have a maximum amplification factor of 100,\n"
-"but the actual default value depends on the underlying Expat library.");
+"but the actual default value depends on the underlying Expat\n"
+"library.");
 
 #define PYEXPAT_XMLPARSER_SETBILLIONLAUGHSATTACKPROTECTIONMAXIMUMAMPLIFICATION_METHODDEF    \
     {"SetBillionLaughsAttackProtectionMaximumAmplification", _PyCFunction_CAST(pyexpat_xmlparser_SetBillionLaughsAttackProtectionMaximumAmplification), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, pyexpat_xmlparser_SetBillionLaughsAttackProtectionMaximumAmplification__doc__},
@@ -551,8 +557,9 @@ PyDoc_STRVAR(pyexpat_xmlparser_SetAllocTrackerActivationThreshold__doc__,
 "\n"
 "Sets the number of allocated bytes of dynamic memory needed to activate protection against disproportionate use of RAM.\n"
 "\n"
-"Parser objects usually have an allocation activation threshold of 64 MiB,\n"
-"but the actual default value depends on the underlying Expat library.");
+"Parser objects usually have an allocation activation threshold of\n"
+"64 MiB, but the actual default value depends on the underlying Expat\n"
+"library.");
 
 #define PYEXPAT_XMLPARSER_SETALLOCTRACKERACTIVATIONTHRESHOLD_METHODDEF    \
     {"SetAllocTrackerActivationThreshold", _PyCFunction_CAST(pyexpat_xmlparser_SetAllocTrackerActivationThreshold), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, pyexpat_xmlparser_SetAllocTrackerActivationThreshold__doc__},
@@ -606,18 +613,20 @@ PyDoc_STRVAR(pyexpat_xmlparser_SetAllocTrackerMaximumAmplification__doc__,
 "\n"
 "Sets the maximum amplification factor between direct input and bytes of dynamic memory allocated.\n"
 "\n"
-"The amplification factor is calculated as \"allocated / direct\" while parsing,\n"
-"where \"direct\" is the number of bytes read from the primary document in parsing\n"
-"and \"allocated\" is the number of bytes of dynamic memory allocated in the parser\n"
-"hierarchy.\n"
+"The amplification factor is calculated as \"allocated / direct\" while\n"
+"parsing, where \"direct\" is the number of bytes read from the primary\n"
+"document in parsing and \"allocated\" is the number of bytes of\n"
+"dynamic memory allocated in the parser hierarchy.\n"
 "\n"
-"The \'max_factor\' value must be a non-NaN floating point value greater than\n"
-"or equal to 1.0. Amplification factors greater than 100.0 can be observed\n"
-"near the start of parsing even with benign files in practice. In particular,\n"
-"the activation threshold should be carefully chosen to avoid false positives.\n"
+"The \'max_factor\' value must be a non-NaN floating point value\n"
+"greater than or equal to 1.0.  Amplification factors greater than\n"
+"100.0 can be observed near the start of parsing even with benign\n"
+"files in practice.  In particular, the activation threshold should\n"
+"be carefully chosen to avoid false positives.\n"
 "\n"
 "Parser objects usually have a maximum amplification factor of 100,\n"
-"but the actual default value depends on the underlying Expat library.");
+"but the actual default value depends on the underlying Expat\n"
+"library.");
 
 #define PYEXPAT_XMLPARSER_SETALLOCTRACKERMAXIMUMAMPLIFICATION_METHODDEF    \
     {"SetAllocTrackerMaximumAmplification", _PyCFunction_CAST(pyexpat_xmlparser_SetAllocTrackerMaximumAmplification), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, pyexpat_xmlparser_SetAllocTrackerMaximumAmplification__doc__},
@@ -830,4 +839,4 @@ exit:
 #ifndef PYEXPAT_XMLPARSER_SETALLOCTRACKERMAXIMUMAMPLIFICATION_METHODDEF
     #define PYEXPAT_XMLPARSER_SETALLOCTRACKERMAXIMUMAMPLIFICATION_METHODDEF
 #endif /* !defined(PYEXPAT_XMLPARSER_SETALLOCTRACKERMAXIMUMAMPLIFICATION_METHODDEF) */
-/*[clinic end generated code: output=81101a16a409daf6 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=270a0bfe3300e8a1 input=a9049054013a1b77]*/
index 64314e5dff93a108b93b1943843e209c2f92123a..d204b6f27d99082df940f5e4efbdefcded26a765 100644 (file)
@@ -830,6 +830,7 @@ get_parse_result(pyexpat_state *state, xmlparseobject *self, int rv)
 #define MAX_CHUNK_SIZE (1 << 20)
 
 /*[clinic input]
+@permit_long_summary
 pyexpat.xmlparser.SetReparseDeferralEnabled
 
     enabled: bool
@@ -841,7 +842,7 @@ Enable/Disable reparse deferral; enabled by default with Expat >=2.6.0.
 static PyObject *
 pyexpat_xmlparser_SetReparseDeferralEnabled_impl(xmlparseobject *self,
                                                  int enabled)
-/*[clinic end generated code: output=5ec539e3b63c8c49 input=021eb9e0bafc32c5]*/
+/*[clinic end generated code: output=5ec539e3b63c8c49 input=6d3743500dcee799]*/
 {
 #if XML_COMBINED_VERSION >= 20600
     XML_SetReparseDeferralEnabled(self->itself, enabled ? XML_TRUE : XML_FALSE);
@@ -1053,18 +1054,19 @@ pyexpat_xmlparser_GetBase_impl(xmlparseobject *self)
 }
 
 /*[clinic input]
-@permit_long_docstring_body
+@permit_long_summary
 pyexpat.xmlparser.GetInputContext
 
 Return the untranslated text of the input that caused the current event.
 
-If the event was generated by a large amount of text (such as a start tag
-for an element with many attributes), not all of the text may be available.
+If the event was generated by a large amount of text (such as
+a start tag for an element with many attributes), not all of the
+text may be available.
 [clinic start generated code]*/
 
 static PyObject *
 pyexpat_xmlparser_GetInputContext_impl(xmlparseobject *self)
-/*[clinic end generated code: output=a88026d683fc22cc input=925cea010fdfa682]*/
+/*[clinic end generated code: output=a88026d683fc22cc input=a672f48f09bb73d2]*/
 {
     if (self->in_callback) {
         int offset, size;
@@ -1191,7 +1193,6 @@ pyexpat_xmlparser_SetParamEntityParsing_impl(xmlparseobject *self, int flag)
 #if XML_COMBINED_VERSION >= 19505
 /*[clinic input]
 @permit_long_summary
-@permit_long_docstring_body
 pyexpat.xmlparser.UseForeignDTD
 
     cls: defining_class
@@ -1200,15 +1201,16 @@ pyexpat.xmlparser.UseForeignDTD
 
 Allows the application to provide an artificial external subset if one is not specified as part of the document instance.
 
-This readily allows the use of a 'default' document type controlled by the
-application, while still getting the advantage of providing document type
-information to the parser. 'flag' defaults to True if not provided.
+This readily allows the use of a 'default' document type controlled
+by the application, while still getting the advantage of providing
+document type information to the parser.  'flag' defaults to True if
+not provided.
 [clinic start generated code]*/
 
 static PyObject *
 pyexpat_xmlparser_UseForeignDTD_impl(xmlparseobject *self, PyTypeObject *cls,
                                      int flag)
-/*[clinic end generated code: output=d7d98252bd25a20f input=c2264845d8c0029c]*/
+/*[clinic end generated code: output=d7d98252bd25a20f input=2920baa5bf24714d]*/
 {
     pyexpat_state *state = PyType_GetModuleState(cls);
     enum XML_Error rc;
@@ -1268,7 +1270,6 @@ set_maximum_amplification(xmlparseobject *self,
 #if XML_COMBINED_VERSION >= 20400
 /*[clinic input]
 @permit_long_summary
-@permit_long_docstring_body
 pyexpat.xmlparser.SetBillionLaughsAttackProtectionActivationThreshold
 
     cls: defining_class
@@ -1277,21 +1278,22 @@ pyexpat.xmlparser.SetBillionLaughsAttackProtectionActivationThreshold
 
 Sets the number of output bytes needed to activate protection against billion laughs attacks.
 
-The number of output bytes includes amplification from entity expansion
-and reading DTD files.
+The number of output bytes includes amplification from entity
+expansion and reading DTD files.
 
-Parser objects usually have a protection activation threshold of 8 MiB,
-but the actual default value depends on the underlying Expat library.
+Parser objects usually have a protection activation threshold of
+8 MiB, but the actual default value depends on the underlying Expat
+library.
 
-Activation thresholds below 4 MiB are known to break support for DITA 1.3
-payload and are hence not recommended.
+Activation thresholds below 4 MiB are known to break support for
+DITA 1.3 payload and are hence not recommended.
 [clinic start generated code]*/
 
 static PyObject *
 pyexpat_xmlparser_SetBillionLaughsAttackProtectionActivationThreshold_impl(xmlparseobject *self,
                                                                            PyTypeObject *cls,
                                                                            unsigned long long threshold)
-/*[clinic end generated code: output=0c082342f1c78114 input=fa2f91f26b62a42a]*/
+/*[clinic end generated code: output=0c082342f1c78114 input=8d84b0e3a873cdba]*/
 {
     return set_activation_threshold(
         self, cls, threshold,
@@ -1303,7 +1305,6 @@ pyexpat_xmlparser_SetBillionLaughsAttackProtectionActivationThreshold_impl(xmlpa
 #if XML_COMBINED_VERSION >= 20400
 /*[clinic input]
 @permit_long_summary
-@permit_long_docstring_body
 pyexpat.xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification
 
     cls: defining_class
@@ -1312,25 +1313,28 @@ pyexpat.xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification
 
 Sets the maximum tolerated amplification factor for protection against billion laughs attacks.
 
-The amplification factor is calculated as "(direct + indirect) / direct"
-while parsing, where "direct" is the number of bytes read from the primary
-document in parsing and "indirect" is the number of bytes added by expanding
-entities and reading external DTD files, combined.
+The amplification factor is calculated as "(direct + indirect) /
+direct" while parsing, where "direct" is the number of bytes read
+from the primary document in parsing and "indirect" is the number of
+bytes added by expanding entities and reading external DTD files,
+combined.
 
-The 'max_factor' value must be a non-NaN floating point value greater than
-or equal to 1.0. Amplification factors greater than 30,000 can be observed
-in the middle of parsing even with benign files in practice. In particular,
-the activation threshold should be carefully chosen to avoid false positives.
+The 'max_factor' value must be a non-NaN floating point value
+greater than or equal to 1.0.  Amplification factors greater than
+30,000 can be observed in the middle of parsing even with benign
+files in practice.  In particular, the activation threshold should
+be carefully chosen to avoid false positives.
 
 Parser objects usually have a maximum amplification factor of 100,
-but the actual default value depends on the underlying Expat library.
+but the actual default value depends on the underlying Expat
+library.
 [clinic start generated code]*/
 
 static PyObject *
 pyexpat_xmlparser_SetBillionLaughsAttackProtectionMaximumAmplification_impl(xmlparseobject *self,
                                                                             PyTypeObject *cls,
                                                                             float max_factor)
-/*[clinic end generated code: output=c590439eadf463fa input=cc1e97c1fd2bd950]*/
+/*[clinic end generated code: output=c590439eadf463fa input=d0f11971c5b9e98b]*/
 {
     return set_maximum_amplification(
         self, cls, max_factor,
@@ -1342,7 +1346,6 @@ pyexpat_xmlparser_SetBillionLaughsAttackProtectionMaximumAmplification_impl(xmlp
 #if XML_COMBINED_VERSION >= 20702
 /*[clinic input]
 @permit_long_summary
-@permit_long_docstring_body
 pyexpat.xmlparser.SetAllocTrackerActivationThreshold
 
     cls: defining_class
@@ -1351,15 +1354,16 @@ pyexpat.xmlparser.SetAllocTrackerActivationThreshold
 
 Sets the number of allocated bytes of dynamic memory needed to activate protection against disproportionate use of RAM.
 
-Parser objects usually have an allocation activation threshold of 64 MiB,
-but the actual default value depends on the underlying Expat library.
+Parser objects usually have an allocation activation threshold of
+64 MiB, but the actual default value depends on the underlying Expat
+library.
 [clinic start generated code]*/
 
 static PyObject *
 pyexpat_xmlparser_SetAllocTrackerActivationThreshold_impl(xmlparseobject *self,
                                                           PyTypeObject *cls,
                                                           unsigned long long threshold)
-/*[clinic end generated code: output=bed7e93207ba08c5 input=b7a7a3e3d054286a]*/
+/*[clinic end generated code: output=bed7e93207ba08c5 input=4728360b545de87a]*/
 {
     return set_activation_threshold(
         self, cls, threshold,
@@ -1371,7 +1375,6 @@ pyexpat_xmlparser_SetAllocTrackerActivationThreshold_impl(xmlparseobject *self,
 #if XML_COMBINED_VERSION >= 20702
 /*[clinic input]
 @permit_long_summary
-@permit_long_docstring_body
 pyexpat.xmlparser.SetAllocTrackerMaximumAmplification
 
     cls: defining_class
@@ -1380,25 +1383,27 @@ pyexpat.xmlparser.SetAllocTrackerMaximumAmplification
 
 Sets the maximum amplification factor between direct input and bytes of dynamic memory allocated.
 
-The amplification factor is calculated as "allocated / direct" while parsing,
-where "direct" is the number of bytes read from the primary document in parsing
-and "allocated" is the number of bytes of dynamic memory allocated in the parser
-hierarchy.
+The amplification factor is calculated as "allocated / direct" while
+parsing, where "direct" is the number of bytes read from the primary
+document in parsing and "allocated" is the number of bytes of
+dynamic memory allocated in the parser hierarchy.
 
-The 'max_factor' value must be a non-NaN floating point value greater than
-or equal to 1.0. Amplification factors greater than 100.0 can be observed
-near the start of parsing even with benign files in practice. In particular,
-the activation threshold should be carefully chosen to avoid false positives.
+The 'max_factor' value must be a non-NaN floating point value
+greater than or equal to 1.0.  Amplification factors greater than
+100.0 can be observed near the start of parsing even with benign
+files in practice.  In particular, the activation threshold should
+be carefully chosen to avoid false positives.
 
 Parser objects usually have a maximum amplification factor of 100,
-but the actual default value depends on the underlying Expat library.
+but the actual default value depends on the underlying Expat
+library.
 [clinic start generated code]*/
 
 static PyObject *
 pyexpat_xmlparser_SetAllocTrackerMaximumAmplification_impl(xmlparseobject *self,
                                                            PyTypeObject *cls,
                                                            float max_factor)
-/*[clinic end generated code: output=6e44bd48c9b112a0 input=c6af7ccb76ae5c6b]*/
+/*[clinic end generated code: output=6e44bd48c9b112a0 input=dd23ea3ef2069b69]*/
 {
     return set_maximum_amplification(
         self, cls, max_factor,