* 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>
`ResourceWarning` is ignored by default.
Document this behaviour, for consistency with others in this table such as `DeprecationWarning`.
Documentation PR can skip NEWS file.
Automerge-Triggered-By: GH:iritkatriel
(cherry picked from commit b949845b36)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
See discussion in GH-30179.
(cherry picked from commit 7c5c3f7254)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Automerge-Triggered-By: GH:Fidget-Spinner
* Fix-1 - isidentifier() function output
* Fix-2 Update the str.splitlines() function parameter
* Fix-3 Removed unwanted full stop for str and bytes types double quotes examples.
* Fix-4 Updated class dict from **kwarg to **kwargs
(cherry picked from commit 6f2df42951)
Co-authored-by: Vivek Vashist <vivekvashist@gmail.com>
* [3.10] bpo-46009: Do not exhaust generator when send() method raises (GH-29986).
(cherry picked from commit 69806b9516)
Co-authored-by: Mark Shannon <mark@hotpy.org>
* Rename variable after cherry-pick.
* Add NULL check.
(cherry picked from commit c7e7a4b969)
Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>
Automerge-Triggered-By: GH:Fidget-Spinner
Expanded ``astuple()`` docs, warning about deepcopy being applied
and providing a workaround.
Automerge-Triggered-By: GH:ericvsmith
(cherry picked from commit c1f93f0d37)
Co-authored-by: andrei kulakov <andrei.avk@gmail.com>
Automerge-Triggered-By: GH:asvetlov
(cherry picked from commit 4dd82194f4)
Co-authored-by: Zbigniew Siciarz <zbigniew@siciarz.net>
Co-authored-by: Zbigniew Siciarz <zbigniew@siciarz.net>
Document the `port` parameter to `loop.create_server` in `asyncio`. In
particular, note that if `host` resolves to multiple network interfaces,
passing in `port=0` will result in a different random unused port being
used for each interface.
Automerge-Triggered-By: GH:ericvsmith
(cherry picked from commit d71c7bc733)
Co-authored-by: Jim Crist-Harif <jcristharif@gmail.com>
Co-authored-by: Jim Crist-Harif <jcristharif@gmail.com>
It is now considered a historical accident that e.g. `for` loops and the `iter()` built-in function do not require the iterators they work with to define `__iter__`, only `__next__`.
(cherry picked from commit be36e06340)
Co-authored-by: Brett Cannon <brett@python.org>
The documentation explaining Python's data model does not adequately explain
the differences between ``__getitem__`` and ``__class_getitem__``, nor does it
explain when each is called. There is an attempt at explaining
``__class_getitem__`` in the documentation for ``GenericAlias`` objects, but
this does not give sufficient clarity into how the method works. Moreover, it
is the wrong place for that information to be found; the explanation of
``__class_getitem__`` should be in the documentation explaining the data model.
This PR has been split off from GH-29335.
(cherry picked from commit 31b3a70edb)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Accessing one enum member from another originally raised an `AttributeError`, but became possible due to a performance boost implementation detail. In 3.11 it will again raise an `AttributeError`.
I was reading this bit last night and thought it was a typo. In the light of day, I realized it wasn't *technically* a typo, but definitely confusing wording. This PR fixes the confusing sentence.
Automerge-Triggered-By: GH:ericvsmith
(cherry picked from commit f8da00ef04)
Co-authored-by: Jack DeVries <jdevries3133@gmail.com>
* [bpo-45772](): socket.socket should be a class instead of a function
Currently `socket.socket` is documented as a function, but it is really
a class (and thus has function-like usage to construct an object). This
correction would ensure that Python projects that are interlinking
Python's documentation can properly locate `socket.socket` as a type.
(cherry picked from commit 4c792f39e6)
Co-authored-by: Hong Xu <hong@topbug.net>
Automerge-Triggered-By: GH:asvetlov
Since `.. module:: contextvars` sets the module using `.. class:: contextvars.Token`, intersphinx records it as `contextvars.contextvars.Token`.
(cherry picked from commit e501d70b34)
Co-authored-by: Hynek Schlawack <hs@ox.cx>
Co-authored-by: Hynek Schlawack <hs@ox.cx>
``typing.Tuple`` has been deprecated since Python 3.9, so it makes no sense to mention it so prominently in the documentation for the ``typing`` module.
(cherry picked from commit 87032cfa3d)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Specify that SSLContext.set_default_verify_paths is called on ALL systems.
The code of SSLContext.load_default_certs was changed in bpo-22449 to do this,
this fix corrects the documentation to match that change.
(cherry picked from commit 3551bf16ee)
Co-authored-by: LincolnPuzey <lincoln@puzey.dev>
* bpo-45516: add protocol description to the Traversable documentation
Signed-off-by: Filipe Laíns <lains@riseup.net>
* Update Doc/library/importlib.rst
Co-authored-by: Jason R. Coombs <jaraco@jaraco.com>
* Update Lib/importlib/abc.py
* Update Doc/library/importlib.rst
Co-authored-by: Jason R. Coombs <jaraco@jaraco.com>
Co-authored-by: Jason R. Coombs <jaraco@jaraco.com>
(cherry picked from commit 4d03de3329)
Co-authored-by: Filipe Laíns <filipe.lains@gmail.com>
The link broke for Python 3.10 since importlib.metadata was made from a module into a package
I think this is trivial enough to not need a bpo issue.
Automerge-Triggered-By: GH:jaraco
(cherry picked from commit aae18a1740)
Co-authored-by: Philipp A <flying-sheep@web.de>
The list of PEPs at the top of the documentation for the ``typing`` module has
become too long to be readable. This PR proposes presenting this
information in a more structured and readable way by adding a new "relevant
PEPs" section to the ``typing`` docs.
(cherry picked from commit 03db1bbfd2)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>
(cherry picked from commit 0a68b3603f)
Co-authored-by: Justinas Petuchovas <justinas.petuchovas@gmail.com>
* add availability info to AF_PACKET section
* add availability for AF_QIPCRTR as well
(cherry picked from commit 51375388be)
Co-authored-by: andrei kulakov <andrei.avk@gmail.com>
We should have done this way back when 3.9 was released, but it fell off
the radar.
Co-authored-by: Paul Ganssle <git@m.ganssle.io>
(cherry picked from commit 8e40ca127f)
Document that the "standalone" parameter was added in Python 3.9.
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
(cherry picked from commit c7e81fcf95)
Co-authored-by: Jens Diemer <github.com@jensdiemer.de>
This is true of all dictionaries in Python, but this one tends to
catch people off guard as they don't realize when sys.modules might
change out from underneath them as a hidden side effect of their
code. Copying it first avoids the RuntimeError. An example when
this happens in single threaded code are codecs being loaded which
are an implicit time of use import that most need not think about.
(cherry picked from commit 3d1ca867ed)
Co-authored-by: Gregory P. Smith <greg@krypto.org>
It took me longer than I expected to figure out why a random class
I dealt with didn't support weak references. I believe this addition
will make the __slots__/weakref interaction more discoverable to people
having troubles with this. (Before this patch __slots__ was not
mentioned in weakref documentation even once).
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
(cherry picked from commit b24b47e643)
Co-authored-by: Jakub Stasiak <jakub@stasiak.at>
It seems part of `gethostbyname_ex` doc was copied from `gethostbyaddr`. The latter has an `ip_address` parameter whereas the former doesn't.
(cherry picked from commit 4103280b83)
Co-authored-by: Andre Delfino <adelfino@gmail.com>
The URL listed in the `logging` docs for the original `logging` module leads to a 404. I managed to find the new location for the page and updated the URL.
Automerge-Triggered-By: GH:vsajip
(cherry picked from commit 8492b729ae)
Co-authored-by: Sean Leavey <SeanDS@users.noreply.github.com>
Replace old names when they refer to actual versions of macOS.
Keep historical names in references to older versions.
Co-authored-by: Patrick Reader <_@pxeger.com>
(cherry picked from commit 36122e1814)
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
(cherry picked from commit fcbf9b176b)
Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
- Add link to str object and sqlite3 transaction control
- Mention that exceptions are not propagated
(cherry picked from commit 51056b40e7)
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
Miss Islington (bot)