DateTime Objects¶

Various date and time objects are supplied by thedatetime module.Before using any of these functions, the header filedatetime.h must beincluded in your source (note that this is not included byPython.h),and the macroPyDateTime_IMPORT must be invoked, usually as part ofthe module initialisation function. The macro puts a pointer to a C structureinto a static variable,PyDateTimeAPI, that is used by the followingmacros.

PyDateTime_IMPORT()¶

Import the datetime C API.

On success, populate thePyDateTimeAPI pointer.On failure, setPyDateTimeAPI toNULL and set an exception.The caller must check if an error occurred viaPyErr_Occurred():

PyDateTime_IMPORT;if(PyErr_Occurred()){/* cleanup */}

Warning

This is not compatible with subinterpreters.

typePyDateTime_CAPI¶

Structure containing the fields for the datetime C API.

The fields of this structure are private and subject to change.

Do not use this directly; preferPyDateTime_* APIs instead.

PyDateTime_CAPI*PyDateTimeAPI¶

Dynamically allocated object containing the datetime C API.

This variable is only available oncePyDateTime_IMPORT succeeds.

typePyDateTime_Date¶

This subtype ofPyObject represents a Python date object.

typePyDateTime_DateTime¶

This subtype ofPyObject represents a Python datetime object.

typePyDateTime_Time¶

This subtype ofPyObject represents a Python time object.

typePyDateTime_Delta¶

This subtype ofPyObject represents the difference between two datetime values.

PyTypeObjectPyDateTime_DateType¶

This instance ofPyTypeObject represents the Python date type;it is the same object asdatetime.date in the Python layer.

PyTypeObjectPyDateTime_DateTimeType¶

This instance ofPyTypeObject represents the Python datetime type;it is the same object asdatetime.datetime in the Python layer.

PyTypeObjectPyDateTime_TimeType¶

This instance ofPyTypeObject represents the Python time type;it is the same object asdatetime.time in the Python layer.

PyTypeObjectPyDateTime_DeltaType¶

This instance ofPyTypeObject represents the Python type forthe difference between two datetime values;it is the same object asdatetime.timedelta in the Python layer.

PyTypeObjectPyDateTime_TZInfoType¶

This instance ofPyTypeObject represents the Python time zone info type;it is the same object asdatetime.tzinfo in the Python layer.

Macro for access to the UTC singleton:

PyObject*PyDateTime_TimeZone_UTC¶

Returns the time zone singleton representing UTC, the same object asdatetime.timezone.utc.

Added in version 3.7.

Type-check macros:

intPyDate_Check(PyObject*ob)¶

Return true ifob is of typePyDateTime_DateType or a subtype ofPyDateTime_DateType.ob must not beNULL. This function alwayssucceeds.

intPyDate_CheckExact(PyObject*ob)¶

Return true ifob is of typePyDateTime_DateType.ob must not beNULL. This function always succeeds.

intPyDateTime_Check(PyObject*ob)¶

Return true ifob is of typePyDateTime_DateTimeType or a subtype ofPyDateTime_DateTimeType.ob must not beNULL. This function alwayssucceeds.

intPyDateTime_CheckExact(PyObject*ob)¶

Return true ifob is of typePyDateTime_DateTimeType.ob must notbeNULL. This function always succeeds.

intPyTime_Check(PyObject*ob)¶

Return true ifob is of typePyDateTime_TimeType or a subtype ofPyDateTime_TimeType.ob must not beNULL. This function alwayssucceeds.

intPyTime_CheckExact(PyObject*ob)¶

Return true ifob is of typePyDateTime_TimeType.ob must not beNULL. This function always succeeds.

intPyDelta_Check(PyObject*ob)¶

Return true ifob is of typePyDateTime_DeltaType or a subtype ofPyDateTime_DeltaType.ob must not beNULL. This function alwayssucceeds.

intPyDelta_CheckExact(PyObject*ob)¶

Return true ifob is of typePyDateTime_DeltaType.ob must not beNULL. This function always succeeds.

intPyTZInfo_Check(PyObject*ob)¶

Return true ifob is of typePyDateTime_TZInfoType or a subtype ofPyDateTime_TZInfoType.ob must not beNULL. This function alwayssucceeds.

intPyTZInfo_CheckExact(PyObject*ob)¶

Return true ifob is of typePyDateTime_TZInfoType.ob must not beNULL. This function always succeeds.

Macros to create objects:

PyObject*PyDate_FromDate(intyear,intmonth,intday)¶

Return value: New reference.

Return adatetime.date object with the specified year, month and day.

PyObject*PyDateTime_FromDateAndTime(intyear,intmonth,intday,inthour,intminute,intsecond,intusecond)¶

Return value: New reference.

Return adatetime.datetime object with the specified year, month, day, hour,minute, second and microsecond.

PyObject*PyDateTime_FromDateAndTimeAndFold(intyear,intmonth,intday,inthour,intminute,intsecond,intusecond,intfold)¶

