Objetos DateTime

Vários objetos de data e hora são fornecidos pelo módulo datetime. Antes de usar qualquer uma dessas funções, o arquivo de cabeçalho datetime.h deve ser incluído na sua fonte (observe que isso não é incluído por Python.h) e a macro PyDateTime_IMPORT deve ser chamada, geralmente como parte da função de inicialização do módulo. A macro coloca um ponteiro para uma estrutura C em uma variável estática, PyDateTimeAPI, usada pelas macros a seguir.

PyDateTime_IMPORT()

Importa a API C de datetime.

Em caso de sucesso, preenche o ponteiro PyDateTimeAPI. Em caso de falha, define PyDateTimeAPI como NULL e lança uma exceção. O chamador deve verificar se ocorreu um erro através de PyErr_Occurred():

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

Aviso

Isso não é compatível com subinterpretadores.

type PyDateTime_CAPI

Estrutura contendo os campos para a API C de datetime.

Os campos desta estrutura são privados e sujeitos a alterações.

Não use isto diretamente; prefira as APIs PyDateTime_*.

PyDateTime_CAPI *PyDateTimeAPI

Objeto alocado dinamicamente contendo a API C de datetime.

Esta variável só estará disponível após a execução bem-sucedida de PyDateTime_IMPORT.

type PyDateTime_Date

Esta é uma instância de PyObject representando o objeto data do Python.

type PyDateTime_DateTime

Esta é uma instância de PyObject representando o objeto datetime do Python.

type PyDateTime_Time

Esta é uma instância de PyObject representando o objeto hora do Python.

type PyDateTime_Delta

Esta é uma instância de PyObject representando a diferença entre dois valores de datetime.

PyTypeObject PyDateTime_DateType

Esta instância de PyTypeObject representa o tipo data do Python; é o mesmo objeto que datetime.date na camada de Python.

PyTypeObject PyDateTime_DateTimeType

Esta instância de PyTypeObject representa o tipo datetime do Python; é o mesmo objeto que datetime.datetime na camada de Python.

PyTypeObject PyDateTime_TimeType

Esta instância de PyTypeObject representa o tipo hora do Python; é o mesmo objeto que datetime.time na camada de Python.

PyTypeObject PyDateTime_DeltaType

Esta instância de PyTypeObject representa o tipo Python para a diferença entre dois valores de datetime; é o mesmo objeto que datetime.timedelta na camada de Python.

PyTypeObject PyDateTime_TZInfoType

Esta instância de PyTypeObject representa o tipo fuso horário do Python; é o mesmo objeto que datetime.tzinfo na camada de Python.

Macro para acesso ao singleton UTC:

PyObject *PyDateTime_TimeZone_UTC

Retorna um singleton do fuso horário representando o UTC, o mesmo objeto que datetime.timezone.utc.

Adicionado na versão 3.7.

Macros de verificação de tipo:

int PyDate_Check(PyObject *ob)

Retorna verdadeiro se ob for do tipo PyDateTime_DateType ou um subtipo de PyDateTime_DateType. ob não deve ser NULL. Esta função sempre tem sucesso.

int PyDate_CheckExact(PyObject *ob)

Retorna verdadeiro se ob for do tipo PyDateTime_DateType. ob não deve ser NULL. Esta função sempre tem sucesso.

int PyDateTime_Check(PyObject *ob)

Retorna verdadeiro se ob é do tipo PyDateTime_DateTimeType ou um subtipo de PyDateTime_DateTimeType. ob não deve ser NULL. Esta função sempre tem sucesso.

int PyDateTime_CheckExact(PyObject *ob)

Retorna verdadeiro se ob for do tipo PyDateTime_DateTimeType. ob não deve ser NULL. Esta função sempre tem sucesso.

int PyTime_Check(PyObject *ob)

Retorna verdadeiro se ob é do tipo PyDateTime_TimeType ou um subtipo de PyDateTime_TimeType. ob não deve ser NULL. Esta função sempre tem sucesso.

int PyTime_CheckExact(PyObject *ob)

Retorna verdadeiro se ob for do tipo PyDateTime_TimeType. ob não deve ser NULL. Esta função sempre tem sucesso.

int PyDelta_Check(PyObject *ob)

Retorna verdadeiro se ob for do tipo PyDateTime_DeltaType ou um subtipo de PyDateTime_DeltaType. ob não pode ser NULL. Esta função sempre tem sucesso.

int PyDelta_CheckExact(PyObject *ob)

Retorna verdadeiro se ob for do tipo PyDateTime_DeltaType. ob não deve ser NULL. Esta função sempre tem sucesso.

int PyTZInfo_Check(PyObject *ob)

Retorna verdadeiro se ob for do tipo PyDateTime_TZInfoType ou um subtipo de PyDateTime_TZInfoType. ob não pode ser NULL. Esta função sempre tem sucesso.

int PyTZInfo_CheckExact(PyObject *ob)

Retorna verdadeiro se ob for do tipo PyDateTime_TZInfoType. ob não deve ser NULL. Esta função sempre tem sucesso.

Macros para criar objetos:

PyObject *PyDate_FromDate(int year, int month, int day)
Retorna valor: Nova referência.

Retorna um objeto datetime.date com o ano, mês e dia especificados.

