* This just copies the docs from `StreamWriter` and `StreamReader`.
* Add docstring for asyncio functions.
https://bugs.python.org/issue36889
Automerge-Triggered-By: @asvetlov
(cherry picked from commit d31b31516c)
Co-authored-by: Xtreak <tir.karthi@gmail.com>
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>
Three internal cpython events were not documented, yet.
Signed-off-by: Christian Heimes <christian@python.org>
https://bugs.python.org/issue37363
(cherry picked from commit ed4b3216e5)
Co-authored-by: Christian Heimes <christian@python.org>
* Add a note to the PyModule_AddObject docs.
* Correct example usages of PyModule_AddObject.
* Whitespace.
* Clean up wording.
* 📜🤖 Added by blurb_it.
* First code review.
* Add < 0 in the tests with PyModule_AddObject
(cherry picked from commit 224b8aaa7e)
Co-authored-by: Brandt Bucher <brandtbucher@gmail.com>
Does no longer work since Sphinx moved the trim_doctest_flag option in
the configuration.
(cherry picked from commit 2c910c1e73)
Co-authored-by: Julien Palard <julien@palard.fr>
Prefer client or TLSv1_2 in examples
Signed-off-by: Christian Heimes <christian@python.org>
(cherry picked from commit 894d0f7d55)
Co-authored-by: Christian Heimes <christian@python.org>
* bpo-13927: time.ctime and time.asctime return string explantion
* Add note explaining that time.ctime and time.asctime returns a space padded date value in case it contains a single digit date
* Reformat linebreaks
(cherry picked from commit 2d32bf1ef2)
Co-authored-by: Harmandeep Singh <harmandeep.singh1@delhivery.com>
* bpo-36260: Add pitfalls to zipfile module documentation
We saw vulnerability warning description (including zip bomb) in Doc/library/xml.rst file.
This gave us the idea of documentation improvement.
So, we moved a little bit forward :P
And the doc patch can be found (pr).
* fix trailing whitespace
* 📜🤖 Added by blurb_it.
* Reformat text for consistency.
(cherry picked from commit 3ba51d587f)
Co-authored-by: JunWei Song <sungboss2004@gmail.com>
Since they have been removed from cgi it's useful to remind people where they
can be found instead.
(cherry picked from commit 1abf54336f)
Co-authored-by: Simon Willison <swillison@gmail.com>
* Document `unittest.IsolatedAsyncioTestCase` API
* Add a simple example with respect to order of evaluation of setup and teardown calls.
https://bugs.python.org/issue32972
Automerge-Triggered-By: @asvetlov
(cherry picked from commit 6a9fd66f6e)
Co-authored-by: Xtreak <tir.karthi@gmail.com>
In text mode, the "size" parameter indicates the number of characters, not bytes.
(cherry picked from commit faff81c05f)
Co-authored-by: William Andrea <william.j.andrea@gmail.com>
Update the docs as patch can now return an AsyncMock if the patched
object is an async function.
(cherry picked from commit f5e7f39d29)
Co-authored-by: Mario Corchero <mcorcherojim@bloomberg.net>
This PR deprecate explicit loop parameters in all public asyncio APIs
This issues is split to be easier to review.
fourth step: queue.py
https://bugs.python.org/issue36373
(cherry picked from commit 9008be303a)
Co-authored-by: Emmanuel Arias <emmanuelarias30@gmail.com>
This PR deprecate explicit loop parameters in all public asyncio APIs
This issues is split to be easier to review.
Third step: locks.py
https://bugs.python.org/issue36373
(cherry picked from commit 537877d85d)
Co-authored-by: Emmanuel Arias <emmanuelarias30@gmail.com>
* bpo-351428: Updates documentation to reflect AsyncMock call_count after await.
* Adds skip and fixes warning.
* Removes extra >>>.
* Adds ... in front of await mock().
(cherry picked from commit b9f65f01fd)
Co-authored-by: Lisa Roach <lisaroach14@gmail.com>
The "A4" pdfs were previously the wrong size due to a change in the options in Sphinx 1.5.
See also sphinx-doc/sphinxGH-5235
(cherry picked from commit b5381f6697)
Authored-by: Jean-François B <jfbu@free.fr>
The link we have points to the version from Unicode 6.0.0, dated 2010.
There have been numerous updates to it since then:
https://www.unicode.org/reports/tr44/GH-Modifications
Change the link to one that points to the current version. Also, use HTTPS.
(cherry picked from commit 64c6ac74e2)
Co-authored-by: Greg Price <gnprice@gmail.com>
The purpose of the `unicodedata.is_normalized` function is to answer
the question `str == unicodedata.normalized(form, str)` more
efficiently than writing just that, by using the "quick check"
optimization described in the Unicode standard in UAX GH-15.
However, it turns out the code doesn't implement the full algorithm
from the standard, and as a result we often miss the optimization and
end up having to compute the whole normalized string after all.
Implement the standard's algorithm. This greatly speeds up
`unicodedata.is_normalized` in many cases where our partial variant
of quick-check had been returning MAYBE and the standard algorithm
returns NO.
At a quick test on my desktop, the existing code takes about 4.4 ms/MB
(so 4.4 ns per byte) when the partial quick-check returns MAYBE and it
has to do the slow normalize-and-compare:
$ build.base/python -m timeit -s 'import unicodedata; s = "\uf900"*500000' \
-- 'unicodedata.is_normalized("NFD", s)'
50 loops, best of 5: 4.39 msec per loop
With this patch, it gets the answer instantly (58 ns) on the same 1 MB
string:
$ build.dev/python -m timeit -s 'import unicodedata; s = "\uf900"*500000' \
-- 'unicodedata.is_normalized("NFD", s)'
5000000 loops, best of 5: 58.2 nsec per loop
This restores a small optimization that the original version of this
code had for the `unicodedata.normalize` use case.
With this, that case is actually faster than in master!
$ build.base/python -m timeit -s 'import unicodedata; s = "\u0338"*500000' \
-- 'unicodedata.normalize("NFD", s)'
500 loops, best of 5: 561 usec per loop
$ build.dev/python -m timeit -s 'import unicodedata; s = "\u0338"*500000' \
-- 'unicodedata.normalize("NFD", s)'
500 loops, best of 5: 512 usec per loop
(cherry picked from commit 2f09413947)
Co-authored-by: Greg Price <gnprice@gmail.com>
* Fix suspicious.py to actually print the unused rules
* Fix the other `self.warn` calls
(cherry picked from commit e1786b5416)
Co-authored-by: Anthony Sottile <asottile@umich.edu>
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>
- drop TargetScopeError in favour of raising SyntaxError directly
as per the updated PEP 572
- comprehension iteration variables are explicitly local, but
named expression targets in comprehensions are nonlocal or
global. Raise SyntaxError as specified in PEP 572
- named expression targets in the outermost iterable of a
comprehension have an ambiguous target scope. Avoid resolving
that question now by raising SyntaxError. PEP 572
originally required this only for cases where the bound name
conflicts with the iteration variable in the comprehension,
but CPython can't easily restrict the exception to that case
(as it doesn't know the target variable names when visiting
the outermost iterator expression)
(cherry picked from commit 5dbe0f59b7)
"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
Fix typo in description of link to mozilla bug report writing guidelines.
Though the URL is misleading, we're indeed trying to write bug _reports_, not to add bugs.
Automerge-Triggered-By: @ned-deily
(cherry picked from commit e17f201cd9)
Co-authored-by: Antoine <43954001+awecx@users.noreply.github.com>
bpo-37834: Normalise handling of reparse points on Windows
* ntpath.realpath() and nt.stat() will traverse all supported reparse points (previously was mixed)
* nt.lstat() will let the OS traverse reparse points that are not name surrogates (previously would not traverse any reparse point)
* nt.[l]stat() will only set S_IFLNK for symlinks (previous behaviour)
* nt.readlink() will read destinations for symlinks and junction points only
bpo-1311: os.path.exists('nul') now returns True on Windows
* nt.stat('nul').st_mode is now S_IFCHR (previously was an error)
Added back mention that ensure_future actually scheduled obj. This documentation just mentions what ensure_future returns, so I did not realize that ensure_future also schedules obj.
(cherry picked from commit 092911d5c0)
Co-authored-by: Roger Iyengar <ri@rogeriyengar.com>
Fixed wrong link to Telnet.open() method in telnetlib documentation.
(cherry picked from commit e0b6117e27)
Co-authored-by: Michael Anckaert <michael.anckaert@sinax.be>
The documented definition was much broader than the real one:
there are tons of characters with general category "Other",
and we don't (and shouldn't) treat most of them as whitespace.
Rewrite the definition to agree with the comment on
_PyUnicode_IsWhitespace, and with the logic in makeunicodedata.py,
which is what generates that function and so ultimately governs.
Add suitable breadcrumbs so that a reader who wants to pin down
exactly what this definition means (what's a "bidirectional class"
of "B"?) can do so. The `unicodedata` module documentation is an
appropriate central place for our references to Unicode's own copious
documentation, so point there.
Also add to the isspace() test a thorough check that the
implementation agrees with the intended definition.
Because mod, func, class, etc all share one namespace, :func:time creates a link to the time module doc page rather than the time.time function.
(cherry picked from commit 1b1d0514ad)
Co-authored-by: Éric Araujo <merwok@netwok.org>
Automerge-Triggered-By: @merwok
https://bugs.python.org/issue37814:
> The empty tuple syntax in type annotations, `Tuple[()]`, is not obvious from the examples given in the documentation (I naively expected `Tuple[]` to work); it has been documented in PEP 484 and in mypy, but not in the documentation for the typing module.
https://bugs.python.org/issue37814
(cherry picked from commit 8a784af750)
Co-authored-by: Josh Holland <anowlcalledjosh@gmail.com>
* bpo-32912: Revert warnings for invalid escape sequences.
DeprecationWarning will continue to be emitted for invalid escape sequences in string and bytes literals in 3.8 just as it did in 3.7.
SyntaxWarning may be emitted in the future. But per mailing list discussion, we don't yet know when because we haven't settled on how to do so in a non-disruptive manner.
* add a missing ``.. availability::`` reST explicit markup;
* more consistent "see man page" sentences.
(cherry picked from commit cfebfef2de)
Co-authored-by: Géry Ogam <gery.ogam@gmail.com>
* Remove suggestion that is less relevant now that global lookups are much faster
* Add link for installing the recipes
(cherry picked from commit adf02b36b3)
Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
There was a discrepancy between the Python and C implementations.
Add singletons ALWAYS_EQ, LARGEST and SMALLEST in test.support
to test mixed type comparison.
(cherry picked from commit 17e52649c0)
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Expose the CAN_BCM SocketCAN constants used in the bcm_msg_head struct
flags (provided by <linux/can/bcm.h>) under the socket library.
This adds the following constants with a CAN_BCM prefix:
* SETTIMER
* STARTTIMER
* TX_COUNTEVT
* TX_ANNOUNCE
* TX_CP_CAN_ID
* RX_FILTER_ID
* RX_CHECK_DLC
* RX_NO_AUTOTIMER
* RX_ANNOUNCE_RESUME
* TX_RESET_MULTI_IDX
* RX_RTR_FRAME
* CAN_FD_FRAME
The CAN_FD_FRAME flag was introduced in the 4.8 kernel, while the other
ones were present since SocketCAN drivers were mainlined in 2.6.25. As
such, it is probably unnecessary to guard against these constants being
missing.
(cherry picked from commit 31c4fd2a10)
Co-authored-by: karl ding <karlding@users.noreply.github.com>
* bpo-33821: Update IDLE section of What's New 3.7
* Fix roles.
(cherry picked from commit 5982b7201b)
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
Prior to this change the guard on an 'elif' used an assignment expression whose value was used in a later 'else' block, causing some confusion for people.
(Discussion on Twitter: https://twitter.com/brettsky/status/1153861041068994566.)
Automerge-Triggered-By: @brettcannon
(cherry picked from commit 544fa15ea1)
Co-authored-by: Tzu-ping Chung <uranusjr@gmail.com>
* Fix the formatting in the documentation of the tostring() functions.
* bpo-34160: Document that the tostring() and tostringlist() functions also preserve the attribute order now.
* bpo-34160: Add an explanation of how users should deal with the attribute order.
(cherry picked from commit a3697db010)
Co-authored-by: Stefan Behnel <stefan_ml@behnel.de>
Move the Editors and IDE section out of the Unix section, to its own section.
https://bugs.python.org/issue37610
(cherry picked from commit 8f040b7a9f)
Co-authored-by: aldwinaldwin <aldwinaldwin@users.noreply.github.com>
Add a brief note to indicate that any new required attributes must go through the PEP process.
https://bugs.python.org/issue37284
(cherry picked from commit 52693c10e8)
Co-authored-by: Giovanni Cappellotto <gcappellotto@fb.com>
The `allow_abbrev` option for ArgumentParser is documented and intended to disable support for unique prefixes of --options, which may sometimes be ambiguous due to deferred parsing.
However, the initial implementation also broke parsing of grouped short flags, such as `-ab` meaning `-a -b` (or `-a=b`). Checking the argument for a leading `--` before rejecting it fixes this.
This was prompted by pytest-dev/pytestGH-5469, so a backport to at least 3.8 would be great 😄
And this is my first PR to CPython, so please let me know if I've missed anything!
https://bugs.python.org/issue26967
(cherry picked from commit dffca9e925)
Co-authored-by: Zac Hatfield-Dodds <Zac-HD@users.noreply.github.com>
Hi,
I've faced an issue w/ `mailbox.Maildir()`. The case is following:
1. I create a folder with `tempfile.TemporaryDirectory()`, so it's empty
2. I pass that folder path as an argument when instantiating `mailbox.Maildir()`
3. Then I receive an exception happening because "there's no such file or directory" (namely `cur`, `tmp` or `new`) during interaction with Maildir
**Expected result:** subdirs are created during `Maildir()` instance creation.
**Actual result:** subdirs are assumed as existing which leads to exceptions during use.
**Workaround:** remove the actual dir before passing the path to `Maildir()`. It will be created automatically with all subdirs needed.
**Fix:** This PR. Basically it adds creation of subdirs regardless of whether the base dir existed before.
https://bugs.python.org/issue30088
(cherry picked from commit e44184749c)
Co-authored-by: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Fix importlib examples to insert any newly created modules via importlib.util.module_from_spec() immediately into sys.modules instead of after calling loader.exec_module().
Thanks to Benjamin Mintz for finding the bug.
https://bugs.python.org/issue37521
(cherry picked from commit 0827064c95)
Co-authored-by: Brett Cannon <54418+brettcannon@users.noreply.github.com>
https://bugs.python.org/issue37521
This is done to compensate for the extra stack frames added by
IDLE itself, which cause problems when setting the recursion limit
to low values.
This wraps sys.setrecursionlimit() and sys.getrecursionlimit()
as invisibly as possible.
(cherry picked from commit fcf1d003bf)
Co-authored-by: Tal Einat <taleinat+github@gmail.com>
The distutils bdist_wininst command is now deprecated, use
bdist_wheel (wheel packages) instead.
(cherry picked from commit 1da4462765)
Co-authored-by: Victor Stinner <vstinner@redhat.com>
bdist_wininst depends on MBCS codec, unavailable on non-Windows,
and bdist_wininst have not worked since at least Python 3.2, possibly
never on Python 3.
Here we document that bdist_wininst is only supported on Windows,
and we mark it unsupported otherwise to skip tests.
Distributors of Python 3 can now safely drop the bdist_wininst .exe files
without the need to skip bdist_wininst related tests.
(cherry picked from commit 72cd653c4e)
Co-authored-by: Miro Hrončok <miro@hroncok.cz>
Add PyCode_NewEx to be used internally and set PyCode_New as a compatibility wrapper
(cherry picked from commit 4a2edc34a4)
Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>
* Added documentation for textwrap.dedent behavior.
* Remove an obsolete note about pre-2.5 behavior from the docstring.
(cherry picked from commit eb97b9211e)
Co-authored-by: tmblweed <tmblweed@users.noreply.github.com>
Add a versionadded for PS Core and note that `.venv` is a common virtual environment name.
(cherry picked from commit f9f8e3ce70)
Co-authored-by: Brett Cannon <54418+brettcannon@users.noreply.github.com>
Miss Islington (bot)
Stéphane Wirtel
Paul Ganssle
Vinay Sajip
Jason R. Coombs
Steve Dower
Zachary Ware
Raymond Hettinger
Serhiy Storchaka
Nick Coghlan
Greg Price
Kyle Stanley