Uploaded image for project: 'Python Driver'
  1. Python Driver
  2. PYTHON-3448

Buildfest Feedback: Suggested improvements for datetime docs

    • Type: Icon: Improvement Improvement
    • Resolution: Unresolved
    • Priority: Icon: Unknown Unknown
    • 4.8
    • Affects Version/s: None
    • Component/s: Docs
    • Labels:

      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.

            Unassigned Unassigned
            jmikola@mongodb.com Jeremy Mikola
            0 Vote for this issue
            1 Start watching this issue