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.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset) 136 137 Return a :class:`datetime.timezone` object with an unnamed fixed offset 138 represented by the *offset* argument. 139 140 .. versionadded:: 3.7 141 142.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name) 143 144 Return a :class:`datetime.timezone` object with a fixed offset represented 145 by the *offset* argument and with tzname *name*. 146 147 .. versionadded:: 3.7 148 149 150Macros to extract fields from date objects. The argument must be an instance of 151:c:data:`PyDateTime_Date`, including subclasses (such as 152:c:data:`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is 153not checked: 154 155.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o) 156 157 Return the year, as a positive int. 158 159 160.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o) 161 162 Return the month, as an int from 1 through 12. 163 164 165.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o) 166 167 Return the day, as an int from 1 through 31. 168 169 170Macros to extract fields from datetime objects. The argument must be an 171instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument 172must not be ``NULL``, and the type is not checked: 173 174.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o) 175 176 Return the hour, as an int from 0 through 23. 177 178 179.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o) 180 181 Return the minute, as an int from 0 through 59. 182 183 184.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o) 185 186 Return the second, as an int from 0 through 59. 187 188 189.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o) 190 191 Return the microsecond, as an int from 0 through 999999. 192 193.. c:function:: PyObject* PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o) 194 195 Return the tzinfo (which may be ``None``). 196 197 .. versionadded:: 3.10 198 199Macros to extract fields from time objects. The argument must be an instance of 200:c:data:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``, 201and the type is not checked: 202 203.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o) 204 205 Return the hour, as an int from 0 through 23. 206 207 208.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o) 209 210 Return the minute, as an int from 0 through 59. 211 212 213.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o) 214 215 Return the second, as an int from 0 through 59. 216 217 218.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o) 219 220 Return the microsecond, as an int from 0 through 999999. 221 222.. c:function:: PyObject* PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o) 223 224 Return the tzinfo (which may be ``None``). 225 226 .. versionadded:: 3.10 227 228 229Macros to extract fields from time delta objects. The argument must be an 230instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must 231not be ``NULL``, and the type is not checked: 232 233.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o) 234 235 Return the number of days, as an int from -999999999 to 999999999. 236 237 .. versionadded:: 3.3 238 239 240.. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o) 241 242 Return the number of seconds, as an int from 0 through 86399. 243 244 .. versionadded:: 3.3 245 246 247.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o) 248 249 Return the number of microseconds, as an int from 0 through 999999. 250 251 .. versionadded:: 3.3 252 253 254Macros for the convenience of modules implementing the DB API: 255 256.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args) 257 258 Create and return a new :class:`datetime.datetime` object given an argument 259 tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp()`. 260 261 262.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args) 263 264 Create and return a new :class:`datetime.date` object given an argument 265 tuple suitable for passing to :meth:`datetime.date.fromtimestamp()`. 266