Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

bpo-45335: Add note to sqlite3 docs about "timestamp" converter #29200

Merged
merged 2 commits into from
Oct 29, 2021
Merged

bpo-45335: Add note to sqlite3 docs about "timestamp" converter #29200

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6b37eb6
bpo-45335: Add note to `sqlite3` docs about "timestamp" converter
iafisher Oct 24, 2021
e8572f7
Address comments from reviewers
iafisher Oct 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions Doc/library/sqlite3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1049,6 +1049,17 @@ If a timestamp stored in SQLite has a fractional part longer than 6
numbers, its value will be truncated to microsecond precision by the
timestamp converter.

.. warning::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We avoid using warnings in documentation. Instead we describe behavior using affirmative tone.


The "timestamp" converter ignores UTC offsets in the database and always
returns a naive :class:`datetime.datetime` object, so if you read a timestamp
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Outside of tutorials and howtos, we avoid addressing the reader as "you", instead using a style where the "you" is implied. Instead of saying:

If you want X, do Y.

simply say:

To achieve X, do Y.

Copy link
Contributor

@erlend-aasland erlend-aasland Oct 28, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, I'd drop that part of the sentence. The first part already says that UTC offsets are ignored; no need to exemplify it. How about something like this:

    The "timestamp" converter ignores UTC offsets in the database and always 
    returns a naive :class:`datetime.datetime` object. To preserve UTC offsets
    in timestamps, either leave converters disabled, or register offset-aware
    converters with :func:`register_converter`.

from the database with converters enabled and then write it back, any UTC
offset will be lost.

If you need to preserve UTC offsets in timestamps, then either leave
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similarly, instead of if..then just say "To preserve... either... or". This way you avoid the explicit "you".

converters disabled, or register your own offset-aware converter with
:func:`register_converter` to override the default one.


.. _sqlite3-controlling-transactions:

Expand Down