Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[3.12] gh-123832: Adjust socket.getaddrinfo docs for better POSIX compliance (GH-126182) #126824

Open
wants to merge 1 commit into
base: 3.12
Choose a base branch
from
Open

[3.12] gh-123832: Adjust socket.getaddrinfo docs for better POSIX compliance (GH-126182) #126824

wants to merge 1 commit into from
+32 −3

Commits on Nov 14, 2024

  1. pythongh-123832: Adjust socket.getaddrinfo docs for better POSIX co… 

    …mpliance (pythonGH-126182)

* pythongh-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 ff0ef0a)

Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
    @encukou @willingc @miss-islington
    2 people authored and miss-islington committed Nov 14, 2024
    Configuration menu
    Copy the full SHA
    8c3dc8a View commit details
    Browse the repository at this point in the history