Skip to content

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

Merged
ambv merged 2 commits into
python:mainfrom
iafisher:sqlite3-docs
Oct 29, 2021
Merged

bpo-45335: Add note to sqlite3 docs about "timestamp" converter#29200
ambv merged 2 commits into
python:mainfrom
iafisher:sqlite3-docs

Conversation

@iafisher

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

Copy link
Copy Markdown
Contributor

@the-knights-who-say-ni

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

Copy link
Copy Markdown

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
Comment threadDoc/library/sqlite3.rst Outdated
numbers, its value will be truncated to microsecond precision by the
timestamp converter.

.. warning::

@ambvambvOct 28, 2021

Copy link
Copy Markdown
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.

Comment threadDoc/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

@ambvambvOct 28, 2021

Copy link
Copy Markdown
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.

@erlend-aaslanderlend-aaslandOct 28, 2021•
edited
Loading

Copy link
Copy Markdown
Contributor

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

Comment threadDoc/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

@ambvambvOct 28, 2021

Copy link
Copy Markdown
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".

@bedevere-bot

bedevere-bot commented Oct 28, 2021

Copy link
Copy Markdown

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

iafisher commented Oct 28, 2021

Copy link
Copy Markdown
ContributorAuthor

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

bedevere-bot commented Oct 28, 2021

Copy link
Copy Markdown

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

@erlend-aaslanderlend-aasland left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM. Thanks!

@iafisher

iafisher commented Oct 28, 2021

Copy link
Copy Markdown
ContributorAuthor

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

@erlend-aasland

erlend-aasland commented Oct 28, 2021•
edited
Loading

Copy link
Copy Markdown
Contributor

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

iafisher commented Oct 28, 2021

Copy link
Copy Markdown
ContributorAuthor

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

@ambv
ambv merged commit 3877fc0 into python:mainOct 29, 2021
@miss-islington

miss-islington commented Oct 29, 2021

Copy link
Copy Markdown
Contributor

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

bedevere-bot commented Oct 29, 2021

Copy link
Copy Markdown

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

bedevere-bot commented Oct 29, 2021

Copy link
Copy Markdown

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 berkerpeksag
@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