Datas e Horários

Terminologia

O Python utiliza um tipo de dados dedicado, datetime.datetime, para representar datas e horas. O MongoDB armazena valores datetime no tempo universal coordenado (UTC), um padrão de hora global local para Londres, Inglaterra.

datetime(2002, 10, 27, 14, 0, 0)

datetime(2002, 10, 27, 6, 0,
         tzinfo=<DstTzInfo 'US/Pacific' PST-1 day, 16:00:00 STD>)

from datetime import datetime
from pytz import timezone
utc_datetime = datetime(2002, 10, 27, 6, 0, 0)
pacific = timezone("US/Pacific")
local_datetime = pacific.localize(utc_datetime)
print(f"UTC datetime: {utc_datetime}")
print(f"Local datetime: {local_datetime}")

UTC datetime: 2002-10-27 06:00:00
Local datetime: 2002-10-27 06:00:00-08:00

Data/hora UTC ingnua

Por padrão, o PyMongo recupera valores UTC datetime sem informações adicionais. O exemplo de código a seguir recupera o documento de amostra e imprime o valor datetime. O valor impresso é idêntico ao do documento de amostra . Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:

from datetime import datetime
collection = database["sample_collection"]
find_result = collection.find_one()["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 14:00:00
datetime.tzinfo: None

from datetime import datetime
collection = database["sample_collection"]
find_result = (await collection.find_one())["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 14:00:00
datetime.tzinfo: None

Data hora UTC ciente

Para instruir o PyMongo a recuperar um valor de datetime ciente, crie um objeto CodecOptions e passe tz_aware = True para o construtor. Em seguida, passe o objeto CodecOptions para o método get_collection() .

O exemplo de código a seguir recupera o valor datetime do documento de exemplo como um datetime ciente. Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:

from pymongo import MongoClient
from datetime import datetime
from bson.codec_options import CodecOptions
options = CodecOptions(tz_aware = True)
collection = database.get_collection("sample_collection", options)
find_result = collection.find_one()["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 14:00:00+00:00
datetime.tzinfo: <bson.tz_util.FixedOffset object at 0x104db2b80>

from pymongo import MongoClient
from datetime import datetime
from bson.codec_options import CodecOptions
options = CodecOptions(tz_aware = True)
collection = database.get_collection("sample_collection", options)
find_result = (await collection.find_one())["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 14:00:00+00:00
datetime.tzinfo: <bson.tz_util.FixedOffset object at 0x104db2b80>

Data e hora localizada

Se você planeja mostrar valores datetime para o usuário, poderá instruir o PyMongo a converter automaticamente todos os horários lidos do MongoDB para um fuso horário específico. Para fazer isso, crie um objeto timezone para o fuso horário de destino, conforme descrito na seção Terminologia . Em seguida, crie um objeto CodecOptions e passe os seguintes argumentos para o construtor:

• tz_aware: Defina como True.

• tzinfo: O objeto timezone .

O exemplo de código a seguir recupera o documento de amostra, mas usa os argumentos tz_aware e tzinfo para localizar automaticamente o valor datetime para o zona horário "US/Pacific". Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:

from pymongo import MongoClient
from datetime import datetime
from bson.codec_options import CodecOptions
import pytz
from pytz import timezone
pacific = timezone("US/Pacific")
options = CodecOptions(tz_aware = True, tzinfo = pacific)
collection = database.get_collection("sample_collection", options)
find_result = collection.find_one()["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 06:00:00-08:00
datetime.tzinfo: US/Pacific

from pymongo import MongoClient
from datetime import datetime
from bson.codec_options import CodecOptions
import pytz
from pytz import timezone
pacific = timezone("US/Pacific")
options = CodecOptions(tz_aware = True, tzinfo = pacific)
collection = database.get_collection("sample_collection", options)
find_result = (await collection.find_one())["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 06:00:00-08:00
datetime.tzinfo: US/Pacific

DatetimeConversion.DATETIME

DatetimeConversion.DATETIME é o valor padrão. Esse valor faz com que o PyMongo gere um erro ao tentar decodificar uma data fora do intervalo, como mostrado no exemplo a seguir:

from datetime import datetime
from bson import encode, decode
from bson.datetime_ms import DatetimeMS
out_of_range = DatetimeMS(-(2**62))
val = encode({"date": out_of_range})
decoded = decode(val)
print(decoded)

...
bson.errors.InvalidBSON: year -146136543 is out of range (Consider Using
CodecOptions(datetime_conversion=DATETIME_AUTO) or
MongoClient(datetime_conversion='DATETIME_AUTO')).
...

DatetimeConversion.DATETIME_MS

Esse valor instrui o PyMongo a retornar somente DatetimeMS objetos, mesmo que a data esteja dentro do intervalo de datetime:

from datetime import datetime
from bson import encode, decode
from bson.datetime_ms import DatetimeMS
from bson.codec_options import CodecOptions, DatetimeConversion
val = encode({"date": datetime(1970, 1, 2)})
codec_ms = CodecOptions(datetime_conversion=DatetimeConversion.DATETIME_MS)
decoded = decode(val, codec_options=codec_ms)
print(decoded)

{"date": DatetimeMS(86400000)}

DatetimeConversion.DATETIME_AUTO

Esse valor instrui o PyMongo a retornar objetos datetime se o valor estiver dentro do intervalo datetime e a retornar um objeto DatetimeMS caso contrário. O seguinte exemplo de código codifica e decodifica uma data/hora no intervalo datetime e uma fora do intervalo:

from datetime import datetime
from bson import encode, decode
from bson.datetime_ms import DatetimeMS
from bson.codec_options import CodecOptions, DatetimeConversion
in_range = encode({"date": datetime(1970, 1, 1)})
out_of_range = encode({"date": DatetimeMS(-(2**62))})
codec_auto = CodecOptions(datetime_conversion=DatetimeConversion.DATETIME_AUTO)
in_decoded = decode(in_range, codec_options=codec_auto)
out_decoded = decode(out_of_range, codec_options=codec_auto)
print(f"in-range date: {in_decoded}")
print(f"out-of-range date: {out_decoded}")

in-range date: {"date": datetime.datetime(1970, 1, 1, 0, 0)}
out-of-range date: {'x': DatetimeMS(-4611686018427387904)}

DatetimeConversion.DATETIME_CLAMP

Esse valor "grampeia" os objetos datetime resultantes, forçando-os a estar dentro do intervalo datetime (cortado para 999 000 microssegundos).

O exemplo de código a seguir codifica e decodifica uma data/hora anterior ao intervalo datetime e uma data/hora posterior ao intervalo datetime . Os valores resultantes estão no início e no final do intervalo permitido.

from datetime import datetime
from bson import encode, decode
from bson.datetime_ms import DatetimeMS
from bson.codec_options import CodecOptions, DatetimeConversion
before = encode({"date": DatetimeMS(-(2**62))})
after = encode({"date": DatetimeMS(2**62)})
codec_clamp = CodecOptions(datetime_conversion=DatetimeConversion.DATETIME_CLAMP)
before_decoded = decode(before, codec_options=codec_clamp)
after_decoded = decode(after, codec_options=codec_clamp)
print(f"datetime before the range: {before_decoded}")
print(f"datetime after the range: {after_decoded}")

datetime before the range: {"date": datetime.datetime(1, 1, 1, 0, 0)}
datetime after the range: {"date": datetime.datetime(9999, 12, 31, 23, 59, 59, 999000)}

OverflowError ao decodificar datas armazenadas pelo driver de outro idioma

O PyMongo decodifica valores BSON datetime para instâncias da classe datetime.datetime do Python. As instâncias de datetime.datetime estão limitadas a anos entre datetime.MINYEAR (1) e datetime.MAXYEAR (9999). Alguns drivers do MongoDB podem armazenar datas BSON com valores de ano muito fora dos suportados por datetime.datetime.

Existem algumas maneiras de contornar esse problema. Começando com o PyMongo 4.3, bson.decode pode decodificar valores BSON datetime de quatro maneiras. Você pode especificar o método de conversão usando o parâmetro datetime_conversion de ~bson.codec_options.CodecOptions.

A opção de conversão padrão é ~bson.codec_options.DatetimeConversion.DATETIME, que tentará decodificar o valor como datetime.datetime, permitindo que ~builtin.OverflowError ocorra em datas fora do intervalo. ~bson.codec_options.DatetimeConversion.DATETIME_AUTO altera esse comportamento para retornar ~bson.datetime_ms.DatetimeMS quando as representações estão fora do intervalo, enquanto retorna objetos ~datetime.datetime como antes. Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:

from datetime import datetime
from bson.datetime_ms import DatetimeMS
from bson.codec_options import DatetimeConversion
from pymongo import MongoClient
client = MongoClient(datetime_conversion=DatetimeConversion.DATETIME_AUTO)
client.db.collection.insert_one({"x": datetime(1970, 1, 1)})
client.db.collection.insert_one({"x": DatetimeMS(2**62)})
for x in client.db.collection.find():
   print(x)

{'_id': ObjectId('...'), 'x': datetime.datetime(1970, 1, 1, 0, 0)}
{'_id': ObjectId('...'), 'x': DatetimeMS(4611686018427387904)}

from datetime import datetime
from bson.datetime_ms import DatetimeMS
from bson.codec_options import DatetimeConversion
from pymongo import MongoClient
client = AsyncMongoClient(datetime_conversion=DatetimeConversion.DATETIME_AUTO)
await client.db.collection.insert_one({"x": datetime(1970, 1, 1)})
await client.db.collection.insert_one({"x": DatetimeMS(2**62)})
async for x in client.db.collection.find():
   print(x)

{'_id': ObjectId('...'), 'x': datetime.datetime(1970, 1, 1, 0, 0)}
{'_id': ObjectId('...'), 'x': DatetimeMS(4611686018427387904)}

Para outras opções, consulte a documentação API para a classe DatetimeConversion.

Outra opção que não envolve a configuração datetime_conversion é filtrar valores de documento fora do intervalo suportado por ~datetime.datetime. Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:

from datetime import datetime
coll = client.test.dates
cur = coll.find({'dt': {'$gte': datetime.min, '$lte': datetime.max}})

from datetime import datetime
coll = client.test.dates
cur = coll.find({'dt': {'$gte': datetime.min, '$lte': datetime.max}})

Se você não precisar do valor de datetime, poderá filtrar apenas esse campo. Selecione a aba Synchronous ou Asynchronous para ver o código correspondente:

cur = coll.find({}, projection={'dt': False})

cur = coll.find({}, projection={'dt': False})