PyObject *PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
Retorna valor: Nova referência.

Retorna um objeto datetime.datetime com o ano, mês, dia, hora, minuto, segundo, microssegundo especificados.

PyObject *PyDateTime_FromDateAndTimeAndFold(int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
Retorna valor: Nova referência.

Retorna um objeto datetime.datetime com o ano, mês, dia, hora, minuto, segundo, microssegundo e a dobra especificados.

Adicionado na versão 3.6.

PyObject *PyTime_FromTime(int hour, int minute, int second, int usecond)
Retorna valor: Nova referência.

Retorna um objeto datetime.time com a hora, minuto, segundo e microssegundo especificados.

PyObject *PyTime_FromTimeAndFold(int hour, int minute, int second, int usecond, int fold)
Retorna valor: Nova referência.

Retorna um objeto datetime.time com a hora, minuto, segundo, microssegundo e a dobra especificados.

Adicionado na versão 3.6.

PyObject *PyDelta_FromDSU(int days, int seconds, int useconds)
Retorna valor: Nova referência.

Retorna um objeto datetime.timedelta representando o número especificado de dias, segundos e microssegundos. A normalização é realizada para que o número resultante de microssegundos e segundos esteja nos intervalos documentados para objetos de datetime.timedelta.

PyObject *PyTimeZone_FromOffset(PyObject *offset)
Retorna valor: Nova referência.

Retorna um objeto datetime.timezone com um deslocamento fixo sem nome representado pelo argumento offset.

Adicionado na versão 3.7.

PyObject *PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)
Retorna valor: Nova referência.

Retorna um objeto datetime.timezone com um deslocamento fixo representado pelo argumento offset e com tzname name.

Adicionado na versão 3.7.

Macros para extrair campos de objetos date. O argumento deve ser uma instância de PyDateTime_Date, inclusive subclasses (como PyDateTime_DateTime). O argumento não deve ser NULL, e o tipo não é verificado:

int PyDateTime_GET_YEAR(PyDateTime_Date *o)

Retorna o ano, como um inteiro positivo.

int PyDateTime_GET_MONTH(PyDateTime_Date *o)

Retorna o mês, como um inteiro de 1 a 12.

int PyDateTime_GET_DAY(PyDateTime_Date *o)

Retorna o dia, como um inteiro de 1 a 31.

Macros para extrair campos de objetos datetime. O argumento deve ser uma instância de PyDateTime_DateTime, inclusive subclasses. O argumento não deve ser NULL, e o tipo não é verificado:

int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)

Retorna a hora, como um inteiro de 0 a 23.

int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)

Retorna o minuto, como um inteiro de 0 a 59.

int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)

Retorna o segundo, como um inteiro de 0 a 59.

int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)

Retorna o microssegundo, como um inteiro de 0 a 999999.

int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)

Retorna a dobra, como um inteiro de 0 a 1.

Adicionado na versão 3.6.

PyObject *PyDateTime_DATE_GET_TZINFO(PyDateTime_DateTime *o)

Retorna o tzinfo (que pode ser None).

Adicionado na versão 3.10.

Macros para extrair campos de objetos time. O argumento deve ser uma instância de PyDateTime_Time, inclusive subclasses. O argumento não deve ser NULL, e o tipo não é verificado:

int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)

Retorna a hora, como um inteiro de 0 a 23.

int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)

Retorna o minuto, como um inteiro de 0 a 59.

int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)

Retorna o segundo, como um inteiro de 0 a 59.

int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)

Retorna o microssegundo, como um inteiro de 0 a 999999.

int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)

Retorna a dobra, como um inteiro de 0 a 1.

Adicionado na versão 3.6.

PyObject *PyDateTime_TIME_GET_TZINFO(PyDateTime_Time *o)

Retorna o tzinfo (que pode ser None).

Adicionado na versão 3.10.

Macros para extrair campos de objetos time delta. O argumento deve ser uma instância de PyDateTime_Delta, inclusive subclasses. O argumento não deve ser NULL, e o tipo não é verificado:

int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)

Retorna o número de dias, como um inteiro de -999999999 a 999999999.

Adicionado na versão 3.3.

int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)

Retorna o número de segundos, como um inteiro de 0 a 86399.

Adicionado na versão 3.3.

int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)

Retorna o número de microssegundos, como um inteiro de 0 a 999999.

Adicionado na versão 3.3.

Macros para a conveniência de módulos implementando a API de DB:

PyObject *PyDateTime_FromTimestamp(PyObject *args)
Retorna valor: Nova referência.

Cria e retorna um novo objeto datetime.datetime dado uma tupla de argumentos que possa ser passada ao método datetime.datetime.fromtimestamp().

PyObject *PyDate_FromTimestamp(PyObject *args)
Retorna valor: Nova referência.

Cria e retorna um novo objeto datetime.date dado uma tupla de argumentos que possa ser passada ao método datetime.date.fromtimestamp().

Dados internos

Os seguintes símbolos são expostos pela API C, mas devem ser considerados apenas para uso interno.

PyDateTime_CAPSULE_NAME

Nome da cápsula de datetime a ser passada para PyCapsule_Import().

Uso interno apenas. Use PyDateTime_IMPORT em vez disso.