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 16.. c:type:: PyDateTime_Date 17 18 This subtype of :c:type:`PyObject` represents a Python date object. 19 20.. c:type:: PyDateTime_DateTime 21 22 This subtype of :c:type:`PyObject` represents a Python datetime object. 23 24.. c:type:: PyDateTime_Time 25 26 This subtype of :c:type:`PyObject` represents a Python time object. 27 28.. c:type:: PyDateTime_Delta 29 30 This subtype of :c:type:`PyObject` represents the difference between two datetime values. 31 32.. c:var:: PyTypeObject PyDateTime_DateType 33 34 This instance of :c:type:`PyTypeObject` represents the Python date type; 35 it is the same object as :class:`datetime.date` in the Python layer. 36 37.. c:var:: PyTypeObject PyDateTime_DateTimeType 38 39 This instance of :c:type:`PyTypeObject` represents the Python datetime type; 40 it is the same object as :class:`datetime.datetime` in the Python layer. 41 42.. c:var:: PyTypeObject PyDateTime_TimeType 43 44 This instance of :c:type:`PyTypeObject` represents the Python time type; 45 it is the same object as :class:`datetime.time` in the Python layer. 46 47.. c:var:: PyTypeObject PyDateTime_DeltaType 48 49 This instance of :c:type:`PyTypeObject` represents Python type for 50 the difference between two datetime values; 51 it is the same object as :class:`datetime.timedelta` in the Python layer. 52 53.. c:var:: PyTypeObject PyDateTime_TZInfoType 54 55 This instance of :c:type:`PyTypeObject` represents the Python time zone info type; 56 it is the same object as :class:`datetime.tzinfo` in the Python layer. 57 58 59Macro for access to the UTC singleton: 60 61.. c:var:: PyObject* PyDateTime_TimeZone_UTC 62 63 Returns the time zone singleton representing UTC, the same object as 64 :attr:`datetime.timezone.utc`. 65 66 .. versionadded:: 3.7 67 68 69Type-check macros: 70 71.. c:function:: int PyDate_Check(PyObject *ob) 72 73 Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of 74 :c:data:`!PyDateTime_DateType`. *ob* must not be ``NULL``. This function always 75 succeeds. 76 77 78.. c:function:: int PyDate_CheckExact(PyObject *ob) 79 80 Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be 81 ``NULL``. This function always succeeds. 82 83 84.. c:function:: int PyDateTime_Check(PyObject *ob) 85 86 Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of 87 :c:data:`!PyDateTime_DateTimeType`. *ob* must not be ``NULL``. This function always 88 succeeds. 89 90 91.. c:function:: int PyDateTime_CheckExact(PyObject *ob) 92 93 Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not 94 be ``NULL``. This function always succeeds. 95 96 97.. c:function:: int PyTime_Check(PyObject *ob) 98 99 Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of 100 :c:data:`!PyDateTime_TimeType`. *ob* must not be ``NULL``. This function always 101 succeeds. 102 103 104.. c:function:: int PyTime_CheckExact(PyObject *ob) 105 106 Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be 107 ``NULL``. This function always succeeds. 108 109 110.. c:function:: int PyDelta_Check(PyObject *ob) 111 112 Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of 113 :c:data:`!PyDateTime_DeltaType`. *ob* must not be ``NULL``. This function always 114 succeeds. 115 116 117.. c:function:: int PyDelta_CheckExact(PyObject *ob) 118 119 Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be 120 ``NULL``. This function always succeeds. 121 122 123.. c:function:: int PyTZInfo_Check(PyObject *ob) 124 125 Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of 126 :c:data:`!PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This function always 127 succeeds. 128 129 130.. c:function:: int PyTZInfo_CheckExact(PyObject *ob) 131 132 Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be 133 ``NULL``. This function always succeeds. 134 135 136Macros to create objects: 137 138.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day) 139 140 Return a :class:`datetime.date` object with the specified year, month and day. 141 142 143.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond) 144 145 Return a :class:`datetime.datetime` object with the specified year, month, day, hour, 146 minute, second and microsecond. 147 148 149.. c:function:: PyObject* PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold) 150 151 Return a :class:`datetime.datetime` object with the specified year, month, day, hour, 152 minute, second, microsecond and fold. 153 154 .. versionadded:: 3.6 155 156 157.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond) 158 159 Return a :class:`datetime.time` object with the specified hour, minute, second and 160 microsecond. 161 162 163.. c:function:: PyObject* PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold) 164 165 Return a :class:`datetime.time` object with the specified hour, minute, second, 166 microsecond and fold. 167 168 .. versionadded:: 3.6 169 170 171.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds) 172 173 Return a :class:`datetime.timedelta` object representing the given number 174 of days, seconds and microseconds. Normalization is performed so that the 175 resulting number of microseconds and seconds lie in the ranges documented for 176 :class:`datetime.timedelta` objects. 177 178 179.. c:function:: PyObject* PyTimeZone_FromOffset(PyObject *offset) 180 181 Return a :class:`datetime.timezone` object with an unnamed fixed offset 182 represented by the *offset* argument. 183 184 .. versionadded:: 3.7 185 186 187.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name) 188 189 Return a :class:`datetime.timezone` object with a fixed offset represented 190 by the *offset* argument and with tzname *name*. 191 192 .. versionadded:: 3.7 193 194 195Macros to extract fields from date objects. The argument must be an instance of 196:c:type:`PyDateTime_Date`, including subclasses (such as 197:c:type:`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is 198not checked: 199 200.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o) 201 202 Return the year, as a positive int. 203 204 205.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o) 206 207 Return the month, as an int from 1 through 12. 208 209 210.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o) 211 212 Return the day, as an int from 1 through 31. 213 214 215Macros to extract fields from datetime objects. The argument must be an 216instance of :c:type:`PyDateTime_DateTime`, including subclasses. The argument 217must not be ``NULL``, and the type is not checked: 218 219.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o) 220 221 Return the hour, as an int from 0 through 23. 222 223 224.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o) 225 226 Return the minute, as an int from 0 through 59. 227 228 229.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o) 230 231 Return the second, as an int from 0 through 59. 232 233 234.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o) 235 236 Return the microsecond, as an int from 0 through 999999. 237 238 239.. c:function:: int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o) 240 241 Return the fold, as an int from 0 through 1. 242 243 .. versionadded:: 3.6 244 245 246.. c:function:: PyObject* PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o) 247 248 Return the tzinfo (which may be ``None``). 249 250 .. versionadded:: 3.10 251 252 253Macros to extract fields from time objects. The argument must be an instance of 254:c:type:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``, 255and the type is not checked: 256 257.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o) 258 259 Return the hour, as an int from 0 through 23. 260 261 262.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o) 263 264 Return the minute, as an int from 0 through 59. 265 266 267.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o) 268 269 Return the second, as an int from 0 through 59. 270 271 272.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o) 273 274 Return the microsecond, as an int from 0 through 999999. 275 276 277.. c:function:: int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o) 278 279 Return the fold, as an int from 0 through 1. 280 281 .. versionadded:: 3.6 282 283 284.. c:function:: PyObject* PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o) 285 286 Return the tzinfo (which may be ``None``). 287 288 .. versionadded:: 3.10 289 290 291Macros to extract fields from time delta objects. The argument must be an 292instance of :c:type:`PyDateTime_Delta`, including subclasses. The argument must 293not be ``NULL``, and the type is not checked: 294 295.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o) 296 297 Return the number of days, as an int from -999999999 to 999999999. 298 299 .. versionadded:: 3.3 300 301 302.. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o) 303 304 Return the number of seconds, as an int from 0 through 86399. 305 306 .. versionadded:: 3.3 307 308 309.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o) 310 311 Return the number of microseconds, as an int from 0 through 999999. 312 313 .. versionadded:: 3.3 314 315 316Macros for the convenience of modules implementing the DB API: 317 318.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args) 319 320 Create and return a new :class:`datetime.datetime` object given an argument 321 tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp`. 322 323 324.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args) 325 326 Create and return a new :class:`datetime.date` object given an argument 327 tuple suitable for passing to :meth:`datetime.date.fromtimestamp`. 328