@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 is not safe. The risk of error while reading time is low, whereas the cost of having to report errors to the caller while reading time is high. 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 the PyThread_acquire_lock_timed() API. For example, one implementation uses:

        _PyTime_t deadline = _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 the PyTime 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, I removed these checks at startup. I decided that it's not worth it.

commit ae6cd7cfdab0599139002c526953d907696d9eef
Author: 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 PR gh-115215 which can report errors.