[3.12] gh-123832: Adjust socket.getaddrinfo docs for better POSIX c…

…ompliance (GH-126182) (GH-126824)

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

Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Carol Willing <[email protected]>

Doc/library/socket.rst

@@ -915,7 +915,9 @@ The :mod:`socket` module also offers various network-related services:
 
    .. versionadded:: 3.7
 
-.. function:: getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)
+.. function:: getaddrinfo(host, port, family=AF_UNSPEC, type=0, proto=0, flags=0)
+
+   This function wraps the C function ``getaddrinfo`` of the underlying system.
 
    Translate the *host*/*port* argument into a sequence of 5-tuples that contain
    all the necessary arguments for creating a socket connected to that service.
@@ -925,8 +927,10 @@ The :mod:`socket` module also offers various network-related services:
    and *port*, you can pass ``NULL`` to the underlying C API.
 
    The *family*, *type* and *proto* arguments can be optionally specified
-   in order to narrow the list of addresses returned.  Passing zero as a
-   value for each of these arguments selects the full range of results.
+   in order to provide options and limit the list of addresses returned.
+   Pass their default values (:data:`AF_UNSPEC`, 0, and 0, respectively)
+   to not limit the results. See the note below for details.
+
    The *flags* argument can be one or several of the ``AI_*`` constants,
    and will influence how results are computed and returned.
    For example, :const:`AI_NUMERICHOST` will disable domain name resolution
@@ -946,6 +950,29 @@ The :mod:`socket` module also offers various network-related services:
    :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
    method.
 
+   .. note::
+
+      If you intend to use results from :func:`!getaddrinfo` to create a socket
+      (rather than, for example, retrieve *canonname*),
+      consider limiting the results by *type* (e.g. :data:`SOCK_STREAM` or
+      :data:`SOCK_DGRAM`) and/or *proto* (e.g. :data:`IPPROTO_TCP` or
+      :data:`IPPROTO_UDP`) that your application can handle.
+
+      The behavior with default values of *family*, *type*, *proto*
+      and *flags* is system-specific.
+
+      Many systems (for example, most Linux configurations) will return a sorted
+      list of all matching addresses.
+      These addresses should generally be tried in order until a connection succeeds
+      (possibly tried in parallel, for example, using a `Happy Eyeballs`_ algorithm).
+      In these cases, limiting the *type* and/or *proto* can help eliminate
+      unsuccessful or unusable connecton attempts.
+
+      Some systems will, however, only return a single address.
+      (For example, this was reported on Solaris and AIX configurations.)
+      On these systems, limiting the *type* and/or *proto* helps ensure that
+      this address is usable.
+
    .. audit-event:: socket.getaddrinfo host,port,family,type,protocol socket.getaddrinfo
 
    The following example fetches address information for a hypothetical TCP
@@ -965,6 +992,8 @@ The :mod:`socket` module also offers various network-related services:
       for IPv6 multicast addresses, string representing an address will not
       contain ``%scope_id`` part.
 
+.. _Happy Eyeballs: https://en.wikipedia.org/wiki/Happy_Eyeballs
+
 .. function:: getfqdn([name])
 
    Return a fully qualified domain name for *name*. If *name* is omitted or empty,