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