Reduce user friction: Improve docs on how to work around our integer to/from decimal str length limit

[gpshead]

Based on this discussion comment: https://discuss.python.org/t/int-str-conversions-broken-in-latest-python-bugfix-releases/18889/17

But one group of users I would like to bring up is users practicing number theory in Python using only the Python language and the standard library, not advanced third party libraries like sympy.

Because of the unbounded nature of Python integers and the very easy syntax to learn it has historically been a very low barrier to entry for such users. As this is now a new barrier it would be nice if in the release notes it very clearly stated how to disable this in the easiest possible way for such users, e.g. sys.set_int_max_str_digits(0).

Currently it took me ~15 paragraphs of reading from the release notes to the documentation, to subtopics in the documentation, to correlating the information with sys.int_info.str_digits_check_threshold to sys.set_int_max_str_digits. To me this seems like a much bigger barrier to entry than this group of users has ever faced before.

We need to call this out better in whatever places are most meaningful to our users who may otherwise get lost or frustrated.

I fully expect that a stackoverflow python question regarding ValueError: Exceeds the limit (4300) for integer string conversion will wind up restating and linking to the most accessible docs about this, so why not have those docs be our own?

I wished I had something to link to from a URL in the exception error message itself, but did not do that when polishing up the change as we've never done such a thing before in CPython that I'm aware of. URLs in standard exception messages opens a can of works about long term URL stability requirements, a desire for them to be short, and a PSF managed canonical URL shortener that could be used for that purpose to avoid stale links from older versions as our web presence evolves.

[gpshead]

It would be nice if the error message directly mentioned the sys.set_int_max_str_digits function as a way to increase the limit.

from sympy/sympy#24033 (comment) is also a possibility.

[mdboom]

I wished I had something to link to from a URL in the exception error message itself, but did not do that when polishing up the change as we've never done such a thing before in CPython that I'm aware of. URLs in standard exception messages opens a can of works about long term URL stability requirements, a desire for them to be short, and a PSF managed canonical URL shortener that could be used for that purpose to avoid stale links from older versions as our web presence evolves.

I agree with these points, but there is some prior art of putting URLs in exception messages. (I know this only because I was just hacking on this part of the code).

[davidism]

Instead of a URL, you could say something like "See the docs about 'integer safety' for more information." As long as you keep that phrase in the docs in a searchable format, it should be easy enough to find from the error. I also try to put the exact error message into the docs that someone might copy and paste in Google, so that the docs are a close or exact match for the phrase.

You might also look into how SQLAlchemy has implemented links, I think they use a short/redirect like you've described.

[eyaler]

sys.set_int_max_str_digits(0) will raise on pre-patch versions. maybe:

import sys
try:
  sys.set_int_max_str_digits(0)
except AttributeError:
  pass