* separate documentation and examples for both functions
* add examples demonstrating behaviour with unsupported types
* document return value of `get_origin` for `ParamSpecArgs` and `ParamSpecKwargs` instances
(cherry picked from commit a7a2dbbf72)
Co-authored-by: chgnrdv <52372310+chgnrdv@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
gh-102327: Extend docs for "url" and "headers" parameters to HTTPConnection.request()
Added example on how to use the HTTPConnection object for making GET request.
Original issue: https://github.com/python/cpython/issues/102327
---------
(cherry picked from commit 7ba6288feb)
Co-authored-by: David Foster <david@dafoster.net>
Co-authored-by: Éric <earaujo@caravan.coop>
GH-104145: Use fully-qualified cross reference types for the bisect module (GH-104172)
(cherry picked from commit 76eef552f3)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
gh-102500: Remove mention of bytes shorthand (#104281)
The bytes shorthand was removed in PEP 688:
https://peps.python.org/pep-0688/#no-special-meaning-for-bytes
The reference to collections.abc.ByteString is also removed, since that object is deprecated (#91896) and has different semantics (#102092)
Although PEP 688 is new in Python 3.12, type checkers are expected to implement the new semantics for type annotations even if users are using an older version of Python, so this docs PR is backported to Python 3.11.
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
gh-104254: Document the optional keyword-only "context" argument to Task constructor (GH-104251)
(This was added in 3.11. It was already documented for `create_task()`, but not for `Task()`.)
(cherry picked from commit 4ee2068c34)
Co-authored-by: Itamar Ostricher <itamarost@gmail.com>
GH-97950: Use new-style index directive ('builtin') (GH-104164)
* Uncomment builtin removal in pairindextypes
* Use new-style index directive ('builtin') - C API
* Use new-style index directive ('builtin') - Extending
* Use new-style index directive ('builtin') - Library
* Use new-style index directive ('builtin') - Reference
* Use new-style index directive ('builtin') - Tutorial
(cherry picked from commit f5088006ca)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
gh-104112: link from cached_property docs to method-caching FAQ (GH-104113)
(cherry picked from commit fa86a77589)
Co-authored-by: Carl Meyer <carl@oddbird.net>
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
GH-97950: Use new-style index directive ('object') (GH-104158)
* Uncomment object removal in pairindextypes
* Use new-style index directive ('object') - C API
* Use new-style index directive ('object') - Library
* Use new-style index directive ('object') - Reference
* Use new-style index directive ('object') - Tutorial
(cherry picked from commit 6ab463684b)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Improve assert_type phrasing (GH-104081)
I'd like to make the fact that this does nothing at runtime
really obvious, since I suspect this is unintuitive for users who are
unfamiliar with static type checking.
I thought of this because of
https://discuss.python.org/t/add-arg-check-type-to-types/26384
wherein I'm skeptical that the user really did want `assert_type`.
(cherry picked from commit 82ba6ce303)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
This removes a section of the `strftime` and `strptime` documentation that refers to a bygone era when `strftime` would return an encoded byte string.
---------
(cherry picked from commit 2aa22f72fb)
Co-authored-by: William Andrea <william.j.andrea@gmail.com>
Co-authored-by: Paul Ganssle <1377457+pganssle@users.noreply.github.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Clarify that asyncio.Server.sockets is a socket-like TransportSocket
(cherry picked from commit 1c0a9c5a1c)
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Cc. @adriangb
The "stub documentation" in `types.rst` does already link to the
in-depth docs in `stdtypes.rst`, but the link isn't obvious for new
users. It deserves to be made more prominent.
- Issue: https://github.com/python/cpython/issues/103721
(cherry picked from commit cef542ca57)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
modernize dataclass example typing `list` rather than `List` and comment
as to that line being the alluded too error.
(cherry picked from commit 7ef614c1ad)
Co-authored-by: Allan Lago <35788148+alago1@users.noreply.github.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Clarifies that it remains None until a method checking the child process
status has been called and noticed it has terminated.
(cherry picked from commit 68f5836582)
Co-authored-by: Joshua Herman <30265+zitterbewegung@users.noreply.github.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Fix broken links reported by linkcheck (#103608)
gh-68654: Clarify subdirectories used by pkgutil.extend_path (GH-103701)
Clarify sub directories used by pkgutil.extend_path in the docs and the docstring
(cherry picked from commit 7bf94568a9)
Co-authored-by: Randy <69558016+san-juan1667@users.noreply.github.com>
GH-103475: cache() and lru_cache() do not have a "call once" guarantee (GH-103669)
(cherry picked from commit e5eaac6064)
Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
STRICT boundary:
- fix bitwise operations
- make default for Flag
(cherry picked from commit 2194071540)
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
Also use `raise TimeOut from <CancelledError instance>` so that the CancelledError is set
in the `__cause__` field rather than in the `__context__` field.
(cherry picked from commit 04adf2df39)
Co-authored-by: Kristján Valur Jónsson <sweskman@gmail.com>
Co-authored-by: Guido van Rossum <gvanrossum@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Fix outdated note about 'int' rounding or truncating (GH-102736)
(cherry picked from commit 405739f916)
Co-authored-by: Mark Dickinson <dickinsm@gmail.com>
gh-102354: change python3 to python in docs examples (GH-102696)
(cherry picked from commit 80abd62647)
Co-authored-by: Paul Watson <paul.hermeneutic@gmail.com>
* Replace known bad address pointing toward a malicious web page.
(cherry picked from commit 61479d4684)
Co-authored-by: Blind4Basics <32236948+Blind4Basics@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
(cherry picked from commit 78e4e6c3d7)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Fixes duplicated word (GH-102623)
In line 1627, the end of the sentence reads "only that that it may be." but it should read "only that it may be" (or alternatively "only that that may be").
(cherry picked from commit e6210621be)
Co-authored-by: Guido van Rossum <guido@python.org>
Co-authored-by: Hugo Gabriel Eyherabide <hugogabriel.eyherabide@gmail.com>
Move around example in to_bytes() to avoid confusion (GH-101595)
Moves an example to be closer to the sentence that refers to it.
(cherry picked from commit 5da379ca7d)
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
[3.11] Fix typos in documentation and comments (GH-102374)
Found some duplicate `to`s in the documentation and some code comments and fixed them.
[Misc/NEWS.d/3.12.0a1.rst](ed55c69ebd/Misc/NEWS.d/3.12.0a1.rst) also contains two duplicate `to`s, but I wasn't sure if it's ok to touch that file. Looks auto generated. I'm happy to amend the PR if requested. :)
Automerge-Triggered-By: GH:AlexWaygood
Co-authored-by: Michael K <michael-k@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Brad Wolfe <brad.wolfe@gmail.com>
Co-authored-by: Furkan Onder <furkanonder@protonmail.com>
Fix erroneous doc links in the sys module (#101319)
gh-85417: Clarify behaviour on branch cuts in cmath module (GH-102046)
This PR updates the cmath module documentation to reflect the reality that Python is almost always (and as far as I can tell, that "almost" can be omitted) running on a machine whose C double supports signed zeros.
* Removes misleading references to functions being continuous from above / below / the left / the right at branch cuts
* Expands the note on branch cuts at the top of the module documentation to explain the double-sided sign-of-zero-based behaviour
(cherry picked from commit b513c46d99)
Co-authored-by: Mark Dickinson <dickinsm@gmail.com>
(cherry picked from commit b7c1126447)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit b40dd71241)
Co-authored-by: ram vikram singh <ramvikrams243@gmail.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Adjust wording slightly, and use min(entries) instead of
sorted(list(entries))[0] as an example.
(cherry picked from commit 350ba7c07f)
Co-authored-by: Owain Davies <116417456+OTheDev@users.noreply.github.com>
Note: the `timeout` parameter was not added until 3.12.
(cherry picked from commit c4de6b1d52)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>.
Co-authored-by: Brian Skinn <brian.skinn@gmail.com>
* Replace bitbucket.org domain by forge.example
* Update example to python.org
* Use explicitly invalid domain
topsecret.server.com domain is not controled by PSF. It's replaced by invalid topsecret.server.example domain. It follows RFC 2606, which advise .example as TLD for documentation.
(cherry picked from commit 924a3bfa28)
Co-authored-by: sblondon <stephane.blondon@gmail.com>
gh-101390: Fix docs for `imporlib.util.LazyLoader.factory` to properly call it a class method (GH-101391)
(cherry picked from commit 17143e2c30)
Co-authored-by: busywhitespace <busywhitespace@tuta.io>
(cherry picked from commit 2037ebf81b)
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
* Note that Popen attributes aren't meant to be set by users by rewording the text about the attributes.
* Also update some universal_newlines references to mention the modern text parameter name while in the area.
(cherry picked from commit 027adf42cd)
Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
Co-authored-by: Gregory P. Smith <greg@krypto.org>
* Move array methods under class in array doc
* Fix a few internal references related to the touched lines
(cherry picked from commit 1b6045668d)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
This is a follow-up to GH-100811.
One of the changes in that PR isn't accurate in that
`os.path.join('', '')` will not end in a separator.
This reverts that change to the previous wording that used "only", but
explicitly calls out the case where the last part ends in a separator,
which is what caused confusin in GH-77607 and motivated the change
in GH-100811.
(cherry picked from commit 909a674693)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
(cherry picked from commit 9a155138c5)
While the documentation for `optparse` mentioned that both `store_const` and
`append_const` store a constant value, it was not clear where this value was
coming from.
A link to `Option.const` makes this explicit.
Co-authored-by: Jürgen Gmach <juergen.gmach@googlemail.com>
The zipfile.Path open() and read_text() encoding parameter can be supplied as a positional argument without causing a TypeError again. 3.10.0b1 included a regression that made it keyword only.
Documentation update included as users writing code to be compatible with a wide range of versions will need to consider this for some time..
(cherry picked from commit 5927013e47)
Co-authored-by: Gregory P. Smith <greg@krypto.org> [Google]
Sync-up parameter name in equivalent code snippet of `enumerate` (GH-101029)
(cherry picked from commit ef633e5000)
Co-authored-by: JustAnotherArchivist <JustAnotherArchivist@users.noreply.github.com>
- Use "drive", not "drive letter", because of UNC paths
- Previous components are not thrown away from relative drive letters
- Use "segment" instead of "component" for consistency with pathlib
- Other miscellaneous improvements
(cherry picked from commit 53455a319f)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Removed erroneous note in the get_type_hints docs
typing.get_type_hints still includes base class type hints.
(cherry picked from commit deaf090699)
Co-authored-by: FrozenBob <30644137+FrozenBob@users.noreply.github.com>
update dataclasses docs for when annotations are inspected
(cherry picked from commit 659c2607f5)
Co-authored-by: Akshit Tyagi <37214399+exitflynn@users.noreply.github.com>
The behaviour is fully explained a couple paragraphs above, but it may be useful to have a brief example to cover the behaviour.
(cherry picked from commit 1ae619c911)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Automerge-Triggered-By: GH:hauntsaninja
- Remove first link to lexical definition of integer literal, since it
doesn't apply (differs in handling of leading zeros, base needs to be
explicitly specified, unicode digits are allowed)
- Better describe handling of leading zeros, unicode digits, underscores
- Base 0 does not work exactly as like a code literal, since it allows
Unicode digits. Link code literal to lexical definition of integer
literal.
(cherry picked from commit edfbf56f4c)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
The PEP-249 numeric style has never been supported by sqlite3.
(cherry picked from commit b7a68ab824)
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
All the arguments are positional-only.
The current status after GH-99476 seems to be to not use positional-only
markers in documentation, hence I've simply removed it.
(cherry picked from commit 71159a8e07)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Based on the definition of the collections.abc classes, it is more accurate to use "sequence" instead of "container" when describing argparse choices.
(cherry picked from commit ad3c99e521)
Co-authored-by: Guy Yagev <yourlefthandman8@gmail.com>
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Previously, the grammar did not accept `float("10")`.
Also implement mdickinson's suggestion of removing the indirection.
(cherry picked from commit 2e1a9ce989)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Example needed to be indented. Was trying to call a context manger `pr` (from ` with cProfile.Profile() as pr:`) wot perform ` pr.print_stats()` once it had already exited.
(cherry picked from commit 8711b59f7a)
Co-authored-by: jarrodcolburn <jcourtlandcolburn@gmail.com>
Automerge-Triggered-By: GH:AlexWaygood
Changed from multiples of 3 to powers of 3 to match the class name.
(cherry picked from commit 868bab0fdc)
Co-authored-by: Beweeted <Beweeted@users.noreply.github.com>
Replace control characters in http.server.BaseHTTPRequestHandler.log_message with an escaped \xHH sequence to avoid causing problems for the terminal the output is printed to.
(cherry picked from commit d8ab0a4dfa)
Co-authored-by: Gregory P. Smith <greg@krypto.org>
Changing TraversableReader to TraversableResources at one place of the documentation.
See GH-99795 for more details.
(cherry picked from commit 5f8898216e)
Co-authored-by: busywhitespace <busywhitespace@tuta.io>
gh-99502: mention bytes-like objects as input in `secrets.compare_digest` (GH-99512)
Now it is in sync with https://docs.python.org/3/library/hmac.htmlGH-hmac.compare_digest
It is the same function, just re-exported. So, I guess they should mention the same input types.
(cherry picked from commit 47d673d81f)
Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
Fix misspelling in docs for http.HTTPMethod (GH-99376)
(cherry picked from commit f0d12ca0e0)
Co-authored-by: Matt Harasymczuk <github.com@haras.pl>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
(cherry picked from commit 7d2dcc53d0)
Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
Co-authored-by: Michael Anckaert <michael.anckaert@sinax.be>
gh-85073: Add some missing links to source (GH-99363)
Add some missing links to source from Python docs
(cherry picked from commit 27d8dc2c9d)
Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>
On some platforms, and in particular macOS/arm64, the calling
convention for variadic arguments is different from the regular
calling convention. Add a section to the documentation to document
this.
(cherry picked from commit bc3a11d21d)
Co-authored-by: Ronald Oussoren <ronaldoussoren@mac.com>
gh-99146 struct module documentation should have more predictable examples/warnings (GH-99141)
* nail down a couple examples to have more predictable output
* update a number of things, but this is really just a stash...
* added an applications section to describe typical uses for native and machine-independent formats
* make sure all format strings use a format prefix character
* responding to comments from @gpshead. Not likely finished yet.
* This got more involved than I expected...
* respond to several PR comments
* a lot of wordsmithing
* try and be more consistent in use of ``x`` vs ``'x'``
* expand examples a bit
* update the "see also" to be more up-to-date
* original examples relied on import * so present all examples as if
* reformat based on @gpshead comment (missed before)
* responding to comments
* missed this
* one more suggested edit
* wordsmithing
(cherry picked from commit 22d91c16bb)
Co-authored-by: Skip Montanaro <skip.montanaro@gmail.com>
Co-authored-by: Skip Montanaro <skip.montanaro@gmail.com>
GH-95815: Document less specific error for os.remove (GH-99571)
os.remove can raise PermissionError instead of IsADirectoryError,
when the object to be removed is a directory (in particular on
macOS).
This reverts a change done in GH-14262.
(cherry picked from commit 1cae31d26b)
Co-authored-by: Ronald Oussoren <ronaldoussoren@mac.com>
Co-authored-by: Ronald Oussoren <ronaldoussoren@mac.com>
Improves the docstring on signal.strsignal to make it explain when it returns a message, None, or when it raises ValueError.
Closes GH-98930
Co-authored-by: Gregory P. Smith <greg@krypto.org>.
(cherry picked from commit 88385b8564)
Co-authored-by: ram vikram singh <ramvikrams243@gmail.com>
gh-99304: [Enum] clarify what constitutes a flag alias (GH-99395)
(cherry picked from commit 73a921b070)
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Update reference to the size of PyPI
Last changed in 2008 (528576031d).
(cherry picked from commit 58ee5d8677)
Co-authored-by: jmcb <joelsgp@protonmail.com>
* fix auto() failure during multiple assignment
i.e. `ONE = auto(), 'text'` will now have `ONE' with the value of `(1,
'text')`. Before it would have been `(<an auto instance>, 'text')`
(cherry picked from commit 8feb7ab77c)
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
Erlend E. Aasland
