Buildfest Feedback: Suggested improvements for datetime docs

XMLWordPrintableJSON

    • Type: Improvement
    • Resolution: Duplicate
    • Priority: Unknown
    • None
    • Affects Version/s: None
    • Component/s: Docs
    • None
    • Hide

      This should clarify how it works:

      By default, all timestamps are inserted into the database without any timezone info. The server stores these as if they have UTC timezones, even though the actual timestamp is not necessarily in the UTC timezone. If you insert a timestamp such as datetime.datetime.now(), it will represent a local time in your timezone but without any timezone info, and the database will store it as if it's from the UTC timezone.

      With tz_aware=True, timezones are preserved: any timestamp that is inserted with a timezone will be stored with that timezone. Timestamps without explicit timezone info will still be stored with the UTC timezone, regardless of their original timezone.

      Show
      This should clarify how it works: By default, all timestamps are inserted into the database without any timezone info. The server stores these as if they have UTC timezones, even though the actual timestamp is not necessarily in the UTC timezone. If you insert a timestamp such as datetime.datetime.now(), it will represent a local time in your timezone but without any timezone info, and the database will store it as if it's from the UTC timezone. With tz_aware=True, timezones are preserved: any timestamp that is inserted with a timezone will be stored with that timezone. Timestamps without explicit timezone info will still be stored with the UTC timezone, regardless of their original timezone.
    • None
    • None
    • None
    • None
    • None
    • None

      Context

      https://pymongo.readthedocs.io/en/stable/api/bson/index.html#dt2 mentions that datetime.datetime instances are treated as naive, but doesn't explain what that means. It may be helpful to link to https://docs.python.org/3/library/datetime.html#aware-and-naive-objects for context. https://pymongo.readthedocs.io/en/stable/examples/datetimes.html also refers to "aware" in a similar vein.

      https://pymongo.readthedocs.io/en/stable/examples/datetimes.html says PyMongo assumes datetimes are naive (i.e. no timezone info) and will interpret the time as UTC. I found that I needed to use datetime.datetime.utcfromtimestamp instead of fromtimestamp when constructing a datetime from a UNIX timestamp; otherwise I ended up storing a local time (by the numbers, e.g. 5:30pm) with a UTC timezone.

      I understand PyMongo uses the native datetime type as a convenience, but the edge cases around timezone handling definitely seem like something that can trip up a new user. We would have a similar challenge in PHP if we used the built-in DateTime class instead of having our own UTCDateTime.

      Acceptance Criteria

       

            Assignee:
            Unassigned
            Reporter:
            Jeremy Mikola
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: