# 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](https://github.com/marrow/mongo/tree/128b1ec81ec6a48e05a95c32b636deede377854b/reference/field/field.md#attributes) and represents a singular, scalar date/time value.

#### `naive`

Timezone to interpret naive \`datetime\` objects as utilizing.

Default`utc`

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)

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mongo.webcore.io/reference/fields/date.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.