This is a restructuring of the datetime documentation to hopefully make
them more user-friendly and approachable to new users without losing any
of the detail.
Changes include:
- Creating dedicated subsections for some concepts such as:
- "Constants"
- "Naive vs Aware"
- "Determining if an Object is Aware"
- Give 'naive vs aware' its own subsection
- Give 'constants' their own subsection
- Overhauling the strftime-strptime section by:
- Breaking it into logical, linkable, and digestable parts
- Adding a high-level comparison table
- Moving the technical detail to bottom: readers come to this
section primarily to remind themselves to things:
- How do I write the format code for X?
- strptime/strftime: which one is which again?
- Touching up fromisoformat + isoformat sections by:
- Revising fromisoformat + isoformat for date, time, and
datetime
- Adding basic examples
- Enforcing consistency about putting formats (i.e. ``HH:MM``)
in double backticks. This was previously done in some places
but not all
- Putting long 'supported formats', on their own line to improve
readability
- Moving the 'seealso' section to the top and add a link to dateutil
Rationale: This doesn't really belong nested under the
'constants' section. Let readers know right away that
datetime is one of several related tools.
- Moving common features of several types into one place:
Previously, each type went out of its way to note separately
that it was hashable and picklable. These can be brought
into one single place that is more prominent.
- Reducing some verbose explanations to improve readability
- Breaking up long paragraphs into digestable chunks
- Displaying longer "equivalent to" examples, as short code blocks
- Using the dot notation for datetime/time classes:
Use :class:`.time` and :class:`.datetime` rather than :class:`time` and
:class:`datetime`; otherwise, the generated links will route to the
respective modules, not classes.
- Rewording the tzinfo class description
The top paragraph should get straight to the point of telling the reader
what subclasses of tzinfo _do_. Previously, that was hidden in a later
paragraph.
- Adding a note on .today() versus .now()
- Rearranging and expanding example blocks, including:
- Moved long, multiline inline examples to standalone examples
- Simplified the example block for timedelta arithmetic:
- Broke the example into two logical sections:
1. normalization/parameter 'merging'
2. timedelta arithmetic
- Reduced the complexity of the some of the examples. Show
reasonable, real-world uses cases that are easy to follow
along with and progres in difficult slightly.
- Broke up the example sections for date and datetime sections by putting
the easy examples first, progressing to more esoteric situations and
breaking it up into logical sections based on what the methods are
doing at a high level.
- Simplified the KabulTz example:
- Put the class definition itself into a non-REPL block since there is
no interactive output involved there
- Briefly explained what's happening before launching into the code
- Broke the example section into visually separate chunks
- Various whitespace, formatting, style and grammar fixes including:
- Consistently using backctics for 'date_string' formats
- Consistently using one space after periods.
- Consistently using bold for vocab terms
- Consistently using italics when referring to params:
See https://devguide.python.org/documenting/GH-id4
- Using '::' to lead into code blocks
Per https://devguide.python.org/documenting/GH-source-code, this will
let the reader use the 'expand/collapse' top-right button for REPL
blocks to hide or show the prompt.
- Using consistent captialization schemes
- Removing use of the default role
- Put 'example' blocks in Markdown subsections
This is a combination of 66 commits.
See bpo-36960: https://bugs.python.org/issue36960
(cherry picked from commit 3fb1363fe8)
Co-authored-by: Brad <brad.solomon.1124@gmail.com>
Adds a link to `dateutil.parser.isoparse` in the documentation.
It would be nice to set up intersphinx for things like this, but I think we can leave that for a separate PR.
CC: @pitrou
[bpo-37979](https://bugs.python.org/issue37979)
https://bugs.python.org/issue37979
Automerge-Triggered-By: @pitrou
(cherry picked from commit 59725f3bad)
Co-authored-by: Paul Ganssle <paul@ganssle.io>
"Arguments may be integers... " could be misunderstand as they also
could be strings.
New wording makes it clear that arguments have to be integers.
modified: Doc/library/datetime.rst
Automerge-Triggered-By: @pganssle
(cherry picked from commit c5218fce02)
Co-authored-by: Jürgen Gmach <juergen.gmach@googlemail.com>
Automerge-Triggered-By: @pganssle
For datetime.datetime.strptime(), the leading zero for some two-digit formats is optional.
This adds a footnote to the strftime/strptime documentation to reflect this fact, and adds some tests to ensure that it is true.
bpo-34903
(cherry picked from commit 6b9c204ee7)
Co-authored-by: Mike Gleen <mike.gleen@gmail.com>
* Improve example on tzinfo instances
Move from GMTX to TZX when naming the classes, as GMT1 might be rather
confusing as seen in the reported issue.
In addition, move to UTC over GMT and improve the tzname implementation.
* Simplify datetime with tzinfo example
Move the example in the documentation to just use timezone.utc and a
user defined Kabul timezone rather than having two user defined
timezones with DST.
Kabul timezone is still interesting as it changes its offset but not
based on DST. This is more accurate as the previous example was missing
information about the fold attribute. Additionally, implementing the fold
attribute was rather complex and probably not relevant enough for the
section "datetime with tzinfo".
A datetime object d is aware if d.tzinfo is not None and
d.tzinfo.utcoffset(d) does not return None. If d.tzinfo is None,
or if d.tzinfo is not None but d.tzinfo.utcoffset(d) returns None,
d is naive.
This commit ensures that instances with non-None d.tzinfo, but
d.tzinfo.utcoffset(d) returning None are treated as naive.
In addition, C acceleration code will raise TypeError if
d.tzinfo.utcoffset(d) returns an object with the type other than
timedelta.
* Updated the documentation.
Assume that the term "naive" is defined elsewhere and remove the
not entirely correct clarification. Thanks, Tim.
* Closes issue bpo-5288: Allow tzinfo objects with sub-minute offsets.
* bpo-5288: Implemented %z formatting of sub-minute offsets.
* bpo-5288: Removed mentions of the whole minute limitation on TZ offsets.
* bpo-5288: Removed one more mention of the whole minute limitation.
Thanks @csabella!
* Fix a formatting error in the docs
* Addressed review comments.
Thanks, @haypo.
Added an optional argument timespec to the datetime isoformat() method
to choose the precision of the time component.
Original patch by Alessandro Cucci.
* Various sections were pointing to the section on the string.Formatter
class, when the section on the common format string syntax is probably more
appropriate
* Fix references to various format() functions and methods
* Nested replacement fields may contain conversions and format specifiers,
and this is tested; see Issue #19729 for instance
Miss Islington (bot)
Mario Corchero
Abhishek Kumar Singh
Paul Ganssle
Yasser A
Alexey Izbyshev
Serhiy Storchaka
Gus Goulart
Christophe Nanteuil
Danish Prakash
Farhaan Bukhsh
Alexander Belopolsky
Utkarsh Upadhyay
Mario Corchero
wim glenn
delirious-lettuce
Marco Buttu
Xiang Zhang
Raymond Hettinger
Alexander Belopolsky
Terry Jan Reedy
Berker Peksag
Martin Panter