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