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