Debian Codegraph @

Doc/c-api/datetime.rst

raw
1 .. highlight:: c
2
3 .. _datetimeobjects:
4
5 DateTime Objects
6 ----------------
7
8 Various date and time objects are supplied by the :mod:`datetime` module.
9 Before using any of these functions, the header file :file:`datetime.h` must be
10 included in your source (note that this is not included by :file:`Python.h`),
11 and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
12 the module initialisation function. The macro puts a pointer to a C structure
13 into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
14 macros.
15
16 .. c:macro:: PyDateTime_IMPORT()
17
18 Import the datetime C API.
19
20 On success, populate the :c:var:`PyDateTimeAPI` pointer.
21 On failure, set :c:var:`PyDateTimeAPI` to ``NULL`` and set an exception.
22 The caller must check if an error occurred via :c:func:`PyErr_Occurred`:
23
24 .. code-block::
25
26 PyDateTime_IMPORT;
27 if (PyErr_Occurred()) { /* cleanup */ }
28
29 .. warning::
30
31 This is not compatible with subinterpreters.
32
33 .. c:type:: PyDateTime_CAPI
34
35 Structure containing the fields for the datetime C API.
36
37 The fields of this structure are private and subject to change.
38
39 Do not use this directly; prefer ``PyDateTime_*`` APIs instead.
40
41 .. c:var:: PyDateTime_CAPI *PyDateTimeAPI
42
43 Dynamically allocated object containing the datetime C API.
44
45 This variable is only available once :c:macro:`PyDateTime_IMPORT` succeeds.
46
47 .. c:type:: PyDateTime_Date
48
49 This subtype of :c:type:`PyObject` represents a Python date object.
50
51 .. c:type:: PyDateTime_DateTime
52
53 This subtype of :c:type:`PyObject` represents a Python datetime object.
54
55 .. c:type:: PyDateTime_Time
56
57 This subtype of :c:type:`PyObject` represents a Python time object.
58
59 .. c:type:: PyDateTime_Delta
60
61 This subtype of :c:type:`PyObject` represents the difference between two datetime values.
62
63 .. c:var:: PyTypeObject PyDateTime_DateType
64
65 This instance of :c:type:`PyTypeObject` represents the Python date type;
66 it is the same object as :class:`datetime.date` in the Python layer.
67
68 .. c:var:: PyTypeObject PyDateTime_DateTimeType
69
70 This instance of :c:type:`PyTypeObject` represents the Python datetime type;
71 it is the same object as :class:`datetime.datetime` in the Python layer.
72
73 .. c:var:: PyTypeObject PyDateTime_TimeType
74
75 This instance of :c:type:`PyTypeObject` represents the Python time type;
76 it is the same object as :class:`datetime.time` in the Python layer.
77
78 .. c:var:: PyTypeObject PyDateTime_DeltaType
79
80 This instance of :c:type:`PyTypeObject` represents the Python type for
81 the difference between two datetime values;
82 it is the same object as :class:`datetime.timedelta` in the Python layer.
83
84 .. c:var:: PyTypeObject PyDateTime_TZInfoType
85
86 This instance of :c:type:`PyTypeObject` represents the Python time zone info type;
87 it is the same object as :class:`datetime.tzinfo` in the Python layer.
88
89
90 Macro for access to the UTC singleton:
91
92 .. c:var:: PyObject* PyDateTime_TimeZone_UTC
93
94 Returns the time zone singleton representing UTC, the same object as
95 :attr:`datetime.timezone.utc`.
96
97 .. versionadded:: 3.7
98
99
100 Type-check macros:
101
102 .. c:function:: int PyDate_Check(PyObject *ob)
103
104 Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
105 :c:data:`!PyDateTime_DateType`. *ob* must not be ``NULL``. This function always
106 succeeds.
107
108
109 .. c:function:: int PyDate_CheckExact(PyObject *ob)
110
111 Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
112 ``NULL``. This function always succeeds.
113
114
115 .. c:function:: int PyDateTime_Check(PyObject *ob)
116
117 Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
118 :c:data:`!PyDateTime_DateTimeType`. *ob* must not be ``NULL``. This function always
119 succeeds.
120
121
122 .. c:function:: int PyDateTime_CheckExact(PyObject *ob)
123
124 Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
125 be ``NULL``. This function always succeeds.
126
127
128 .. c:function:: int PyTime_Check(PyObject *ob)
129
130 Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
131 :c:data:`!PyDateTime_TimeType`. *ob* must not be ``NULL``. This function always
132 succeeds.
133
134
135 .. c:function:: int PyTime_CheckExact(PyObject *ob)
136
137 Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
138 ``NULL``. This function always succeeds.
139
140
141 .. c:function:: int PyDelta_Check(PyObject *ob)
142
143 Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
144 :c:data:`!PyDateTime_DeltaType`. *ob* must not be ``NULL``. This function always
145 succeeds.
146
147
148 .. c:function:: int PyDelta_CheckExact(PyObject *ob)
149
150 Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
151 ``NULL``. This function always succeeds.
152
153
154 .. c:function:: int PyTZInfo_Check(PyObject *ob)
155
156 Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
157 :c:data:`!PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This function always
158 succeeds.
159
160
161 .. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
162
163 Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
164 ``NULL``. This function always succeeds.
165
166
167 Macros to create objects:
168
169 .. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
170
171 Return a :class:`datetime.date` object with the specified year, month and day.
172
173
174 .. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
175
176 Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
177 minute, second and microsecond.
178
179
180 .. c:function:: PyObject* PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
181
182 Return a :class:`datetime.datetime` object with the specified year, month, day, hour,
183 minute, second, microsecond and fold.
184
185 .. versionadded:: 3.6
186
187
188 .. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
189
190 Return a :class:`datetime.time` object with the specified hour, minute, second and
191 microsecond.
192
193
194 .. c:function:: PyObject* PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
195
196 Return a :class:`datetime.time` object with the specified hour, minute, second,
197 microsecond and fold.
198
199 .. versionadded:: 3.6
200
201
202 .. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
203
204 Return a :class:`datetime.timedelta` object representing the given number
205 of days, seconds and microseconds. Normalization is performed so that the
206 resulting number of microseconds and seconds lie in the ranges documented for
207 :class:`datetime.timedelta` objects.
208
209
210 .. c:function:: PyObject* PyTimeZone_FromOffset(PyObject *offset)
211
212 Return a :class:`datetime.timezone` object with an unnamed fixed offset
213 represented by the *offset* argument.
214
215 .. versionadded:: 3.7
216
217
218 .. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)
219
220 Return a :class:`datetime.timezone` object with a fixed offset represented
221 by the *offset* argument and with tzname *name*.
222
223 .. versionadded:: 3.7
224
225
226 Macros to extract fields from date objects. The argument must be an instance of
227 :c:type:`PyDateTime_Date`, including subclasses (such as
228 :c:type:`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is
229 not checked:
230
231 .. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
232
233 Return the year, as a positive int.
234
235
236 .. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
237
238 Return the month, as an int from 1 through 12.
239
240
241 .. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
242
243 Return the day, as an int from 1 through 31.
244
245
246 Macros to extract fields from datetime objects. The argument must be an
247 instance of :c:type:`PyDateTime_DateTime`, including subclasses. The argument
248 must not be ``NULL``, and the type is not checked:
249
250 .. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
251
252 Return the hour, as an int from 0 through 23.
253
254
255 .. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
256
257 Return the minute, as an int from 0 through 59.
258
259
260 .. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
261
262 Return the second, as an int from 0 through 59.
263
264
265 .. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
266
267 Return the microsecond, as an int from 0 through 999999.
268
269
270 .. c:function:: int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)
271
272 Return the fold, as an int from 0 through 1.
273
274 .. versionadded:: 3.6
275
276
277 .. c:function:: PyObject* PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)
278
279 Return the tzinfo (which may be ``None``).
280
281 .. versionadded:: 3.10
282
283
284 Macros to extract fields from time objects. The argument must be an instance of
285 :c:type:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
286 and the type is not checked:
287
288 .. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
289
290 Return the hour, as an int from 0 through 23.
291
292
293 .. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
294
295 Return the minute, as an int from 0 through 59.
296
297
298 .. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
299
300 Return the second, as an int from 0 through 59.
301
302
303 .. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
304
305 Return the microsecond, as an int from 0 through 999999.
306
307
308 .. c:function:: int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)
309
310 Return the fold, as an int from 0 through 1.
311
312 .. versionadded:: 3.6
313
314
315 .. c:function:: PyObject* PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)
316
317 Return the tzinfo (which may be ``None``).
318
319 .. versionadded:: 3.10
320
321
322 Macros to extract fields from time delta objects. The argument must be an
323 instance of :c:type:`PyDateTime_Delta`, including subclasses. The argument must
324 not be ``NULL``, and the type is not checked:
325
326 .. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
327
328 Return the number of days, as an int from -999999999 to 999999999.
329
330 .. versionadded:: 3.3
331
332
333 .. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)
334
335 Return the number of seconds, as an int from 0 through 86399.
336
337 .. versionadded:: 3.3
338
339
340 .. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
341
342 Return the number of microseconds, as an int from 0 through 999999.
343
344 .. versionadded:: 3.3
345
346
347 Macros for the convenience of modules implementing the DB API:
348
349 .. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
350
351 Create and return a new :class:`datetime.datetime` object given an argument
352 tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp`.
353
354
355 .. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
356
357 Create and return a new :class:`datetime.date` object given an argument
358 tuple suitable for passing to :meth:`datetime.date.fromtimestamp`.
359
360
361 Internal data
362 -------------
363
364 The following symbols are exposed by the C API but should be considered
365 internal-only.
366
367 .. c:macro:: PyDateTime_CAPSULE_NAME
368
369 Name of the datetime capsule to pass to :c:func:`PyCapsule_Import`.
370
371 Internal usage only. Use :c:macro:`PyDateTime_IMPORT` instead.