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

[miss-islington]

• getaddrinfo fails on Illumos, inconsistent elsewhere if port is, but type & protocol are not specified #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]

---

📚 Documentation preview 📚: https://cpython-previews--126824.org.readthedocs.build/