Commit Graph

156 Commits

Author SHA1 Message Date
Mathieu Dupuy 2e76820a50
Reword aware/naive introduction sentence (GH-20175)
This is more informative and avoids the question of whether the period should go inside or outside the quotation marks.

See also GH-20007.
2020-05-21 16:26:27 -04:00
Mathieu Dupuy 4eba67783e
Doc: move a dot outside double quotes (GH-20007) 2020-05-17 23:24:59 +02:00
Paul Ganssle 1b97b9b0ad
bpo-24416: Return named tuple from date.isocalendar() (GH-20113)
{date, datetime}.isocalendar() now return a private custom named tuple object
IsoCalendarDate rather than a simple tuple.

In order to leave IsocalendarDate as a private class and to improve what
backwards compatibility is offered for pickling the result of a
datetime.isocalendar() call, add a __reduce__ method to the named tuples that
reduces them to plain tuples. (This is the part of this PR most likely to cause
problems — if it causes major issues, switching to a strucseq or equivalent
would be prudent).

The pure python implementation of IsoCalendarDate uses positional-only
arguments, since it is private and only constructed by position anyway; the
equivalent change in the argument clinic on the C side would require us to move
the forward declaration of the type above the clinic import for whatever
reason, so it seems preferable to hold off on that for now.

bpo-24416: https://bugs.python.org/issue24416

Original PR by Dong-hee Na with only minor alterations by Paul Ganssle.

Co-authored-by: Dong-hee Na <donghee.na92@gmail.com>
2020-05-16 10:02:59 -04:00
Michael Morehouse e7b406f4e2 [typo] fix dupe in datetime.fromisoformat docs (GH-17295)
Fixes a nearly word for word duplication of a sentence that appears
earlier in the caution section of datetime.datetime.fromisoformat in
Doc/Library/datetime.rst.

No issue created as it's a trivial change.

Automerge-Triggered-By: @pganssle
2019-12-23 06:37:47 -08:00
cocoatomo 068768faf6 Add missing markup (GH-17680)
"HH", "MM" and "ffffff" are enclosed with double back quotes, but "SS" is left being bare
2019-12-22 09:46:45 -08:00
Ofek Lev 575d0b46d1 Fix typos (GH-17423) 2019-11-30 21:44:21 -08:00
Karl Dubost bc441ed7c1 bpo-22377: Fixes documentation for %Z in datetime (GH-16507)
This fixes the issue discussed in https://bugs.python.org/issue22377
and fixes it according to the comments made by Paul Ganssle @pganssle

* It clarifies which values are acceptable in the table
* It extends the note with a clearer information on the valid values


https://bugs.python.org/issue22377
2019-11-26 08:38:41 -08:00
Joannah Nanjekye 1a53c785e6 bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() (GH-15773)
https://bugs.python.org/issue37488



Automerge-Triggered-By: @pganssle
2019-09-11 06:58:42 -07:00
Brad 3fb1363fe8 Overhaul datetime documentation (GH-13410)
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/#id4
    - Using '::' to lead into code blocks
        Per https://devguide.python.org/documenting/#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
