@@ -622,6 +622,13 @@ class`. float also has the following additional methods.
622
622
:exc: `OverflowError ` on infinities and a :exc: `ValueError ` on
623
623
NaNs.
624
624
625
+ .. note ::
626
+
627
+ The values returned by ``as_integer_ratio() `` can be huge. Attempts
628
+ to render such integers into decimal strings may bump into the
629
+ :ref: `integer string conversion length limitation
630
+ <int_max_str_digits>`.
631
+
625
632
.. method :: float.is_integer()
626
633
627
634
Return ``True `` if the float instance is finite with integral
@@ -5456,6 +5463,165 @@ types, where they are relevant. Some of these are not reported by the
5456
5463
[<class 'bool'>]
5457
5464
5458
5465
5466
+ .. _int_max_str_digits :
5467
+
5468
+ Integer string conversion length limitation
5469
+ ===========================================
5470
+
5471
+ CPython has a global limit for converting between :class: `int ` and :class: `str `
5472
+ to mitigate denial of service attacks. This limit *only * applies to decimal or
5473
+ other non-power-of-two number bases. Hexadecimal, octal, and binary conversions
5474
+ are unlimited. The limit can be configured.
5475
+
5476
+ The :class: `int ` type in CPython is an abitrary length number stored in binary
5477
+ form (commonly known as a "bignum"). There exists no algorithm that can convert
5478
+ a string to a binary integer or a binary integer to a string in linear time,
5479
+ *unless * the base is a power of 2. Even the best known algorithms for base 10
5480
+ have sub-quadratic complexity. Converting a large value such as ``int('1' *
5481
+ 500_000) `` can take over a second on a fast CPU.
5482
+
5483
+ Limiting conversion size offers a practical way to avoid `CVE-2020-10735
5484
+ <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735> `_.
5485
+
5486
+ The limit is applied to the number of digit characters in the input or output
5487
+ string when a non-linear conversion algorithm would be involved. Underscores
5488
+ and the sign are not counted towards the limit.
5489
+
5490
+ When an operation would exceed the limit, a :exc: `ValueError ` is raised:
5491
+
5492
+ .. doctest ::
5493
+
5494
+ >>> import sys
5495
+ >>> sys.set_int_max_str_digits(4300 ) # Illustrative, this is the default.
5496
+ >>> _ = int (' 2' * 5432 )
5497
+ Traceback (most recent call last):
5498
+ ...
5499
+ ValueError: Exceeds the limit (4300) for integer string conversion: value has 5432 digits.
5500
+ >>> i = int (' 2' * 4300 )
5501
+ >>> len (str (i))
5502
+ 4300
5503
+ >>> i_squared = i* i
5504
+ >>> len (str (i_squared))
5505
+ Traceback (most recent call last):
5506
+ ...
5507
+ ValueError: Exceeds the limit (4300) for integer string conversion: value has 8599 digits.
5508
+ >>> len (hex (i_squared))
5509
+ 7144
5510
+ >>> assert int (hex (i_squared), base = 16 ) == i* i # Hexadecimal is unlimited.
5511
+
5512
+ The default limit is 4300 digits as provided in
5513
+ :data: `sys.int_info.default_max_str_digits <sys.int_info> `.
5514
+ The lowest limit that can be configured is 640 digits as provided in
5515
+ :data: `sys.int_info.str_digits_check_threshold <sys.int_info> `.
5516
+
5517
+ Verification:
5518
+
5519
+ .. doctest ::
5520
+
5521
+ >>> import sys
5522
+ >>> assert sys.int_info.default_max_str_digits == 4300 , sys.int_info
5523
+ >>> assert sys.int_info.str_digits_check_threshold == 640 , sys.int_info
5524
+ >>> msg = int (' 578966293710682886880994035146873798396722250538762761564'
5525
+ ... ' 9252925514383915483333812743580549779436104706260696366600'
5526
+ ... ' 571186405732' ).to_bytes(53 , ' big' )
5527
+ ...
5528
+
5529
+ .. versionadded :: 3.11
5530
+
5531
+ Affected APIs
5532
+ -------------
5533
+
5534
+ The limition only applies to potentially slow conversions between :class: `int `
5535
+ and :class: `str ` or :class: `bytes `:
5536
+
5537
+ * ``int(string) `` with default base 10.
5538
+ * ``int(string, base) `` for all bases that are not a power of 2.
5539
+ * ``str(integer) ``.
5540
+ * ``repr(integer) ``
5541
+ * any other string conversion to base 10, for example ``f"{integer}" ``,
5542
+ ``"{}".format(integer) ``, or ``b"%d" % integer ``.
5543
+
5544
+ The limitations do not apply to functions with a linear algorithm:
5545
+
5546
+ * ``int(string, base) `` with base 2, 4, 8, 16, or 32.
5547
+ * :func: `int.from_bytes ` and :func: `int.to_bytes `.
5548
+ * :func: `hex `, :func: `oct `, :func: `bin `.
5549
+ * :ref: `formatspec ` for hex, octal, and binary numbers.
5550
+ * :class: `str ` to :class: `float `.
5551
+ * :class: `str ` to :class: `decimal.Decimal `.
5552
+
5553
+ Configuring the limit
5554
+ ---------------------
5555
+
5556
+ Before Python starts up you can use an environment variable or an interpreter
5557
+ command line flag to configure the limit:
5558
+
5559
+ * :envvar: `PYTHONINTMAXSTRDIGITS `, e.g.
5560
+ ``PYTHONINTMAXSTRDIGITS=640 python3 `` to set the limit to 640 or
5561
+ ``PYTHONINTMAXSTRDIGITS=0 python3 `` to disable the limitation.
5562
+ * :option: `-X int_max_str_digits <-X> `, e.g.
5563
+ ``python3 -X int_max_str_digits=640 ``
5564
+ * :data: `sys.flags.int_max_str_digits ` contains the value of
5565
+ :envvar: `PYTHONINTMAXSTRDIGITS ` or :option: `-X int_max_str_digits <-X> `.
5566
+ If both the env var and the ``-X `` option are set, the ``-X `` option takes
5567
+ precedence. A value of *-1 * indicates that both were unset, thus a value of
5568
+ :data: `sys.int_info.default_max_str_digits ` was used during initilization.
5569
+
5570
+ From code, you can inspect the current limit and set a new one using these
5571
+ :mod: `sys ` APIs:
5572
+
5573
+ * :func: `sys.get_int_max_str_digits ` and :func: `sys.set_int_max_str_digits ` are
5574
+ a getter and setter for the interpreter-wide limit. Subinterpreters have
5575
+ their own limit.
5576
+
5577
+ Information about the default and minimum can be found in :attr: `sys.int_info `:
5578
+
5579
+ * :data: `sys.int_info.default_max_str_digits <sys.int_info> ` is the compiled-in
5580
+ default limit.
5581
+ * :data: `sys.int_info.str_digits_check_threshold <sys.int_info> ` is the lowest
5582
+ accepted value for the limit (other than 0 which disables it).
5583
+
5584
+ .. versionadded :: 3.11
5585
+
5586
+ .. caution ::
5587
+
5588
+ Setting a low limit *can * lead to problems. While rare, code exists that
5589
+ contains integer constants in decimal in their source that exceed the
5590
+ minimum threshold. A consequence of setting the limit is that Python source
5591
+ code containing decimal integer literals longer than the limit will
5592
+ encounter an error during parsing, usually at startup time or import time or
5593
+ even at installation time - anytime an up to date ``.pyc `` does not already
5594
+ exist for the code. A workaround for source that contains such large
5595
+ constants is to convert them to ``0x `` hexadecimal form as it has no limit.
5596
+
5597
+ Test your application thoroughly if you use a low limit. Ensure your tests
5598
+ run with the limit set early via the environment or flag so that it applies
5599
+ during startup and even during any installation step that may invoke Python
5600
+ to precompile ``.py `` sources to ``.pyc `` files.
5601
+
5602
+ Recommended configuration
5603
+ -------------------------
5604
+
5605
+ The default :data: `sys.int_info.default_max_str_digits ` is expected to be
5606
+ reasonable for most applications. If your application requires a different
5607
+ limit, set it from your main entry point using Python version agnostic code as
5608
+ these APIs were added in security patch releases in versions before 3.11.
5609
+
5610
+ Example::
5611
+
5612
+ >>> import sys
5613
+ >>> if hasattr(sys, "set_int_max_str_digits"):
5614
+ ... upper_bound = 68000
5615
+ ... lower_bound = 4004
5616
+ ... current_limit = sys.get_int_max_str_digits()
5617
+ ... if current_limit == 0 or current_limit > upper_bound:
5618
+ ... sys.set_int_max_str_digits(upper_bound)
5619
+ ... elif current_limit < lower_bound:
5620
+ ... sys.set_int_max_str_digits(lower_bound)
5621
+
5622
+ If you need to disable it entirely, set it to ``0 ``.
5623
+
5624
+
5459
5625
.. rubric :: Footnotes
5460
5626
5461
5627
.. [1 ] Additional information on these special methods may be found in the Python
0 commit comments