Note that the typezone type cannot be subclassed:

>>> from datetime import *
>>> class tz(timezone):
...    pass
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: type 'datetime.timezone' is not an acceptable base type

Since we are not exposing PyDateTime_TimeZone struct, I don't see the utility of having PyTimeZone_Check macros. Maybe something like PyTZInfo_Check as an accelerated version of isinstance(x, datetime.tzinfo) will be useful once we expose C versions of tzinfo.utcoffset, etc. methods, but this is better left for a separate PR.

Why not just remove the _Check and leave the _CheckExact? I would think that the _CheckExact function is still meaningful.

@abalkin If you don't want the _Check macros exposed, do you also not want this exposed?

yes

Shouldn't we also add a macro definition below to simplify access to the singleton?

#ifdef Py_BUILD_CORE
 ..
#else
#define PyDateTime_TimeZone_UTC PyDateTimeAPI->TimeZone_UTC
#endif

The idea is to make code in user extensions look similar to that in _datetimemodule.c.

Yeah, I'm fine with that. I think I didn't know of any examples of other singletons exposed in the C API so I didn't know to do this.

@abalkin I had to add a new section for this and decided to put it at the top, please let me know if you'd prefer it to be somewhere else.

@vadmium You did a great review of the documentation on #4699, do you want to take a look at this?

Remove “this returns” (or start a new sentence)

Can you link to :attr:`datetime.timezone.utc` here (and similarly elsewhere)? If so, I think they would be useful.

I don't see any other references to timezone.utc in c-api/datetime.rst, do you mean add other links to things other than timezone.utc, or modify other documents to link to timezone.utc?

Parameter names are normally marked up in italics as *offset*

Looks like there is no practical difference between these two as far as the test is concerned, so I suggest to drop one of them. Comparison of datetime objects only considers the offset.

Ooh, good call, as written this test doesn't actually check if PyTimeZone_FromOffsetAndName actually works.

When I build the documentation, I see Return value: New reference. under all the constructor macros except these two, but I'm not sure where that's being generated from. I don't see why they wouldn't be a new reference, but I don't 100% grok when something does and does not change the reference count.

Reference counting information is stored in Doc/data/refcounts.dat

@abalkin When documenting the reference counts, I ran into a bit of a problem, since the reference to offset is not increased if offset is equivalent to timedelta(0), so it's ambiguous whether the function's effect on offset's reference count is +1 or 0. I went with +1 and added a comment to the effect that it's not always true.

I am going to merge this now. We can fine tune the documentation during the beta phase.