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

gh-123832: Adjust socket.getaddrinfo docs for better POSIX compliance #126182

Merged
merged 4 commits into from
Nov 14, 2024
Merged

gh-123832: Adjust socket.getaddrinfo docs for better POSIX compliance #126182

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
83775cf
gh-123832: Adjust `socket.getaddrinfo` docs for better POSIX compliance
encukou Oct 28, 2024
83c86b0
Apply suggestion from code review
encukou Nov 4, 2024
a6f1e2a
Update Doc/library/socket.rst
encukou Nov 12, 2024
bd73913
Remove unacceptable whitespace
encukou Nov 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 28 additions & 3 deletions Doc/library/socket.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -928,7 +928,9 @@

.. 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.
Expand All @@ -938,9 +940,11 @@
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,

Check warning on line 947 in Doc/library/socket.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:const reference target not found: AI_NUMERICHOST [ref.const]
and will influence how results are computed and returned.
For example, :const:`AI_NUMERICHOST` will disable domain name resolution
and will raise an error if *host* is a domain name.
Expand All @@ -959,6 +963,25 @@
: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

Check warning on line 968 in Doc/library/socket.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:data reference target not found: IPPROTO_TCP [ref.data]

Check warning on line 968 in Doc/library/socket.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:data reference target not found: IPPROTO_UDP [ref.data]
(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.

With default values of *family*, *type*, *proto* and/or *flags*,
many systems will return a sorted list of all matching addresses,
which should generally be tried in order until a connection succeeds
(possibly in parallel, for example using a `Happy Eyeballs`_ algorithm).
encukou marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we know typical details for "many systems" and "some systems" we should include an possible example with each such as "(ex: most Linux configurations)" or "(ex: reported on Solaris and AIX configurations)". I'm wording those non-concretely as well, but suggest adding it just to add some context for people looking into behaviors as to when they may encounter the unexpected.

not a big deal without this, just a nice to have.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For your reference from #123832, "many" are basically mainstream (Linux, macOS, FreeBSD) and "some" are Illumos / Solaris / AIX. I haven't had a chance to get my hands on anything more exotic recently (HP-UX and VMS come to mind...).

I would also prefer to be more specific, but I thought the details were left out to avoid "finger pointing".

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
Expand All @@ -978,6 +1001,8 @@
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,
Expand Down
Loading