1 .. highlightlang:: 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 Macro 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 26 Type-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 88 Macros 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* PyTime_FromTime(int hour, int minute, int second, int usecond) 102 103 Return a :class:`datetime.time` object with the specified hour, minute, second and 104 microsecond. 105 106 107 .. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds) 108 109 Return a :class:`datetime.timedelta` object representing the given number 110 of days, seconds and microseconds. Normalization is performed so that the 111 resulting number of microseconds and seconds lie in the ranges documented for 112 :class:`datetime.timedelta` objects. 113 114 .. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset) 115 116 Return a :class:`datetime.timezone` object with an unnamed fixed offset 117 represented by the *offset* argument. 118 119 .. versionadded:: 3.7 120 121 .. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name) 122 123 Return a :class:`datetime.timezone` object with a fixed offset represented 124 by the *offset* argument and with tzname *name*. 125 126 .. versionadded:: 3.7 127 128 129 Macros to extract fields from date objects. The argument must be an instance of 130 :c:data:`PyDateTime_Date`, including subclasses (such as 131 :c:data:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is 132 not checked: 133 134 .. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o) 135 136 Return the year, as a positive int. 137 138 139 .. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o) 140 141 Return the month, as an int from 1 through 12. 142 143 144 .. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o) 145 146 Return the day, as an int from 1 through 31. 147 148 149 Macros to extract fields from datetime objects. The argument must be an 150 instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument 151 must not be *NULL*, and the type is not checked: 152 153 .. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o) 154 155 Return the hour, as an int from 0 through 23. 156 157 158 .. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o) 159 160 Return the minute, as an int from 0 through 59. 161 162 163 .. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o) 164 165 Return the second, as an int from 0 through 59. 166 167 168 .. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o) 169 170 Return the microsecond, as an int from 0 through 999999. 171 172 173 Macros to extract fields from time objects. The argument must be an instance of 174 :c:data:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*, 175 and the type is not checked: 176 177 .. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o) 178 179 Return the hour, as an int from 0 through 23. 180 181 182 .. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o) 183 184 Return the minute, as an int from 0 through 59. 185 186 187 .. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o) 188 189 Return the second, as an int from 0 through 59. 190 191 192 .. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o) 193 194 Return the microsecond, as an int from 0 through 999999. 195 196 197 Macros to extract fields from time delta objects. The argument must be an 198 instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must 199 not be *NULL*, and the type is not checked: 200 201 .. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o) 202 203 Return the number of days, as an int from -999999999 to 999999999. 204 205 .. versionadded:: 3.3 206 207 208 .. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o) 209 210 Return the number of seconds, as an int from 0 through 86399. 211 212 .. versionadded:: 3.3 213 214 215 .. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o) 216 217 Return the number of microseconds, as an int from 0 through 999999. 218 219 .. versionadded:: 3.3 220 221 222 Macros for the convenience of modules implementing the DB API: 223 224 .. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args) 225 226 Create and return a new :class:`datetime.datetime` object given an argument 227 tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp()`. 228 229 230 .. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args) 231 232 Create and return a new :class:`datetime.date` object given an argument 233 tuple suitable for passing to :meth:`datetime.date.fromtimestamp()`. 234
