Pretty sure you can't actually get rid of READONLY; it's part of the public API. Adding PY_READONLY to match PY_READWRITE is fine, but unlike WRITE_RESTRICTED/PY_WRITE_RESTRICTED (which isn't used at all in Py3,  has been non-functional since 2.3, and caused compilation errors on Visual Studio; more details on #36355), READONLY is commonly used by third party C extensions, doesn't have any known conflicts with compiler headers, and can't be removed.

Go ahead and add PY_READONLY, and change the documentation to prefer it, but:

#define READONLY 1

needs to stick around in the header indefinitely.