gh-123832: Adjust socket.getaddrinfo docs for better POSIX compliance
#126182
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…mpliance 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.
|
I really like your changes now 👍 Thank you! My only concern now is that the "meat" of the message is "hidden" in a note, but I guess there's nothing that can reasonably be done about that, apart from making |
willingc
reviewed
Oct 30, 2024
Co-authored-by: Carol Willing <[email protected]>
|
Yeah, the ship has sailed, with Solaris catching up and AIX left behind. Sad, but it's where we are. @gpshead, I intend to merge this next week. Let me know if you want to review & want more time. |
gpshead
reviewed
Nov 4, 2024
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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".
encukou
commented
Nov 11, 2024
encukou
added
needs backport to 3.12
|
Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12. |
|
Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13. |
miss-islington
pushed a commit
to miss-islington/cpython
that referenced
this pull request
Nov 14, 2024
…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]>
|
GH-126824 is a backport of this pull request to the 3.12 branch. |
miss-islington
pushed a commit
to miss-islington/cpython
that referenced
this pull request
Nov 14, 2024
…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]>
|
GH-126825 is a backport of this pull request to the 3.13 branch. |
encukou
added a commit
that referenced
this pull request
Nov 15, 2024
…ompliance (GH-126182) (GH-126825) 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]>
encukou
added a commit
that referenced
this pull request
Nov 15, 2024
…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]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
issue tl;dr: POSIX technically allows
getaddrinforesults with default family, proto & type to be unusable; and you want to specify one of those on all systems to filter out stuff likeSOCK_RAWthat your app can't handle anyway.IMO, CPython should aim to follow POSIX in cases where all supported platforms behave a certain way, but some unsupported ones stick to the spec in some inconvenient way.
@gpshead, I'd be interested in your take on this.
This PR 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.getaddrinfoas a wrapper aroundgetaddrinfo(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_UNSPECrather 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):
getaddrinfofails on Illumos, inconsistent elsewhere if port is, but type & protocol are not specified #123832📚 Documentation preview 📚: https://cpython-previews--126182.org.readthedocs.build/