Skip to content

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

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

Jump to bottom
Merged
ambv merged 2 commits into from
Oct 29, 2021
Merged

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

ambv merged 2 commits into from
Oct 29, 2021

Conversation

@iafisher
Copy link
Contributor

@iafisheriafisher commented Oct 24, 2021•
edited by bedevere-bot
Loading

@the-knights-who-say-ni
Copy link

the-knights-who-say-ni commented Oct 24, 2021

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

CLA Missing

Our records indicate the following people have not signed the CLA:

@iafisher

For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

If you have recently signed the CLA, please wait at least one business day
before our records are updated.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

@bedevere-botbedevere-bot added the docs Documentation in the Doc dir label Oct 24, 2021
ambv
ambv requested changes Oct 28, 2021
View reviewed changes
Doc/library/sqlite3.rst Outdated
numbers, its value will be truncated to microsecond precision by the
timestamp converter.

.. warning::
Copy link
Contributor

@ambvambvOct 28, 2021

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.

Doc/library/sqlite3.rst Outdated
.. warning::

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

@ambvambvOct 28, 2021

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-aaslanderlend-aaslandOct 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`.

Doc/library/sqlite3.rst Outdated
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

@ambvambvOct 28, 2021

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".

@bedevere-bot
Copy link

bedevere-bot commented Oct 28, 2021

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

@iafisher
Copy link
ContributorAuthor

iafisher commented Oct 28, 2021

I have made the requested changes; please review again.

Thank you for the review. I have used Erlend's wording with minor changes.

@bedevere-bot
Copy link

bedevere-bot commented Oct 28, 2021

Thanks for making the requested changes!

@ambv: please review the changes made to this pull request.

erlend-aasland
erlend-aasland approved these changes Oct 28, 2021
View reviewed changes
Copy link
Contributor

@erlend-aaslanderlend-aasland left a comment

Choose a reason for hiding this comment

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

LGTM. Thanks!

@iafisher
Copy link
ContributorAuthor

iafisher commented Oct 28, 2021

Should I backport this to older versions of Python as well? Is there documentation on how to do that?

@erlend-aasland
Copy link
Contributor

erlend-aasland commented Oct 28, 2021•
edited
Loading

Should I backport this to older versions of Python as well? Is there documentation on how to do that?

Thanks for the reminder! I've added backport labels for @miss-islington :)

The devguide has a section about backporting.

@iafisher
Copy link
ContributorAuthor

iafisher commented Oct 28, 2021

Thanks! Hopefully it can be backported automatically, but if not I'll check out the devguide.

@ambvambv merged commit 3877fc0 into python:mainOct 29, 2021
@miss-islington
Copy link
Contributor

miss-islington commented Oct 29, 2021

Thanks @iafisher for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Oct 29, 2021
@iafisher@miss-islington
bpo-45335: Add note tosqlite3docs about "timestamp" converter (py…
b1b563b
…thonGH-29200) (cherry picked from commit 3877fc0) Co-authored-by: Ian Fisher <ian@iafisher.com>
@bedevere-botbedevere-bot removed the needs backport to 3.10 only security fixes label Oct 29, 2021
@bedevere-bot
Copy link

bedevere-bot commented Oct 29, 2021

GH-29319 is a backport of this pull request to the 3.10 branch.

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Oct 29, 2021
@iafisher@miss-islington
bpo-45335: Add note tosqlite3docs about "timestamp" converter (py…
ef4f47f
…thonGH-29200) (cherry picked from commit 3877fc0) Co-authored-by: Ian Fisher <ian@iafisher.com>
@bedevere-bot
Copy link

bedevere-bot commented Oct 29, 2021

GH-29320 is a backport of this pull request to the 3.9 branch.

ambv pushed a commit that referenced this pull request Oct 29, 2021
@miss-islington@iafisher
bpo-45335: Add note tosqlite3docs about "timestamp" converter (GH…
8ea665c
…-29200) (GH-29319) (cherry picked from commit 3877fc0) Co-authored-by: Ian Fisher <ian@iafisher.com>
ambv pushed a commit that referenced this pull request Oct 29, 2021
@miss-islington@iafisher
bpo-45335: Add note tosqlite3docs about "timestamp" converter (GH…
e156031
…-29200) (GH-29320) (cherry picked from commit 3877fc0) Co-authored-by: Ian Fisher <ian@iafisher.com>
@iafisheriafishermannequin mentioned this pull request May 16, 2022
Closed
@erlend-aaslanderlend-aasland mentioned this pull request Jul 27, 2022
Closed
5 tasks
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@erlend-aaslanderlend-aaslanderlend-aasland approved these changes

@berkerpeksagberkerpeksagAwaiting requested review from berkerpeksagberkerpeksag is a code owner

@ambvambvAwaiting requested review from ambv

Assignees

No one assigned

Labels

docsDocumentation in the Doc dirskip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@iafisher@the-knights-who-say-ni@bedevere-bot@erlend-aasland@miss-islington@ambv