Document secrets.DEFAULT_ENTROPY as an opaque value

[viccie30]

Documentation

A previous issue to document secrets.DEFAULT_ENTROPY (#78134) was closed as completed in 2020, but it is not documented in the current version of the documentation. I think it is useful to document it, because it allows requesting a random value with at least as much entropy as Python recommends by calling max(<CURRENT MINIMUM VALUE>, secrets.DEFAULT_ENTROPY).

Linked PRs

• gh-143700: Document secrets.DEFAULT_ENTROPY #144447
• gh-143700: document secrets.DEFAULT_ENTROPY as an opaque value #144568
• [3.14] gh-143700: document secrets.DEFAULT_ENTROPY as an opaque value (GH-144568) #144579
• [3.13] gh-143700: document secrets.DEFAULT_ENTROPY as an opaque value (GH-144568) #144580

[picnixz]

There is another way to actually obtain the default entropy: call token_bytes() and take the length of the result. Now, there is a reason why I could decide not to document it. For instance, one could say that we choose the reasonable number of bytes. We don't really want users to do secrets.DEFAULT_ENTROPY = 1 and then be surprised that it's no more reasonable (we don't want it to be a writable constant but unfortunately we can't ensure that at runtime).

If we were to document this, we would also need to change its value every time we change it (though I think we can safely assume that 32 bytes if ok for now). So, we should also say that only the constant name is public but not the value and that users should not change it.

[Alisa211]

Thanks for the detailed explanation! That makes sense.
Given the design considerations, I’ll look for another documentation issue to start with.