Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abalkin merged 8 commits into from
Jan 24, 2018
Merged

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

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7f1878b
Add timezone to datetime C API
pganssle Dec 28, 2017
20676ae
Add documentation for timezone C API macros
pganssle Dec 28, 2017
4a1bab6
Add dedicated tests for datetime type check macros
pganssle Dec 29, 2017
8728bd7
Remove superfluous C API test
pganssle Dec 29, 2017
2c20871
Drop support for TimeZoneType in datetime C API
pganssle Jan 12, 2018
0398e3c
Expose UTC singleton to the datetime C API
pganssle Jan 16, 2018
70642af
Update datetime C-API documentation to include links
pganssle Jan 20, 2018
9303050
Add reference count information for timezone constructors
pganssle Jan 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Add documentation for timezone C API macros
  • Loading branch information
@pganssle
pganssle committed Jan 20, 2018
commit 20676ae546ad0e47419445e19f5b35fb6f628ff5
26 changes: 26 additions & 0 deletions Doc/c-api/datetime.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,18 @@ Type-check macros:
*NULL*.


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

@abalkin abalkin Jan 9, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Return true if *ob* is of type :c:data:`PyDateTime_TimeZoneType` or a subtype of
:c:data:`PyDateTime_TimeZoneType`. *ob* must not be *NULL*.


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

@abalkin abalkin Jan 9, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@pganssle pganssle Jan 9, 2018

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Return true if *ob* is of type :c:data:`PyDateTime_TimeZoneType`. *ob* must not be
*NULL*.


Macros to create objects:

.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
Expand All @@ -101,6 +113,20 @@ Macros to create objects:
number of microseconds and seconds lie in the ranges documented for
``datetime.timedelta`` objects.

.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)

@pganssle pganssle Jan 20, 2018

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@abalkin abalkin Jan 23, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@pganssle pganssle Jan 24, 2018

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@abalkin abalkin Jan 24, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Return a ``datetime.timezone`` object with an unnamed fixed offset
represented by the *offset* argument.

.. versionadded:: 3.7

.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)

Return a ``datetime.timezone`` object with a fixed offset represented by
the *offset* argument and with tzname *name*.

.. versionadded:: 3.7


Macros to extract fields from date objects. The argument must be an instance of
:c:data:`PyDateTime_Date`, including subclasses (such as
Expand Down