AFAICT, PyOS_InputHook() isn't described anywhere in
the docs.  Even the .h files don't contain comments
explaining it.

The only mention I can find is in Misc/HISTORY:
    When the interpreter shell is invoked interactively, it attempts
    to import the readline module; when this fails, the default input
    mechanism is used.  The hook variables are PyOS_InputHook and
    PyOS_ReadlineFunctionPointer.

A.B, I believe you have looked at other areas of missing C-API docs. What do you think of this one? Is it still missing?

Here's a proposed patch to the c-api manual that describes these two pointers.  I put them in the 'very high-level API' section. Maybe they belong in the Operating System Utilities section instead, but I think they're intertwined with the interpreter loop and therefore belong in the 'very high-level' section.

I am not a C-api user, but the entries are pretty clear to me and seem ready to apply. The usage examples are a nice touch. OS Utilites is not where I would expect interpreter loop hooks, so I think the current location is better.

One question about the patch: how to give the prototype expected for the function?  I currently have it as:

char *(*PyOS_ReadlineFunctionPointer)(FILE *stdin, FILE *stdout, char *prompt)

Would it be better with a trivial function name, as in:

char *func(FILE *stdin, FILE *stdout, char *prompt)

Can one of you three answer Kuchling's question about formatting a data entry that consists of a function pointer with function signature?

New changeset 672614d809a1 by Andrew Kuchling in branch 'default':
#1554133: Document PyOS_InputHook, PyOS_ReadlineFunctionPointer
http://hg.python.org/cpython/rev/672614d809a1