Date

Date fields store datetime values. Times are always stored in UTC, though with appropriate support packages installed (pytz and/or tzlocal) this can include timezone support.

Import

from marrow.mongo.field import Date

Inherits

marrow.mongo:Field

Available

>=1.1.2

Attributes

This field type inherits all Field attributes and represents a singular, scalar date/time value.

naive

Timezone to interpret naive `datetime` objects as utilizing.

Defaultutc

Added>=1.1.3

tz

Timezone to cast to when retrieving from the database.

Default()

Added>=1.1.3

Timezone references as utilized by the above may be any of:

• The constant string "naive", resulting in no timezone transformation or alteration of the tzinfo attribute at all.

• The constant string "local", auto-detecting the host's timezone, requiring the package localtz be installed. This is most useful if you use datetime.now() instead of datetime.utcnow()—please consider updating your code to utilize the UTC variant in preference to this.

• A tzinfo object, such as those provided by the pytz package.

Any use of timezone awareness will require the pytz package be installed, as Python's built-in tzinfo objects suffer a number of issues. Note also that use of timezones comes with a performance penalty.

Usage

Instantiate and assign an instance of this class during construction of a new Document subclass. Accessing as a class attribute will return a Queryable allowing filtering operations, and access as an instance attribute will return a datetime cast value.

Date fields are highly aware of date-like objects and how to apply them. For example, you may provide any of the following in place of a pure datetime value:

• Any MutableMapping instance (such as a dict or Document instance) with an _id key whose value is an ObjectId. The date/time value will be pulled automatically from the _id.generation_time.

• A bare BSON ObjectId instance, behaving as above.

• A datetime.timedelta instance whose value will be immediately applied (added to) the result of datetime.utcnow().

• A datetime instance.

Examples

Typecasting Behaviour and Querying

A key reason for the above typecasting allowances are to permit natural comparison against those types of objects as admittedly, it'll be unlikely you'll need to populate a date from the ID of a record.

Given a Date field named modified, you can identify all documents modified in the last 30 days easily and without performing date math yourself: (remembering that the value being queried for becomes static after that comparison)

query = Asset.modified >= timedelta(days=-30)
Asset.find(query)