Skip to content

gh-116245: Document getentropy() use in os.urandom() - #162108

Open
kirtiagwl1595 wants to merge 1 commit into
python:mainfrom
kirtiagwl1595:gh-116245-urandom-getentropy
Open

kirtiagwl1595 wants to merge 1 commit into
python:mainfrom
kirtiagwl1595:gh-116245-urandom-getentropy

Conversation

@kirtiagwl1595

Copy link
Copy Markdown
Contributor

As Ronald Oussoren explained in the issue, os.urandom() uses getentropy() on macOS 10.12 and newer and on OpenBSD, but the docs mention only /dev/urandom for Unix-like systems; getentropy() appears only in a 3.5 versionchanged note. This change follows that diagnosis, not the issue title: CCRandomGenerateBytes is not used. The Unix paragraph now names getrandom() and getentropy(), and keeps the /dev/urandom fallback for all Unix-like systems, which matches pyurandom() in Python/bootstrap_hash.c.

This needs the skip news label (docs only).

I used Claude Code to research and draft this change; I reviewed every line.

Comment thread Doc/library/os.rst
Comment on lines +6469 to +6476
On other Unix-like systems, the C ``getrandom()`` or ``getentropy()``
function is used if it is available, for example ``getentropy()`` on OpenBSD
and on macOS 10.12 and newer.

On any Unix-like system, if none of these functions can be used, random
bytes are read from the ``/dev/urandom`` device. If the ``/dev/urandom``
device is not available or not readable, the :exc:`NotImplementedError`
exception is raised.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
On other Unix-like systems, the C ``getrandom()`` or ``getentropy()``
function is used if it is available, for example ``getentropy()`` on OpenBSD
and on macOS 10.12 and newer.
On any Unix-like system, if none of these functions can be used, random
bytes are read from the ``/dev/urandom`` device. If the ``/dev/urandom``
device is not available or not readable, the :exc:`NotImplementedError`
exception is raised.
On other Unix-like systems, the C ``getrandom()`` function is used if it is
available, otherwise the C ``getentropy()`` function.
If none of these functions can be used, random bytes are read from the
``/dev/urandom`` device. If the ``/dev/urandom`` device is not available or
not readable, the :exc:`NotImplementedError` exception is raised.

We're duplicating "Unix-like system" and we don't state the order in which we check the functions. Also, I don't think we need the OpenBSD/macOS implementation detail.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

2 participants