2019-09-11 10:19:05 +01:00
Paul Ganssle 59725f3bad bpo-37979: Add alternative to fromisoformat in documentation (GH-15596)
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
2019-08-29 07:47:48 -07:00
Jürgen Gmach c5218fce02 Clarify argument types in datetime docs. (GH-15459)
"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
2019-08-24 12:48:55 -07:00
Mike Gleen 6b9c204ee7 bpo-34903: Document that some strptime formats only require 1 digit (GH-14149)
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
2019-06-18 19:14:57 +01:00
Mario Corchero f0b5ae4567 bpo-30699: Improve example on datetime tzinfo instances (GH-4290)
* 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".
2019-06-04 17:18:10 +02:00
Abhishek Kumar Singh 56027ccd6b bpo-19376: Added doc mentioning `datetime.strptime()` without a year fails for Feb 29. (GH-10243) 2019-05-18 16:36:19 -04:00
Paul Ganssle 88c0937056 bpo-36004: Add date.fromisocalendar (GH-11888)
This commit implements the first version of date.fromisocalendar, the
inverse function for date.isocalendar.
2019-04-29 15:22:03 +02:00
Yasser A f40b4a0b62 bpo-36138: Clarify docs about converting datetime.timedelta to scalars. (GH-12137)
Be explicit that timedelta division converts an overall duration to the interval
units given by the denominator.
2019-03-16 13:56:58 +10:00
Alexey Izbyshev 1cffd0eed3 bpo-34512: Document platform-specific strftime() behavior for non-ASCII format strings (GH-8948) 2019-01-12 19:21:54 +02:00
Serhiy Storchaka 3f819ca138
bpo-35110: Fix unintentional spaces around hyphens and dashes. (GH-10231) 2018-10-31 02:26:06 +02:00
Gus Goulart c0799ec973 bpo-27741: Better wording for datetime.strptime() (GH-9994) 2018-10-29 12:49:52 +01:00
Serhiy Storchaka 913876d824
bpo-35054: Add yet more index entries for symbols. (GH-10121) 2018-10-28 13:41:26 +02:00
Serhiy Storchaka ddb961d2ab
bpo-35054: Add more index entries for symbols. (GH-10064) 2018-10-26 09:00:49 +03:00
Christophe Nanteuil 92878829c3 bpo-34158: Documentation UTC offset update (GH-8377)
* Documentation of UTC offset update
Since changes in the UTC offset that allows sub-minute offsets, the documentation needs update:

- "%z" format code documentation update
Karthikeyan Singaravelan commented on bugs.python.org:
Added as part of 018d353c1c and a fix regarding duplicate words for that part was added at bac2d5ba30.
Relevant format string at https://github.com/python/cpython/pull/2896/files#diff-25e2d173c84057d069b7890450714eddR214.
Relevant test case with 6-digit string for microsecond : https://github.com/python/cpython/pull/2896/files#diff-acc40bec51c7de832de3361db3edae52R309.
Table at https://docs.python.org/3.7/library/datetime.html#strftime-and-strptime-behavior could also be updated with microseconds being optional in the second column
%z | UTC offset in the form ±HHMM[SS] (empty string if the object is naive). | (empty), +0000, -0400, +1030

- isoformat documentation update
According to me, needs confirmation:
Relevant format string at https://github.com/python/cpython/pull/4699/files#diff-25e2d173c84057d069b7890450714eddR176
Relevant test case at https://github.com/python/cpython/pull/4699/files#diff-25e2d173c84057d069b7890450714edd

* From Martin Panter: some style improvment;
From @pganssle: using f for fractional part of seconds in all file.
2018-10-05 18:57:02 -04:00
Danish Prakash 9c223794c7 bpo-34365: Update date object documentation (GH-8814)
Python 3.x does not fall back to comparing object addresses when comparing two `dt` objects.

<!-- issue-number: [bpo-34365](https://www.bugs.python.org/issue34365) -->
https://bugs.python.org/issue34365
<!-- /issue-number -->
2018-09-11 13:59:23 -07:00
Farhaan Bukhsh 5b6e49a139 bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348)
This commit fixes the -timedelta overfllow issue not documented properly.

