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``.  This function always
32   succeeds.
33
34
35.. c:function:: int PyDate_CheckExact(PyObject *ob)
36
37   Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
38   ``NULL``.  This function always succeeds.
39
40
41.. c:function:: int PyDateTime_Check(PyObject *ob)
42
43   Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
44   :c:data:`PyDateTime_DateTimeType`.  *ob* must not be ``NULL``.  This function always
45   succeeds.
46
47
48.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
49
50   Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
51   be ``NULL``.  This function always succeeds.
52
53
54.. c:function:: int PyTime_Check(PyObject *ob)
55
56   Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
57   :c:data:`PyDateTime_TimeType`.  *ob* must not be ``NULL``.  This function always
58   succeeds.
59
60
61.. c:function:: int PyTime_CheckExact(PyObject *ob)
62
63   Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
64   ``NULL``.  This function always succeeds.
65
66
67.. c:function:: int PyDelta_Check(PyObject *ob)
68
69   Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
70   :c:data:`PyDateTime_DeltaType`.  *ob* must not be ``NULL``.  This function always
71   succeeds.
72
73
74.. c:function:: int PyDelta_CheckExact(PyObject *ob)
75
76   Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
77   ``NULL``.  This function always succeeds.
78
79
80.. c:function:: int PyTZInfo_Check(PyObject *ob)
81
82   Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
83   :c:data:`PyDateTime_TZInfoType`.  *ob* must not be ``NULL``.  This function always
84   succeeds.
85
86
87.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
88
89   Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
90   ``NULL``.  This function always succeeds.
91
92
93Macros to create objects:
94
95.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
96
97   Return a :class:`datetime.date` object with the specified year, month and day.
98
99
100.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
101
102   Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
103   minute, second and microsecond.
104
105
106.. c:function:: PyObject* PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
107
108   Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
109   minute, second, microsecond and fold.
110
111   .. versionadded:: 3.6
112
113
114.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
115
116   Return a :class:`datetime.time` object with the specified hour, minute, second and
117   microsecond.
118
119
120.. c:function:: PyObject* PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
121
122   Return a :class:`datetime.time` object with the specified hour, minute, second,
123   microsecond and fold.
124
125   .. versionadded:: 3.6
126
127
128.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
129
130   Return a :class:`datetime.timedelta` object representing the given number
131   of days, seconds and microseconds.  Normalization is performed so that the
132   resulting number of microseconds and seconds lie in the ranges documented for
133   :class:`datetime.timedelta` objects.
134
135
136.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
137
138   Return a :class:`datetime.timezone` object with an unnamed fixed offset
139   represented by the *offset* argument.
140
141   .. versionadded:: 3.7
142
143
144.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)
145
146   Return a :class:`datetime.timezone` object with a fixed offset represented
147   by the *offset* argument and with tzname *name*.
148
149   .. versionadded:: 3.7
150
151
152Macros to extract fields from date objects.  The argument must be an instance of
153:c:data:`PyDateTime_Date`, including subclasses (such as
154:c:data:`PyDateTime_DateTime`).  The argument must not be ``NULL``, and the type is
155not checked:
156
157.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
158
159   Return the year, as a positive int.
160
161
162.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
163
164   Return the month, as an int from 1 through 12.
165
166
167.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
168
169   Return the day, as an int from 1 through 31.
170
171
172Macros to extract fields from datetime objects.  The argument must be an
173instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
174must not be ``NULL``, and the type is not checked:
175
176.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
177
178   Return the hour, as an int from 0 through 23.
179
180
181.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
182
183   Return the minute, as an int from 0 through 59.
184
185
186.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
187
188   Return the second, as an int from 0 through 59.
189
190
191.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
192
193   Return the microsecond, as an int from 0 through 999999.
194
195
196.. c:function:: int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)
197
198   Return the fold, as an int from 0 through 1.
199
200   .. versionadded:: 3.6
201
202
203.. c:function:: PyObject* PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)
204
205   Return the tzinfo (which may be ``None``).
206
207   .. versionadded:: 3.10
208
209
210Macros to extract fields from time objects.  The argument must be an instance of
211:c:data:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
212and the type is not checked:
213
214.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
215
216   Return the hour, as an int from 0 through 23.
217
218
219.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
220
221   Return the minute, as an int from 0 through 59.
222
223
224.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
225
226   Return the second, as an int from 0 through 59.
227
228
229.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
230
231   Return the microsecond, as an int from 0 through 999999.
232
233
234.. c:function:: int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)
235
236   Return the fold, as an int from 0 through 1.
237
238   .. versionadded:: 3.6
239
240
241.. c:function:: PyObject* PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)
242
243   Return the tzinfo (which may be ``None``).
244
245   .. versionadded:: 3.10
246
247
248Macros to extract fields from time delta objects.  The argument must be an
249instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
250not be ``NULL``, and the type is not checked:
251
252.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
253
254   Return the number of days, as an int from -999999999 to 999999999.
255
256   .. versionadded:: 3.3
257
258
259.. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)
260
261   Return the number of seconds, as an int from 0 through 86399.
262
263   .. versionadded:: 3.3
264
265
266.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
267
268   Return the number of microseconds, as an int from 0 through 999999.
269
270   .. versionadded:: 3.3
271
272
273Macros for the convenience of modules implementing the DB API:
274
275.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
276
277   Create and return a new :class:`datetime.datetime` object given an argument
278   tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp()`.
279
280
281.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
282
283   Create and return a new :class:`datetime.date` object given an argument
284   tuple suitable for passing to :meth:`datetime.date.fromtimestamp()`.
285