bpo-10381: Add timezone to datetime C API #5032

pganssle · 2017-12-28T20:20:22Z

This adds C API access to timezone and the timezone.UTC singleton, per bpo-10381.

@abalkin I didn't totally understand what you meant by "I am not sure whether PyDateTime_TimeZone details should be exposed in datetime.h because presumably programmers should access it through the abstract tzinfo interface.", so please clarify if this PR is exposing the details you referred to.

https://bugs.python.org/issue10381

pganssle · 2017-12-28T20:31:41Z

Hm. There's some sort of build error about levels of indirection that seems to only be happening on Windows. I'm not really sure what to do with that - I can take a look at it later, but if any Windows users know if that's a common thing please do let me know. This was some sort of symbol confusion because in my test I had an object named timezone.

I added documentation for the macros, but I didn't see an obvious place to document that the UTC singleton is now available through the C API.

abalkin · 2018-01-09T17:07:38Z

@pganssle - IIRC, my comment on the issue was about PyDateTime_TimeZone struct which should probably stay private and not exposed in the header file. Your PR does the right thing in this regard.

abalkin

Please remove the "Check" methods and limit this PR to TimeZone_UTC and constructors.

abalkin · 2018-01-09T17:10:37Z

Doc/c-api/datetime.rst

@@ -75,6 +75,18 @@ Type-check macros:
   *NULL*.


+.. c:function:: int PyTimeZone_Check(PyObject *ob)


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

abalkin · 2018-01-09T17:17:09Z

Doc/c-api/datetime.rst

+   :c:data:`PyDateTime_TimeZoneType`.  *ob* must not be *NULL*.
+
+
+.. c:function:: int PyTimeZone_CheckExact(PyObject *ob)


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.

bedevere-bot · 2018-01-09T17:20:49Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

pganssle · 2018-01-09T17:39:10Z

Include/datetime.h

