Returning native datetime objects for Bucket/Blob time properties.

[dhermes]

Note this was almost in #793 but dropped due to RFC3339 questions.

@craigcitro @thobrla can you vet an assumption for me? Will timestamps returned conform to

_GOOGLE_TIMESTAMP_FORMAT = '%Y-%m-%dT%H:%M:%S.%fZ'
# For example
TIME_DELETED = '2014-11-05T20:34:37.000Z'

I ask because '2014-11-05T20:34:37Z' is also totally valid according to RFC3339 and I'm wondering if we can get away with using datetime alone (and not having to use the strict-rfc3339 library for the full generality of RFC3339).

[coveralls]

Changes Unknown when pulling 9f7d6fc on dhermes:use-native-datetime into * on GoogleCloudPlatform:master*.

[thobrla]

I think this is true, but it is an implementation detail so it could break in the future; the discovery document only claims this is in RFC3339 format.

That being said, apitools just uses protorpc, which uses datetime exclusively. @craigcitro may be able to comment further; looking at the code we treat the timestamps as DateTimeFields, https://github.com/google/protorpc/blob/master/protorpc/message_types.py#L52, but these are in millisecond format, not RFC3339 and I can't find where it does the string conversion.

[dhermes]

@thobrla The conversion happens in apitools

[thobrla]

Ah; the responsible code is actually in protorpc, and that handles both kinds of string formats (using text search and strptime). That seems like a reasonable approach.

[dhermes]

Yes, I'm cool doing that (only because we will end up requiring protorpc via apitools anyhow).

[craigcitro]

one more heads-up about timestamps: some newer APIs (eg pubsub) may return you timestamps with even more precision. i.e. down to the nanosecond. (see source here)

[dhermes]

@craigcitro WAT? datetime doesn't support nanoseconds, so I suppose I should hold off. Oh Google, le sigh.

[craigcitro]

well, your fix is still good for storage. we can cross the next bridge when we come to it.

[dhermes]

@craigcitro You mean this PR is good or the suggestion to use protorpc.util.decode_datetime?

As it were, I can confirm that the timezone support and the option of not having milliseconds (the only extra features) are not necessary.

From the discovery type documentation:

Type value	Format value	Meaning
string	date-time	An RFC3339 timestamp in UTC time. This is formatted as YYYY-MM-DDThh:mm:ss.fffZ. The milliseconds portion (".fff") is optional. Defined in the JSON Schema spec.

[dhermes]

@tseaver I made an update to the unit tests and also made a slight tweak to the use of mtime in Blob.download_to_filename (was some repeated code).

PTAL

[coveralls]

Changes Unknown when pulling 2645e1d on dhermes:use-native-datetime into * on GoogleCloudPlatform:master*.

[tseaver]

LGTM