I don't like that the same note is repeated four times. Maybe we can split the functions and constants in two separate sections and place this note in the constants section once.

Thank you. I thought that it wasn't DRY when I was changing it but didn't know about moving things around. I step back and look at the overall layout.

Please remove "and data items" from the introductory sentence above.

Thank you. I had originally removed it, but then put it back in because I left some of the new data constants (starting with time.CLOCK_HIGHRES.) in that section. I didn't know if I should move the newer data items to the bottom with the deprecated ones or not. Maybe I should change the one on the bottom to be 'Deprecated data items:'?

Please note that the time module also defines a few constants starting with CLOCK_. Their descriptions should also go to the "Constants" section.

    CLOCK_MONOTONIC = 6
    CLOCK_MONOTONIC_RAW = 4
    CLOCK_PROCESS_CPUTIME_ID = 12
    CLOCK_REALTIME = 0
    CLOCK_THREAD_CPUTIME_ID = 16

You may also mention here that these constants are reset when time.tzset() is called. Maybe add "or the last time tzset() is called" after "at module load time".

Indentation should be the same level as others since the note is talking about altzone, daylight, timezone and tzname constants, not just tzname.

Changed.

We also need to document which functions of the time modules accept these constants.

I added one comment right under the constants heading. It seemed that all the constants would apply to clock_getres and clock_getttime, so hopefully this is appropriate.

Good point. How about removing clock_settime() from the paragraph below and add a note to CLOCK_REALTIME documentation that says this constant can only be passed to time.clock_settime()?

I've added a note to CLOCK_REALTIME.

I would suggest adding a link of this section to appropriate members of the time module. For example, see https://docs.python.org/3/library/time.html#time.clock_gettime -- I would add something like

See :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.

to the time.clock_gettime() documentation.

My wording is probably terrible (it's 3 a.m. here and my brain doesn't work well now), but I think you get the idea :)

And don't forget to create a link for the section:

.. _time-clock-id-constants:

Clock ID Constants
------------------

@berkerpeksag Thank you for all your suggestions. I added this reference to time.clock_gettime(), time.clock_getres(), and time.clock_settime(). It seems that settime only works for CLOCK_REALTIME though, so maybe it shouldn't link to the whole section? Also, I did not add any references in time.monotonic(), time.perf_counter(), or time.process_time(), but those seem to be shortcuts to time.clock_gettime()?

It seems that settime only works for CLOCK_REALTIME though, so maybe it shouldn't link to the whole section?

Good catch. I'd keep it in the same section, but add something like ":data:`CLOCK_REALTIME` is the only acceptable constant for *clk_id*." to time.clock_settime() documentation. My wording is probably a bit bad, feel free to tweak it :)

Also, I did not add any references in time.monotonic(), time.perf_counter(), or time.process_time(), but those seem to be shortcuts to time.clock_gettime()?

Agreed.

I've added a line to the clock_settime() section.

We don't need to create a link for this case, but I believe we can still use some markup to make it more readable: ``CLOCK_HIGHRES``

I'm sorry, but I didn't understand this comment.

Yeah, my comment wasn't clear. I meant to say replace CLOCK_HIGHRES with ``CLOCK_HIGHRES``.

@berkerpeksag Thank you for clarifying. I had tried to do that, but, when I did, the tick marks show up in the HTML (after running make html). It doesn't show up here when I cut and paste from the HTML because of Markdown, so I don't know how to show you what it looks like.

That's weird. I don't know why it didn't work. Could you try copy and paste the backticks in line 27 in Doc/library/time.rst? Perhaps something was wrong with my earlier comment.

I was trying to change it next to data::. :-( After looking at it again, I realized what you meant. Sorry about that.

Maybe "See note below." would be more descriptive?

Changed.

I'd listCLOCK_REALTIME after CLOCK_THREAD_CPUTIME_ID and make it look like in the following format:

Clock ID Constants
------------------

These constants are used as parameters for :func:`clock_getres` and
:func:`clock_gettime`.

.. All CLOCK_* constants except CLOCK_REALTIME documented here.

The following constant is the only parameter that can be sent to
:func:`clock_settime`.

.. data:: CLOCK_REALTIME

   System-wide real-time clock.  Setting this clock requires
   appropriate privileges.

   Availability: Unix.

   .. versionadded:: 3.3

Done. Thanks for the suggestion.

Nit: We use "time zone" and "timezone" a bit inconsistently in this note. I don't know which one is correct, but I don't see a reason to use the both forms here.

Good catch. I hadn't even realized I had done that and googling it seems that both ways is correct, so, as you said, it's best to be consistent. I left the 'T' capitalized, but I wasn't sure if I should 1. make it a link, 2. uppercase the 'C' in constant, or 3. lowercase the 'T'.