Signed-off-by: Farhaan Bukhsh <farhaan.bukhsh@gmail.com>
2018-07-04 19:42:05 +01:00
Alexander Belopolsky 877b23202b
bpo-33812: Corrected astimezone for naive datetimes. (GH-7578)
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.
2018-06-10 17:02:58 -04:00
Serhiy Storchaka bac2d5ba30
Fix duplicating words words. (GH-6296)
Most of them have been added in 3.7.
2018-03-28 22:14:26 +03:00
Paul Ganssle 09dc2f508c bpo-15873: Implement [date][time].fromisoformat (#4699)
Closes bpo-15873.
2017-12-21 00:33:49 -05:00
Utkarsh Upadhyay 843ea47a03 bpo-31545: Update documentation containing timedelta repr. (GH-3687)
This is a fix to the documentation to reflect the changes merged
in as part of bpo-30302.
2017-10-27 14:25:15 +03:00
Mario Corchero 32318930da Closes bpo-31800: Support for colon when parsing time offsets (#4015)
Add support to strptime to parse time offsets with a colon between the hour and the minutes.
2017-10-25 20:35:41 -04:00
Alexander Belopolsky 018d353c1c Closes issue bpo-5288: Allow tzinfo objects with sub-minute offsets. (#2896)
* 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.
2017-07-31 10:26:50 -04:00
Utkarsh Upadhyay 8e45318b0d bpo-30302: Update WhatsNew and documentation. (#2929)
* Update 'Porting to .37' section.

* Fix a minor example in the doc.
2017-07-28 14:42:56 +02:00
Utkarsh Upadhyay cc5a65cd90 bpo-30302 Make timedelta.__repr__ more informative. (#1493) 2017-07-25 23:51:33 +02:00
wim glenn 53f2af1655 bpo-30583: Fix typo in datetime dateutil documentation (GH-1972)
Replace `datetuil` into `dateutil`
2017-06-06 10:54:41 -07:00
delirious-lettuce c7b3f0fc3b Remove trailing semicolon in datetime doc example (GH-1653) 2017-05-18 18:01:00 -07:00
Marco Buttu 909a6f626f bpo-27200: Fix doctests in programming.rst and datetime.rst (#401) 2017-03-18 19:59:33 +03:00
Xiang Zhang b8a1aebb3d Issue #29078: Merge 3.5. 2016-12-27 12:30:42 +08:00
Xiang Zhang 6721c7c3b2 Issue #29078: Add the missing import in datetime.time doc example.
Patch by Dhushyanth Ramasamy.
2016-12-27 12:23:59 +08:00
Serhiy Storchaka ee1b01a41b Issue #21818: Fixed references to classes that have names matching with module
names.
2016-12-02 23:13:53 +02:00
Serhiy Storchaka b6a6b45458 Issue #21818: Fixed references to classes that have names matching with module
names.
2016-12-02 23:15:22 +02:00
Raymond Hettinger 15f44ab043 Issue #27895: Spelling fixes (Contributed by Ville Skyttä). 2016-08-30 10:47:49 -07:00
Alexander Belopolsky 53868aaabb Closes #27595: Document PEP 495 (Local Time Disambiguation) features. 2016-08-24 18:30:16 -04:00
Alexander Belopolsky 43746c3770 Closes #27661: Added tzinfo keyword argument to datetime.combine. 2016-08-02 17:49:30 -04:00
Terry Jan Reedy 4da945f361 Merge Issue #22558. 2016-06-11 15:06:08 -04:00
Terry Jan Reedy fa089b9b0b Issue #22558: Add remaining doc links to source code for Python-coded modules.
Reformat header above separator line (added if missing) to a common format.
Patch by Yoni Lavi.
2016-06-11 15:02:54 -04:00
Berker Peksag 94f89a6e02 Fix typos in datetime documentation. 2016-06-04 21:36:53 -07:00
Martin Panter f157982b2c Issue #27076: More doc and comment spelling fixes for 3.6, by Ville Skyttä 2016-05-26 06:03:33 +00:00
Serhiy Storchaka 1acbf853c8 Issue #26736: Used HTTPS for external links in the documentation if possible. 2016-05-07 10:49:58 +03:00
Serhiy Storchaka 6dff0205b7 Issue #26736: Used HTTPS for external links in the documentation if possible. 2016-05-07 10:49:07 +03:00
Berker Peksag 9fc385748c Issue #26957: Remove duplicate 'the' from datetime documentation
Patch by Alex Chan.
2016-05-04 23:26:04 +03:00
Berker Peksag bace976db1 Issue #26957: Remove duplicate 'the' from datetime documentation
Patch by Alex Chan.
2016-05-04 23:25:44 +03:00