Return value: New reference.

Return adatetime.datetime object with the specified year, month, day, hour,minute, second, microsecond and fold.

Added in version 3.6.

PyObject*PyTime_FromTime(inthour,intminute,intsecond,intusecond)¶

Return value: New reference.

Return adatetime.time object with the specified hour, minute, second andmicrosecond.

PyObject*PyTime_FromTimeAndFold(inthour,intminute,intsecond,intusecond,intfold)¶

Return value: New reference.

Return adatetime.time object with the specified hour, minute, second,microsecond and fold.

Added in version 3.6.

PyObject*PyDelta_FromDSU(intdays,intseconds,intuseconds)¶

Return value: New reference.

Return adatetime.timedelta object representing the given numberof days, seconds and microseconds. Normalization is performed so that theresulting number of microseconds and seconds lie in the ranges documented fordatetime.timedelta objects.

PyObject*PyTimeZone_FromOffset(PyObject*offset)¶

Return value: New reference.

Return adatetime.timezone object with an unnamed fixed offsetrepresented by theoffset argument.

Added in version 3.7.

PyObject*PyTimeZone_FromOffsetAndName(PyObject*offset,PyObject*name)¶

Return value: New reference.

Return adatetime.timezone object with a fixed offset representedby theoffset argument and with tznamename.

Added in version 3.7.

Macros to extract fields from date objects. The argument must be an instance ofPyDateTime_Date, including subclasses (such asPyDateTime_DateTime). The argument must not beNULL, and the type isnot checked:

intPyDateTime_GET_YEAR(PyDateTime_Date*o)¶

Return the year, as a positive int.

intPyDateTime_GET_MONTH(PyDateTime_Date*o)¶

Return the month, as an int from 1 through 12.

intPyDateTime_GET_DAY(PyDateTime_Date*o)¶

Return the day, as an int from 1 through 31.

Macros to extract fields from datetime objects. The argument must be aninstance ofPyDateTime_DateTime, including subclasses. The argumentmust not beNULL, and the type is not checked:

intPyDateTime_DATE_GET_HOUR(PyDateTime_DateTime*o)¶

Return the hour, as an int from 0 through 23.

intPyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime*o)¶

Return the minute, as an int from 0 through 59.

intPyDateTime_DATE_GET_SECOND(PyDateTime_DateTime*o)¶

Return the second, as an int from 0 through 59.

intPyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime*o)¶

Return the microsecond, as an int from 0 through 999999.

intPyDateTime_DATE_GET_FOLD(PyDateTime_DateTime*o)¶

Return the fold, as an int from 0 through 1.

Added in version 3.6.

PyObject*PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime*o)¶

Return the tzinfo (which may beNone).

Added in version 3.10.

Macros to extract fields from time objects. The argument must be an instance ofPyDateTime_Time, including subclasses. The argument must not beNULL,and the type is not checked:

intPyDateTime_TIME_GET_HOUR(PyDateTime_Time*o)¶

Return the hour, as an int from 0 through 23.

intPyDateTime_TIME_GET_MINUTE(PyDateTime_Time*o)¶

Return the minute, as an int from 0 through 59.

intPyDateTime_TIME_GET_SECOND(PyDateTime_Time*o)¶

Return the second, as an int from 0 through 59.

intPyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time*o)¶

Return the microsecond, as an int from 0 through 999999.

intPyDateTime_TIME_GET_FOLD(PyDateTime_Time*o)¶

Return the fold, as an int from 0 through 1.

Added in version 3.6.

PyObject*PyDateTime_TIME_GET_TZINFO(PyDateTime_Time*o)¶

Return the tzinfo (which may beNone).

Added in version 3.10.

Macros to extract fields from time delta objects. The argument must be aninstance ofPyDateTime_Delta, including subclasses. The argument mustnot beNULL, and the type is not checked:

intPyDateTime_DELTA_GET_DAYS(PyDateTime_Delta*o)¶

Return the number of days, as an int from -999999999 to 999999999.

Added in version 3.3.

intPyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta*o)¶

Return the number of seconds, as an int from 0 through 86399.

Added in version 3.3.

intPyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta*o)¶

Return the number of microseconds, as an int from 0 through 999999.

Added in version 3.3.

Macros for the convenience of modules implementing the DB API:

PyObject*PyDateTime_FromTimestamp(PyObject*args)¶

Return value: New reference.

Create and return a newdatetime.datetime object given an argumenttuple suitable for passing todatetime.datetime.fromtimestamp().

PyObject*PyDate_FromTimestamp(PyObject*args)¶

Return value: New reference.

Create and return a newdatetime.date object given an argumenttuple suitable for passing todatetime.date.fromtimestamp().

Internal data¶

The following symbols are exposed by the C API but should be consideredinternal-only.

PyDateTime_CAPSULE_NAME¶

Name of the datetime capsule to pass toPyCapsule_Import().

Internal usage only. UsePyDateTime_IMPORT instead.