gh-123832: Adjust `socket.getaddrinfo` docs for better POSIX compliance (GH-126182)
* gh-123832: Adjust `socket.getaddrinfo` docs for better POSIX compliance
This changes nothing changes for CPython supported platforms,
but hints how to deal with platforms that stick to the letter of
the spec.
It also marks `socket.getaddrinfo` as a wrapper around `getaddrinfo(3)`;
specifically, workarounds to make the function work consistently across
platforms are out of scope in its code.
Include wording similar to the POSIX's “by providing options and by
limiting the returned information”, which IMO suggests that the
hints limit the resulting list compared to the defaults, *but* can
be interpreted differently. Details are added in a note.
Specifically say that this wraps the underlying C function. So, the
details are in OS docs. The “full range of results” bit goes away.
Use `AF_UNSPEC` rather than zero for the *family* default, although
I don't think a system where it's nonzero would be very usable.
Suggest setting proto and/or type (with examples, as the appropriate
values aren't obvious). Say why you probably want to do that that
on all systems; mention the behavior on the “letter of the spec”
systems.
Suggest that the results should be tried in order, which is,
AFAIK best practice -- see RFC 6724 section 2, and its predecessor
from 2003 (which are specific to IP, but indicate how people use this):
> Well-behaved applications SHOULD iterate through the list of
> addresses returned from `getaddrinfo()` until they find a working address.
(cherry picked from commit ff0ef0a54b)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
The supported mode values are 'r', 'w', and 'b', or a combination of those.
(cherry picked from commit 62a29be5bb)
Co-authored-by: Daniel Williams <dann0a@gmail.com>
docs: module page titles should not start with a link to themselves (GH-117099)
(cherry picked from commit bcb435ee8f)
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
gh-101100: Fix Sphinx warning in references with asterisks (GH-113029)
(cherry picked from commit 3531ea441b)
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Correct documentation for AF_PACKET (GH-112339)
Protocol in the address tuple should *not* be in the network-byte-order, because it is converted internally[1].
[1] 89ddea4886/Modules/socketmodule.cGH-L2144
network byte order doesn't make sense for a python level int anyways. It's a fixed size C serialization concept.
(cherry picked from commit 562d7149c6)
Co-authored-by: Eugene Toder <eltoder@users.noreply.github.com>
gh-110631: Fix reST indentation in `Doc/library` (GH-110685)
Fix wrong indentation in the Doc/library dir.
(cherry picked from commit bb7923f556)
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
socket documentation fix - rename triple to 3-tuple (GH-24722)
(cherry picked from commit 6b15ff5235)
Co-authored-by: Ori Hoch <ori@uumpa.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
gh-104882: Docs: fix description of relationship between `socket.getblocking()` and `socket.gettimeout()` (GH-105026)
(cherry picked from commit 5a5ed7a3e6)
Co-authored-by: Joe Geisbauer <joegeisbauer@gmail.com>
gh-89415: Mention new `IP_*` constants in `socket` module in the docs (GH-105266)
(cherry picked from commit eaff9c39aa)
Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
* 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
* Use new-style index directive ('module') - C API
* Use new-style index directive ('module') - Library
* Use new-style index directive ('module') - Reference
* Use new-style index directive ('module') - Tutorial
* Uncomment module removal in pairindextypes
* Use new-style index directive ('module') - C API
* Use new-style index directive ('module') - Library
* Use new-style index directive ('module') - Reference
A few TCP socket options have been added to the Linux kernel these last
few years.
This commit adds all the ones available in Linux 6.0:
https://elixir.bootlin.com/linux/v6.0/source/include/uapi/linux/tcp.h#L91
While at it, the TCP_FASTOPEN option has been moved lower in the list
just to keep the same order as in tcp.h to ease future synchronisations.
Signed-off-by: Matthieu Baerts <matthieu.baerts@tessares.net>
If an HTTP link is redirected to a same looking HTTPS link, the latter can
be used directly without changes in readability and behavior.
It protects from a men-in-the-middle attack.
This change does not affect Python examples.
* 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.
