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