Doc/c-api/datetime.rst

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