In the queue documentation, the code snippet shows the import to be not PEP 8 compliant.
Since people typically copy-paste from such code samples, I think it's important to show best-practices here.
(cherry picked from commit ad55147c1d)
Co-authored-by: Mariatta Wijaya <Mariatta@users.noreply.github.com>
0. Update text start and stop conditions.
1. Title-case sections but not subsections.
2. Edit Shell Window sections: title, execute, restart.
(cherry picked from commit e6391e08bf)
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Also add adapters and converter recipes.
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com.
(cherry picked from commit bd3c1c187e)
It is no longer changed when create a zip or tar archive.
It is still changed for custom archivers registered with shutil.register_archive_format()
if root_dir is not None.
Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
(cherry picked from commit fda4b2f063)
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
* Revert "bpo-42843: Keep Sphinx 1.8 and Sphinx 2 compatibility (GH-24282)"
This reverts commit 5c1f15b4b1
* Revert "bpo-42579: Make workaround for various versions of Sphinx more robust (GH-23662)"
This reverts commit b63a620014.
(cherry picked from commit 0efe3a1636)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Explicitly note that transactions are only closed if there is an open
transation at `__exit__`, and that transactions are not implicitly
opened during `__enter__`.
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
Automerge-Triggered-By: GH:erlend-aasland
(cherry picked from commit 8e08978141)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
Align the docs for the following methods with the actual implementation:
- sqlite3.complete_statement()
- sqlite3.Connection.create_function()
- sqlite3.Connection.create_aggregate()
- sqlite3.Connection.set_progress_handler()
(cherry picked from commit d31834688b)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
- Order exceptions as in PEP 249
- Reword descriptions, so they match the current behaviour
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>.
(cherry picked from commit bb0b768946)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
Documentation for `pathlib` says:
> Spurious slashes and single dots are collapsed, but double dots ('..') are not, since this would change the meaning of a path in the face of symbolic links:
However, it omits that initial double slashes also aren't collapsed.
Later, in documentation of `PurePath.drive`, `PurePath.root`, and `PurePath.name` it mentions UNC but:
- this abbreviation says nothing to a person who is unaware about existence of UNC (Wikipedia doesn't help either by [giving a disambiguation page](https://en.wikipedia.org/wiki/UNC))
- it shows up only if a person needs to use a specific property or decides to fully learn what the module provides.
For context, see the BPO entry.
(cherry picked from commit 78f1a43694)
Co-authored-by: Oleg Iarygin <oleg@arhadthedev.net>
These are currently broken as they refer to :meth:`Path.relative_to` rather than :meth:`PurePath.relative_to`, and `relative_to` is a method on `PurePath`..
(cherry picked from commit 8ef7929baf)
Co-authored-by: jacksonriley <52106215+jacksonriley@users.noreply.github.com>
Backport of #93268
This is purely for SEO as this is the actual generic name for this kind of method and it currently does not appear in a Google search for "python constant time compare". Not creating an issue or setting this up for backports as its trivial (I think) and not a functional change.
(cherry picked from commit 8241a6971e)
Co-authored-by: Noah Kantrowitz <noah@coderanger.net>
* bpo-42272: improve message/module warning filter docs
"The Warnings Filter" section of the warnings module documentation
describes the message and module filters as "a string containing a
regular expression". While that is true when they are arguments to the
filterwarnings function, it is not true when they appear in -W or
$PYTHONWARNINGS where they are matched literally (after stripping any
starting/ending whitespace). Update the documentation to note when they
are matched literally. Also clarify that module matches the
"fully-qualified module name", rather than "module name" which is
ambiguous.
skip news (since this is a doc fix)
Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
* bpo-42272: remove bad submodule warning filter doc
The `error:::mymodule[.*]` example in the "Describing Warning Filters"
section of the warnings module documentation does not behave as the
comment describes. Since the module portion of the filter string is
interpreted literally, it would match a module with a fully-qualified
name that is literally `mymodule[.*]`.
Unfortunately, there is not a way to match '"module" and any subpackages
of "mymodule"' as documented, since the module part of a filter string
is matched literally. Instead, update the filter and comment to match
only "mymodule".
skip news (since this is a doc fix)
Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
* bpo-42272: add warning filter doc changes to NEWS
Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
(cherry picked from commit 8136606769)
Co-authored-by: Kevin Locke <kevin@kevinlocke.name>
This is a rework of GH-5774 on current main. I was a bit more
conservative in making changes than the original PR.
See @csabella's comments on issue GH-77024 and the discussion
on GH-5774 for explanations of several of the changes.
Co-authored-by: Cheryl Sabella <cheryl.sabella@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
(cherry picked from commit 8995177030)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
* Some handlers were wrongly described as text-encoding only, but actually they can also be used in text-decoding.
* Add more description to each handler.
* Add two REPL examples.
* Add indexes for Error Handler's name.
Co-authored-by: Kyle Stanley <aeros167@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit 5bc2390229)
Co-authored-by: Ma Lin <animalize@users.noreply.github.com>
Missing reference of auditing event presents error when building translated documentation
(cherry picked from commit f298ba1f27)
Co-authored-by: Rafael Fontenelle <rffontenelle@users.noreply.github.com>
Given that 2.7 has now been end-of-life for two and a half years,
I don't think we need such a detailed explanation here anymore of
the differences between Python 2 and Python 3.
(cherry picked from commit 8efda1e7c6)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Automerge-Triggered-By: GH:serhiy-storchaka
Fixed some inconsistencies in the text about relationships
(cherry picked from commit 5f45a9d3c3)
Co-authored-by: David Gilbertson <gilbertson.david@gmail.com>
Remove a confusion for read method in asyncio-subprocess doc for stderr StreamReader instance
(cherry picked from commit bb857a96ef)
Co-authored-by: Harsh <65716674+Harsh-br0@users.noreply.github.com>
example.com is reserved by the IANA as special-use domain name for documentation
purposes. The domain names are used widely in books, tutorials, sample network
configurations, and generally as examples for the use of domain name.
On the other hand, mydomain.com is real Domain Name Registration service.
(cherry picked from commit ea39246782)
Co-authored-by: Motoki Naruse <motoki@naru.se>
- Drop 'nonstandard'; it does not add any value
- Try to be more concise
- Make return value a little more explicit
(cherry picked from commit 017f07a229)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
* revise the first paragraph of docs for os.path
* add a mention of `os.PathLike` protocol
* remove warnings rendered irrelevant by :pep:`383` and :pep:`529`
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit 468314cc8b)
Co-authored-by: Jack DeVries <jdevries3133@gmail.com>
* add a paragraph to document this kwarg in detail
* update docstring in the source accordingly
(cherry picked from commit f33e2c87a8)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Since `title()` mentions its own short-comings, it should also mention the library function which does not possess them.
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit b786d9ec52)
Co-authored-by: Eric Wieser <wieser.eric@gmail.com>
People keep popping up reporting these as typos in the docs despite
being described as typos in the surrounding text. Hopefully a comment
on the line itself makes it more obvious?
Arguably some of the typo examples are not using the "right" typo as the
"assret" one in particular is now detected by default due to how common
it was in actual code. But I don't want to to typo chasing by changing
these examples to be other not yet auto-detected typos as they still
illustrate the point well enough.
(cherry picked from commit ac1fb07b6e)
Co-authored-by: Gregory P. Smith <greg@krypto.org>
It is not preferable to keep a copy of the implementation in the
docs.
(cherry picked from commit e06f920c5b)
Co-authored-by: Zackery Spytz <zspytz@gmail.com>
Clarify the `str()` docs to point out that `object.__str__()`
follows special method lookup.
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit bb86d1d9fb)
Co-authored-by: Vanshaj Singhania <8797467+itsvs@users.noreply.github.com>
The second parameter (named `func`) has been present since the `locale`
module was introduced in eef1d4e8b1, but has never been documented.
This commit updates the documentation for `locale.atof` to clarify the
behavior of the function and how the `func` parameter is used.
Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
(cherry picked from commit 208da6d508)
Co-authored-by: Kevin Locke <kevin@kevinlocke.name>
While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Éric Araujo <merwok@netwok.org>
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit ebbdbbff5d)
Co-authored-by: Arthur Milchior <arthur@milchior.fr>
Update documentation to note that in some circumstances,
KeyboardInterrupt may cause code to enter an inconsistent state. Also
document sample workaround to avoid KeyboardInterrupt, if needed.
(cherry picked from commit d0906c90fc)
Co-authored-by: benfogle <benfogle@gmail.com>
The enter_context is updated with following information: 'The :meth:`__enter__` method
returns the ExitStack instance, and performs no additional operations.'
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit 86384cf83f)
Co-authored-by: vidhya <96202776+Vidhyavinu@users.noreply.github.com>
People are testing those blocs with the default
inline_comment_prefixes of None, leading to a:
configparser.InterpolationSyntaxError: '$' must be followed by '$' or '{', found: '$ sign ($ is the only character that needs to be escaped)'
(cherry picked from commit 3ac4e783e0)
Co-authored-by: Julien Palard <julien@palard.fr>
Also removed asynchat, asyncore, and smtpd from their respective toctree entries so they are only in the superceded subtree.
(cherry picked from commit 9ac2de922a)
Co-authored-by: Brett Cannon <brett@python.org>
Automerge-Triggered-By: GH:brettcannon
Document the deprecation of asyncore, asynchat, and smtpd with a slated removal in Python 3.12 thanks to PEP 594..
(cherry picked from commit 7747384643)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Clarifies a versionchanged note on crc32 & adler32 docs that the workaround is only needed for Python 2 and earlier.
Also cleans up an unnecessary intermediate variable in the implementation.
Authored-By: Ma Lin / animalize
Co-authored-by: Gregory P. Smith <greg@krypto.org>
For consistency, replace "a SQL" with "an SQL"..
(cherry picked from commit 2d5835a019)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
As per the comments, this mirrors the [datetime documentation](https://docs.python.org/3/library/datetime.htmlGH-datetime.datetime.fromtimestamp).
```
>>> import time
>>> time.localtime(999999999999999999999)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
OverflowError: timestamp out of range for platform time_t
>>> time.localtime(-3600)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
OSError: [Errno 22] Invalid argument
```
(cherry picked from commit c83fc9c02c)
Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>
Replace two instances of "pysqlite" with "sqlite3" in sqlite3
docstrings. Also reword "is a no-op" to "does nothing" for clarity..
(cherry picked from commit b33a1ae703)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
* Fix formatting of True and False in the threading documentation
* Update threading.rst
(cherry picked from commit 46a116c1c9)
Co-authored-by: Géry Ogam <gery.ogam@gmail.com>
Was probably caused by the addition of the `total()` method
(cherry picked from commit 99331fcf17)
Co-authored-by: Charles Brunet <charles.brunet@optelgroup.com>
This PR for the documentation of the [html.parser](https://docs.python.org/3/library/html.parser.html) module will
- fix a terminology mistake (‘start of a tag’ -> ‘start tag of an element’);
- mention the parameter names of the `HTMLParser.handle_*` methods where missing.
(cherry picked from commit 2945f5a7c5)
Co-authored-by: Géry Ogam <gery.ogam@gmail.com>
Automerge-Triggered-By: GH:merwok
(cherry picked from commit 04215a4272)
Co-authored-by: David Gilbertson <gilbertson.david@gmail.com>
Co-authored-by: David Gilbertson <gilbertson.david@gmail.com>
The reference to `venv` appears in the paragraph below, instead of above.
Fixed the documentation.
(cherry picked from commit 4e4e7c2684)
Co-authored-by: David Gilbertson <gilbertson.david@gmail.com>
Co-authored-by: David Gilbertson <gilbertson.david@gmail.com>
(cherry picked from commit 6b9f27dd0b)
Co-authored-by: Rafael Fontenelle <rffontenelle@users.noreply.github.com>
Co-authored-by: Rafael Fontenelle <rffontenelle@users.noreply.github.com>
Explicitly state that it is lowercase.
Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com>
(cherry picked from commit 5d53cf30f9)
Co-authored-by: 180909 <wjh180909@gmail.com>
Added *key* parameter to `bisect.bisect()` and `bisect.insort()` in bisect module docs.
(cherry picked from commit 96084f4256)
Co-authored-by: Zackery Spytz <zspytz@gmail.com>
* `precision` field is a decimal integer
* clarify that stated limitations are on presentation type
rather than input value type. Especially misleading is
"precision is not allowed for integer values", since integer
value input to a format like `.1f` is fine.
* regarding max field size, replace "non-number" with "string",
which is the only non-numeric presentation type
Automerge-Triggered-By: GH:ericvsmith
(cherry picked from commit 1d6ce67c29)
Co-authored-by: John Belmonte <john@neggie.net>
Remove pathlib classes from the list in stdtypes.rst of classes
that can be parameterized at runtime.
(cherry picked from commit e0bc8ee945)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Minor missing version note mentioned at the end of (and affected me independently before reading that note).
Automerge-Triggered-By: GH:ericvsmith
(cherry picked from commit 5a3f97291e)
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
Less specific number wording (as there is no one right number - the old 100k is too big for some applications and woefully small for others). We now link to NIST SP 800-132 to tell people what to read in there on how to decide for their application.
Co-authored-by: Gregory P. Smith <greg@krypto.org> [Google]
(cherry picked from commit 897ce90187)
Co-authored-by: Illia Volochii <illia.volochii@gmail.com>
In the File menu, 'Close' and 'Exit' are now 'Close Window' (the current
one) and 'Exit' is now 'Exit IDLE' (by closing all windows).
In Shell, 'quit()' and 'exit()' mean 'close Shell'.
If there are no other windows, this also exits IDLE.
(cherry picked from commit fcde0bc10d)
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
Code link:
70c16468de/Lib/http/server.pyGH-L1270
It's been this way since at least 3.4.
Also improved some wording in the same section.
(cherry picked from commit c8a536624e)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Other descriptions in the same file also use 'bytestring' to refer to bytes objects
(cherry picked from commit 4b99803b86)
Co-authored-by: Florian Bruhin <me@the-compiler.org>
A small change to the documentation of datetime module , in the format codes section of stftime and strptime. Changed the description of format code '%W' from 'as a decimal number' to 'a zero padded decimal number' so it's in line with the example having leading zeros. Similar to the format code '%U' above.
Automerge-Triggered-By: GH:pganssle
(cherry picked from commit d45cd2d207)
Co-authored-by: Evan <binary-signal@users.noreply.github.com>
The documentation on ``GenericAlias`` objects implies at multiple points that
only container classes can define ``__class_getitem__``. This is misleading.
This PR proposes a rewrite of the documentation to clarify that non-container
classes can define ``__class_getitem__``, and to clarify what it means when a
non-container class is parameterized.
See also: initial discussion of issues with this piece of documentation in
GH-29308, and previous BPO issue [42280]().
Also improved references in glossary and typing docs. Fixed some links.
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>
(cherry picked from commit 0eae9a2a2d)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Automerge-Triggered-By: GH:Fidget-Spinner
* bpo-46402: Promote SQLite URI tricks in `sqlite3` docs (GH-30660)
Provide some examples of URI parameters in sqlite connect().
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
(cherry picked from commit bdf2ab1887)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
* Update suspicious rules
This addresses [bpo-45554]() by expanding the `exitcode` documentation to also describe what `exitcode` will be in cases of normal termination, `sys.exit()` called, and on uncaught exceptions.
Automerge-Triggered-By: GH:pitrou
(cherry picked from commit 3852269b91)
Co-authored-by: John Marshall <jmarshall@hey.com>
Co-authored-by: Robert Collins <robertc@robertcollins.net>
(cherry picked from commit 73140de97c)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Ian Kelling <ian@iankelling.org>
(cherry picked from commit 6d07a9fb7c)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
(cherry picked from commit f404e26d74)
Co-authored-by: Philipp Claßen <philipp.classen@posteo.de>
Co-authored-by: Philipp Claßen <philipp.classen@posteo.de>
Miss Islington (bot)