@colesbury: I copied the long comment from the private header file as the documentation. I already had doubts about mentioning details of the internal C API which are not exposed in the public C API yet. I will reorganize the "public" documentation to only leave documentation relevant to the few functions made public.

@scoder:

We're adding new functions here, so shouldn't we let them report errors? I don't think silent failures are what you'd want for a new API. Why not return -1 (without exception) in the case of failures for all three get-time functions? Then users can decide themselves whether they want to handle or ignore the error. Or do you consider 0 a safe error indicator?

Not being able to report errors isnot safe. The risk of error while reading time islow, whereas the cost of having to report errors to the caller while reading time ishigh. It makes code way more complicated.

There are some specific C extensions where we cannot even report errors, since the API doesn't let to report errors to the caller. One example if thePyThread_acquire_lock_timed() API. For example, one implementation uses:

_PyTime_tdeadline=_PyTime_Add(_PyTime_GetMonotonicClock(),timeout);_PyTime_AsTimespec_clamp(deadline,&abs_timeout);

It uses_PyTime_Add() and the_clamp function variant which clamp the result into [_PyTime_MIN; _PyTime_MAX] range, rather than raising an exception and report an error.

In existing code which doesn't use thePyTime API, do you know any code which actually check for errors? If yes, how are errors handled?

Since I designed and implemented PEP 418 in 2012, I paid a lot of attention to bug reports about "reading time". I only recall on bug report in Red Hat bug tracker of an application running in a sandbox and the sandbox blocked syscalls to read time. Well, it was more a sandbox configuration issue, than a bug in Python.

When I implemented PEP 418, I was scared of regressions, so I added a read the monotonic clock at Python startup: so Python was able to check for "read time" error at one place, and only one place. That's how I discovered the sandbox issue. Later, Iremoved these checks at startup. I decided that it's not worth it.

commit ae6cd7cfdab0599139002c526953d907696d9eefAuthor: Victor Stinner <vstinner@python.org>Date:   Mon Nov 16 16:08:05 2020 +0100    bpo-37205: time.time() cannot fail with fatal error (GH-23314)        time.time(), time.perf_counter() and time.monotonic() functions can    no longer fail with a Python fatal error, instead raise a regular    Python exception on failure.        Remove _PyTime_Init(): don't check system, monotonic and perf counter    clocks at startup anymore.        On error, _PyTime_GetSystemClock(), _PyTime_GetMonotonicClock() and    _PyTime_GetPerfCounter() now silently ignore the error and return 0.    They cannot fail with a Python fatal error anymore.        Add py_mach_timebase_info() and win_perf_counter_frequency()    sub-functions.

@colesbury@scoder@serhiy-storchaka: Please review the updated PR.

• I cleaned up the C API doc.
• I renamed the functions to use shorter names.
• I added dedicated tests to test_capi.test_time.
• I kept aliases to old names for this PR to make the PR shorter and easier to review. I will remove the private aliases in a follow-up PR once this once is merged.

A few suggestions about the documentation below.

@colesbury: Thanks, I applied your suggestions. Does the updated doc look better?

I have too many things on my plate. I prefer to close the PR for now.

I reopened my PR since#110850 issue is now marked as a release blocker issue. I rebased my PR on main.

I created a C API Working Group issue:capi-workgroup/decisions#8

I close this PR: the C API Working Group is against an API which cannot fail.

Instead,@encukou modified to PR as PRgh-115215 which can report errors.