ssl.RAND_status docs describe it as returning True/False; actually returns 1/0

[MojoVampire]

BPO	35114
Nosy	@tiran, @MojoVampire, @ZackerySpytz, @tirkarthi
PRs	bpo-35114: Make ssl.RAND_status() return a bool (GH-20063) #20063

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2021-04-23.16:08:16.336>
created_at = <Date 2018-10-30.13:40:16.997>
labels = ['expert-SSL', 'type-bug', '3.10', 'docs']
title = 'ssl.RAND_status docs describe it as returning True/False; actually returns 1/0'
updated_at = <Date 2021-04-23.16:08:16.335>
user = 'https://github.com/MojoVampire'

bugs.python.org fields:

activity = <Date 2021-04-23.16:08:16.335>
actor = 'christian.heimes'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-04-23.16:08:16.336>
closer = 'christian.heimes'
components = ['Documentation', 'SSL']
creation = <Date 2018-10-30.13:40:16.997>
creator = 'josh.r'
dependencies = []
files = []
hgrepos = []
issue_num = 35114
keywords = ['patch']
message_count = 3.0
messages = ['328917', '391702', '391703']
nosy_count = 5.0
nosy_names = ['christian.heimes', 'docs@python', 'josh.r', 'ZackerySpytz', 'xtreak']
pr_nums = ['20063']
priority = 'low'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue35114'
versions = ['Python 3.10']

[MojoVampire]

The ssl.RAND_status online docs say (with code format on True/False):

"Return True if the SSL pseudo-random number generator has been seeded with ‘enough’ randomness, and False otherwise."

This is incorrect; the function actually returns 1 or 0 (and the docstring agrees).

Fix can be one of:

1. Update docs to be less specific about the return type (use true/false, not True/False)
2. Update docs to match docstring (which specifically says 1/0, not True/False)
3. Update implementation and docstring to actually return True/False (replacing PyLong_FromLong with PyBool_FromLong and changing docstring to use True/False to match online docs)

#3 involves a small amount of code churn, but it also means we're not needlessly replicating a C API's use of int return values when the function is logically bool (there is no error status for the C API AFAICT, so it's not like returning int gains us anything on flexibility). bool would be mathematically equivalent to the original 1/0 return value in the rare cases someone uses it mathematically.

[tiran]

New changeset 7d37b86 by Zackery Spytz in branch 'master':
bpo-35114: Make ssl.RAND_status() return a bool (GH-20063)
7d37b86

[tiran]

Thanks Zackery!