@@ -154,13 +154,18 @@ typedef struct {
    PyTypeObject *TimeType;
    PyTypeObject *DeltaType;
    PyTypeObject *TZInfoType;
+    PyTypeObject *TimeZoneType;


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

pganssle · 2018-01-12T17:50:26Z

@abalkin Ready for review. I added a new commit rather than rewriting the history, because I figure it might be useful to have access to the tests and such later if this is ever exposed.

abalkin · 2018-01-16T17:19:45Z

Include/datetime.h

@@ -155,12 +155,16 @@ typedef struct {
    PyTypeObject *DeltaType;
    PyTypeObject *TZInfoType;

+    /* singletons */
+    PyObject *TimeZone_UTC;


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.

pganssle · 2018-01-17T15:27:22Z

Doc/c-api/datetime.rst

@@ -13,6 +13,16 @@ the module initialisation function.  The macro puts a pointer to a C structure
 into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
 macros.

+Macro for access to the UTC singleton:


@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?

vadmium · 2018-01-19T20:43:11Z

Doc/c-api/datetime.rst

+
+.. c:var:: PyObject* PyDateTime_TimeZone_UTC
+
+   Returns the time zone singleton representing UTC, this returns the same


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

vadmium · 2018-01-19T20:48:18Z

Doc/c-api/datetime.rst

+.. c:var:: PyObject* PyDateTime_TimeZone_UTC
+
+   Returns the time zone singleton representing UTC, this returns the same
+   object as ``datetime.timezone.utc``.


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?

vadmium · 2018-01-19T20:54:13Z

Doc/c-api/datetime.rst

+.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
+
+   Return a ``datetime.timezone`` object with an unnamed fixed offset
+   represented by the ``offset`` argument.


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

vadmium · 2018-01-19T21:12:31Z

Lib/test/datetimetester.py

+        est_capi, est_macro, est_macro_nn = _testcapi.make_timezones_capi()
+
+        exp_named = timezone(timedelta(hours=-5), "EST")
+        exp_unnamed = timezone(timedelta(hours=-5))


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.

pganssle · 2018-01-20T17:51:54Z

Doc/c-api/datetime.rst

+   resulting number of microseconds and seconds lie in the ranges documented for
+   :class:`datetime.timedelta` objects.
+
+.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)


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.

pganssle · 2018-01-21T22:23:24Z

@vadmium Should be good now.

the-knights-who-say-ni added the CLA signed label Dec 28, 2017

bedevere-bot added the awaiting review label Dec 28, 2017

pganssle force-pushed the timezone_api branch from fa54439 to 09377f2 Compare December 28, 2017 20:23

pganssle force-pushed the timezone_api branch 8 times, most recently from e85cfc9 to 70fe5a2 Compare January 5, 2018 17:34

abalkin requested changes Jan 9, 2018

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Jan 9, 2018

abalkin self-assigned this Jan 9, 2018

pganssle commented Jan 9, 2018

View reviewed changes

pganssle force-pushed the timezone_api branch from 70fe5a2 to d026f56 Compare January 12, 2018 14:26

abalkin reviewed Jan 16, 2018

View reviewed changes

pganssle force-pushed the timezone_api branch 2 times, most recently from fb1b06c to c38ea33 Compare January 16, 2018 21:37

pganssle commented Jan 17, 2018

View reviewed changes

abalkin approved these changes Jan 17, 2018

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting changes labels Jan 17, 2018

abalkin requested a review from vadmium January 17, 2018 18:36

vadmium reviewed Jan 19, 2018

View reviewed changes

pganssle added 7 commits January 20, 2018 12:33

Add timezone to datetime C API

7f1878b

Add documentation for timezone C API macros

20676ae

Add dedicated tests for datetime type check macros

4a1bab6

Remove superfluous C API test

8728bd7

Drop support for TimeZoneType in datetime C API

2c20871

Expose UTC singleton to the datetime C API

0398e3c

Update datetime C-API documentation to include links

70642af

pganssle force-pushed the timezone_api branch from c38ea33 to 70642af Compare January 20, 2018 17:42

pganssle commented Jan 20, 2018

View reviewed changes

Add reference count information for timezone constructors

9303050

abalkin merged commit 04af5b1 into python:master Jan 24, 2018

bedevere-bot removed the awaiting merge label Jan 24, 2018

pganssle mentioned this pull request Feb 22, 2018

bpo-10381, bpo-32403: What's new entries for changes to datetime #5814

Merged

joshuahlang mentioned this pull request May 20, 2018

datetimeoffset support zillow/ctds#14

Open

pganssle mentioned this pull request Aug 22, 2018

Support Python 3.7 timezone in datetime bindings PyO3/pyo3#207

Closed

pganssle deleted the timezone_api branch October 25, 2018 14:29

skeydan mentioned this pull request Nov 13, 2019

use Rcpp to convert R Dates to Python rstudio/reticulate#643

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-10381: Add timezone to datetime C API #5032

bpo-10381: Add timezone to datetime C API #5032

pganssle commented Dec 28, 2017 •

edited by bedevere-bot

Loading

pganssle commented Dec 28, 2017 •

edited

Loading

abalkin commented Jan 9, 2018

abalkin left a comment

abalkin Jan 9, 2018

abalkin Jan 9, 2018

pganssle Jan 9, 2018

bedevere-bot commented Jan 9, 2018

pganssle Jan 9, 2018

abalkin Jan 10, 2018

pganssle commented Jan 12, 2018

abalkin Jan 16, 2018

pganssle Jan 16, 2018

pganssle Jan 17, 2018

vadmium Jan 19, 2018

vadmium Jan 19, 2018

pganssle Jan 20, 2018

vadmium Jan 19, 2018

vadmium Jan 19, 2018

pganssle Jan 20, 2018

pganssle Jan 20, 2018

abalkin Jan 23, 2018

pganssle Jan 24, 2018

abalkin Jan 24, 2018

pganssle commented Jan 21, 2018

		@@ -75,6 +75,18 @@ Type-check macros:
		NULL.


		.. c:function:: int PyTimeZone_Check(PyObject *ob)

		:c:data:`PyDateTime_TimeZoneType`. ob must not be NULL.


		.. c:function:: int PyTimeZone_CheckExact(PyObject *ob)


		.. c:var:: PyObject* PyDateTime_TimeZone_UTC

		Returns the time zone singleton representing UTC, this returns the same

bpo-10381: Add timezone to datetime C API #5032

bpo-10381: Add timezone to datetime C API #5032

Conversation

pganssle commented Dec 28, 2017 • edited by bedevere-bot Loading

pganssle commented Dec 28, 2017 • edited Loading

abalkin commented Jan 9, 2018

abalkin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bedevere-bot commented Jan 9, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pganssle commented Jan 12, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pganssle commented Jan 21, 2018

pganssle commented Dec 28, 2017 •

edited by bedevere-bot

Loading

pganssle commented Dec 28, 2017 •

edited

Loading