Skip to content

gh-150285: Fix too long docstrings in the pyexpat module #150294

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

Open
serhiy-storchaka wants to merge 1 commit into
base: main
Choose a base branch
from
+90 −76
Open

gh-150285: Fix too long docstrings in the pyexpat module #150294

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
73 changes: 41 additions & 32 deletions Modules/clinic/pyexpat.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

93 changes: 49 additions & 44 deletions Modules/pyexpat.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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);
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand All @@ -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;
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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,
Expand Down
Loading