1.. highlightlang:: 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 16Type-check macros: 17 18 19.. c:function:: int PyDate_Check(PyObject *ob) 20 21 Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of 22 :c:data:`PyDateTime_DateType`. *ob* must not be *NULL*. 23 24 .. versionadded:: 2.4 25 26 27.. c:function:: int PyDate_CheckExact(PyObject *ob) 28 29 Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be 30 *NULL*. 31 32 .. versionadded:: 2.4 33 34 35.. c:function:: int PyDateTime_Check(PyObject *ob) 36 37 Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of 38 :c:data:`PyDateTime_DateTimeType`. *ob* must not be *NULL*. 39 40 .. versionadded:: 2.4 41 42 43.. c:function:: int PyDateTime_CheckExact(PyObject *ob) 44 45 Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not 46 be *NULL*. 47 48 .. versionadded:: 2.4 49 50 51.. c:function:: int PyTime_Check(PyObject *ob) 52 53 Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of 54 :c:data:`PyDateTime_TimeType`. *ob* must not be *NULL*. 55 56 .. versionadded:: 2.4 57 58 59.. c:function:: int PyTime_CheckExact(PyObject *ob) 60 61 Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be 62 *NULL*. 63 64 .. versionadded:: 2.4 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*. 71 72 .. versionadded:: 2.4 73 74 75.. c:function:: int PyDelta_CheckExact(PyObject *ob) 76 77 Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be 78 *NULL*. 79 80 .. versionadded:: 2.4 81 82 83.. c:function:: int PyTZInfo_Check(PyObject *ob) 84 85 Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of 86 :c:data:`PyDateTime_TZInfoType`. *ob* must not be *NULL*. 87 88 .. versionadded:: 2.4 89 90 91.. c:function:: int PyTZInfo_CheckExact(PyObject *ob) 92 93 Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be 94 *NULL*. 95 96 .. versionadded:: 2.4 97 98Macros to create objects: 99 100 101.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day) 102 103 Return a ``datetime.date`` object with the specified year, month and day. 104 105 .. versionadded:: 2.4 106 107 108.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond) 109 110 Return a ``datetime.datetime`` object with the specified year, month, day, hour, 111 minute, second and microsecond. 112 113 .. versionadded:: 2.4 114 115 116.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond) 117 118 Return a ``datetime.time`` object with the specified hour, minute, second and 119 microsecond. 120 121 .. versionadded:: 2.4 122 123 124.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds) 125 126 Return a ``datetime.timedelta`` object representing the given number of days, 127 seconds and microseconds. Normalization is performed so that the resulting 128 number of microseconds and seconds lie in the ranges documented for 129 ``datetime.timedelta`` objects. 130 131 .. versionadded:: 2.4 132 133Macros to extract fields from date objects. The argument must be an instance of 134:c:data:`PyDateTime_Date`, including subclasses (such as 135:c:data:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is 136not checked: 137 138 139.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o) 140 141 Return the year, as a positive int. 142 143 .. versionadded:: 2.4 144 145 146.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o) 147 148 Return the month, as an int from 1 through 12. 149 150 .. versionadded:: 2.4 151 152 153.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o) 154 155 Return the day, as an int from 1 through 31. 156 157 .. versionadded:: 2.4 158 159Macros to extract fields from datetime objects. The argument must be an 160instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument 161must not be *NULL*, and the type is not checked: 162 163 164.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o) 165 166 Return the hour, as an int from 0 through 23. 167 168 .. versionadded:: 2.4 169 170 171.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o) 172 173 Return the minute, as an int from 0 through 59. 174 175 .. versionadded:: 2.4 176 177 178.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o) 179 180 Return the second, as an int from 0 through 59. 181 182 .. versionadded:: 2.4 183 184 185.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o) 186 187 Return the microsecond, as an int from 0 through 999999. 188 189 .. versionadded:: 2.4 190 191Macros to extract fields from time objects. The argument must be an instance of 192:c:data:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*, 193and the type is not checked: 194 195 196.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o) 197 198 Return the hour, as an int from 0 through 23. 199 200 .. versionadded:: 2.4 201 202 203.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o) 204 205 Return the minute, as an int from 0 through 59. 206 207 .. versionadded:: 2.4 208 209 210.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o) 211 212 Return the second, as an int from 0 through 59. 213 214 .. versionadded:: 2.4 215 216 217.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o) 218 219 Return the microsecond, as an int from 0 through 999999. 220 221 .. versionadded:: 2.4 222 223Macros for the convenience of modules implementing the DB API: 224 225 226.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args) 227 228 Create and return a new ``datetime.datetime`` object given an argument tuple 229 suitable for passing to ``datetime.datetime.fromtimestamp()``. 230 231 .. versionadded:: 2.4 232 233 234.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args) 235 236 Create and return a new ``datetime.date`` object given an argument tuple 237 suitable for passing to ``datetime.date.fromtimestamp()``. 238 239 .. versionadded:: 2.4 240