1.. highlight:: c
2
3.. _datetimeobjects:
4
5DateTime Objects
6----------------
7
8Various date and time objects are supplied by the :mod:`datetime` module.
9Before using any of these functions, the header file :file:`datetime.h` must be
10included in your source (note that this is not included by :file:`Python.h`),
11and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
12the module initialisation function.  The macro puts a pointer to a C structure
13into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
14macros.
15
16Macro for access to the UTC singleton:
17
18.. c:var:: PyObject* PyDateTime_TimeZone_UTC
19
20   Returns the time zone singleton representing UTC, the same object as
21   :attr:`datetime.timezone.utc`.
22
23   .. versionadded:: 3.7
24
25
26Type-check macros:
27
28.. c:function:: int PyDate_Check(PyObject *ob)
29
30   Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
31   :c:data:`PyDateTime_DateType`.  *ob* must not be ``NULL``.
32
33
34.. c:function:: int PyDate_CheckExact(PyObject *ob)
35
36   Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
37   ``NULL``.
38
39
40.. c:function:: int PyDateTime_Check(PyObject *ob)
41
42   Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
43   :c:data:`PyDateTime_DateTimeType`.  *ob* must not be ``NULL``.
44
45
46.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
47
48   Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
49   be ``NULL``.
50
51
52.. c:function:: int PyTime_Check(PyObject *ob)
53
54   Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
55   :c:data:`PyDateTime_TimeType`.  *ob* must not be ``NULL``.
56
57
58.. c:function:: int PyTime_CheckExact(PyObject *ob)
59
60   Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
61   ``NULL``.
62
63
64.. c:function:: int PyDelta_Check(PyObject *ob)
65
66   Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
67   :c:data:`PyDateTime_DeltaType`.  *ob* must not be ``NULL``.
68
69
70.. c:function:: int PyDelta_CheckExact(PyObject *ob)
71
72   Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
73   ``NULL``.
74
75
76.. c:function:: int PyTZInfo_Check(PyObject *ob)
77
78   Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
79   :c:data:`PyDateTime_TZInfoType`.  *ob* must not be ``NULL``.
80
81
82.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
83
84   Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
85   ``NULL``.
86
87
88Macros to create objects:
89
90.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
91
92   Return a :class:`datetime.date` object with the specified year, month and day.
93
94
95.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
96
97   Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
98   minute, second and microsecond.
99
100
101.. c:function:: PyObject* PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
102
103   Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
104   minute, second, microsecond and fold.
105
106   .. versionadded:: 3.6
107
108
109.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
110
111   Return a :class:`datetime.time` object with the specified hour, minute, second and
112   microsecond.
113
114
115.. c:function:: PyObject* PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
116
117   Return a :class:`datetime.time` object with the specified hour, minute, second,
118   microsecond and fold.
119
120   .. versionadded:: 3.6
121
122
123.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
124
125   Return a :class:`datetime.timedelta` object representing the given number
126   of days, seconds and microseconds.  Normalization is performed so that the
127   resulting number of microseconds and seconds lie in the ranges documented for
128   :class:`datetime.timedelta` objects.
129
130.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
131
132   Return a :class:`datetime.timezone` object with an unnamed fixed offset
133   represented by the *offset* argument.
134
135   .. versionadded:: 3.7
136
137.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)
138
139   Return a :class:`datetime.timezone` object with a fixed offset represented
140   by the *offset* argument and with tzname *name*.
141
142   .. versionadded:: 3.7
143
144
145Macros to extract fields from date objects.  The argument must be an instance of
146:c:data:`PyDateTime_Date`, including subclasses (such as
147:c:data:`PyDateTime_DateTime`).  The argument must not be ``NULL``, and the type is
148not checked:
149
150.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
151
152   Return the year, as a positive int.
153
154
155.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
156
157   Return the month, as an int from 1 through 12.
158
159
160.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
161
162   Return the day, as an int from 1 through 31.
163
164
165Macros to extract fields from datetime objects.  The argument must be an
166instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
167must not be ``NULL``, and the type is not checked:
168
169.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
170
171   Return the hour, as an int from 0 through 23.
172
173
174.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
175
176   Return the minute, as an int from 0 through 59.
177
178
179.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
180
181   Return the second, as an int from 0 through 59.
182
183
184.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
185
186   Return the microsecond, as an int from 0 through 999999.
187
188
189Macros to extract fields from time objects.  The argument must be an instance of
190:c:data:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
191and the type is not checked:
192
193.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
194
195   Return the hour, as an int from 0 through 23.
196
197
198.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
199
200   Return the minute, as an int from 0 through 59.
201
202
203.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
204
205   Return the second, as an int from 0 through 59.
206
207
208.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
209
210   Return the microsecond, as an int from 0 through 999999.
211
212
213Macros to extract fields from time delta objects.  The argument must be an
214instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
215not be ``NULL``, and the type is not checked:
216
217.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
218
219   Return the number of days, as an int from -999999999 to 999999999.
220
221   .. versionadded:: 3.3
222
223
224.. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)
225
226   Return the number of seconds, as an int from 0 through 86399.
227
228   .. versionadded:: 3.3
229
230
231.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
232
233   Return the number of microseconds, as an int from 0 through 999999.
234
235   .. versionadded:: 3.3
236
237
238Macros for the convenience of modules implementing the DB API:
239
240.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
241
242   Create and return a new :class:`datetime.datetime` object given an argument
243   tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp()`.
244
245
246.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
247
248   Create and return a new :class:`datetime.date` object given an argument
249   tuple suitable for passing to :meth:`datetime.date.fromtimestamp()`.
250