Petr Viktorin ff0ef0a54b 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. Co-authored-by: Carol Willing <carolcode@willingconsulting.com>		2024-11-14 09:31:14 +01:00
..
__future__.rst
__main__.rst
_thread.rst
abc.rst
aifc.rst
allos.rst
annotationlib.rst
archiving.rst
argparse.rst
array.rst
ast.rst
asynchat.rst
asyncio-api-index.rst
asyncio-dev.rst
asyncio-eventloop.rst
asyncio-exceptions.rst
asyncio-extending.rst
asyncio-future.rst
asyncio-llapi-index.rst
asyncio-platforms.rst
asyncio-policy.rst
asyncio-protocol.rst
asyncio-queue.rst
asyncio-runner.rst
asyncio-stream.rst
asyncio-subprocess.rst
asyncio-sync.rst
asyncio-task.rst
asyncio.rst
asyncore.rst
atexit.rst
audioop.rst
audit_events.rst
base64.rst
bdb.rst
binary.rst
binascii.rst
bisect.rst
builtins.rst
bz2.rst
calendar.rst
cgi.rst
cgitb.rst
chunk.rst
cmath.rst
cmd.rst
cmdline.rst
code.rst
codecs.rst
codeop.rst
collections.abc.rst
collections.rst
colorsys.rst
compileall.rst
concurrency.rst
concurrent.futures.rst
concurrent.rst
configparser.rst
constants.rst
contextlib.rst
contextvars.rst
copy.rst
copyreg.rst
crypt.rst
crypto.rst
csv.rst
ctypes.rst
curses.ascii.rst
curses.panel.rst
curses.rst
custominterp.rst
dataclasses.rst
datatypes.rst
datetime.rst
dbm.rst
debug.rst
decimal.rst
development.rst
devmode.rst
dialog.rst
difflib.rst
dis.rst
distribution.rst
distutils.rst
doctest.rst
email.charset.rst
email.compat32-message.rst
email.contentmanager.rst
email.encoders.rst
email.errors.rst
email.examples.rst
email.generator.rst
email.header.rst
email.headerregistry.rst
email.iterators.rst
email.message.rst
email.mime.rst
email.parser.rst
email.policy.rst
email.rst
email.utils.rst
ensurepip.rst
enum.rst
errno.rst
exceptions.rst
faulthandler.rst
fcntl.rst
filecmp.rst
fileformats.rst
fileinput.rst
filesys.rst
fnmatch.rst
fractions.rst
frameworks.rst
ftplib.rst
functional.rst
functions.rst
functools.rst
gc.rst
getopt.rst	gh-126390: Support for preserving order of options and nonoption arguments in gnu_getopt() (GH-126393)	2024-11-13 22:50:46 +02:00
getpass.rst
gettext.rst
glob.rst
graphlib.rst
grp.rst
gzip.rst
hashlib-blake2-tree.png
hashlib.rst
heapq.rst
hmac.rst
html.entities.rst
html.parser.rst
html.rst
http.client.rst
http.cookiejar.rst
http.cookies.rst
http.rst
http.server.rst
i18n.rst
idle.rst
imaplib.rst
imghdr.rst
imp.rst
importlib.metadata.rst
importlib.resources.abc.rst
importlib.resources.rst
importlib.rst
index.rst
inspect.rst
internet.rst
intro.rst
io.rst
ipaddress.rst
ipc.rst
itertools.rst
json.rst
kde_example.png
keyword.rst
language.rst
linecache.rst
locale.rst
logging.config.rst
logging.handlers.rst
logging.rst
lzma.rst
mailbox.rst
mailcap.rst
markup.rst
marshal.rst
math.rst
mimetypes.rst
mm.rst
mmap.rst
modulefinder.rst
modules.rst
msilib.rst
msvcrt.rst
multiprocessing.rst
multiprocessing.shared_memory.rst
netdata.rst
netrc.rst
nis.rst
nntplib.rst
numbers.rst
numeric.rst
operator.rst
optparse.rst
os.path.rst
os.rst
ossaudiodev.rst
pathlib-inheritance.png
pathlib-inheritance.svg
pathlib.rst
pdb.rst
persistence.rst
pickle.rst
pickletools.rst
pipes.rst
pkgutil.rst
platform.rst
plistlib.rst
poplib.rst
posix.rst
pprint.rst	gh-126731: Update outdated project information in pprint.pp doc (#126732)	2024-11-13 20:58:06 -08:00
profile.rst
pty.rst
pwd.rst
py_compile.rst
pyclbr.rst
pydoc.rst
pyexpat.rst
python.rst
queue.rst
quopri.rst
random.rst
re.rst
readline.rst
removed.rst
reprlib.rst
resource.rst
rlcompleter.rst
runpy.rst
sched.rst
secrets.rst
security_warnings.rst
select.rst
selectors.rst
shelve.rst
shlex.rst
shutil.rst
signal.rst
site.rst
smtpd.rst
smtplib.rst
sndhdr.rst
socket.rst	gh-123832: Adjust socket.getaddrinfo docs for better POSIX compliance (GH-126182)	2024-11-14 09:31:14 +01:00
socketserver.rst
spwd.rst
sqlite3.rst
ssl.rst
stat.rst
statistics.rst
stdtypes.rst
string.rst
stringprep.rst
struct.rst
subprocess.rst
sunau.rst
superseded.rst
symtable.rst
sys_path_init.rst
sys.monitoring.rst
sys.rst
sysconfig.rst
syslog.rst
tabnanny.rst
tarfile.rst
telnetlib.rst
tempfile.rst
termios.rst
test.rst
text.rst
textwrap.rst
threading.rst
time.rst
timeit.rst
tk_msg.png
tk.rst
tkinter.colorchooser.rst
tkinter.dnd.rst
tkinter.font.rst
tkinter.messagebox.rst
tkinter.rst
tkinter.scrolledtext.rst
tkinter.ttk.rst
token-list.inc
token.rst
tokenize.rst
tomllib.rst	gh-126175: Add attributes to TOMLDecodeError. Deprecate free-form __init__ args (GH-126428)	2024-11-13 13:52:16 +01:00
trace.rst
traceback.rst
tracemalloc.rst
tty.rst
tulip_coro.dia
tulip_coro.png
turtle-star.pdf
turtle-star.png
turtle-star.ps
turtle.rst
types.rst
typing.rst
unicodedata.rst
unittest.mock-examples.rst
unittest.mock.rst
unittest.rst
unix.rst
urllib.error.rst
urllib.parse.rst	gh-116897: Deprecate generic false values in urllib.parse.parse_qsl() (GH-116903)	2024-11-12 21:10:29 +02:00
urllib.request.rst
urllib.robotparser.rst
urllib.rst
uu.rst
uuid.rst	gh-89083: add support for UUID version 8 (RFC 9562) (#123224)	2024-11-12 19:08:49 +01:00
venv.rst
warnings.rst
wave.rst
weakref.rst
webbrowser.rst
windows.rst
winreg.rst
winsound.rst
wsgiref.rst
xdrlib.rst
xml.dom.minidom.rst
xml.dom.pulldom.rst
xml.dom.rst
xml.etree.elementtree.rst
xml.rst
xml.sax.handler.rst
xml.sax.reader.rst
xml.sax.rst
xml.sax.utils.rst
xmlrpc.client.rst
xmlrpc.rst
xmlrpc.server.rst
zipapp.rst
zipfile.rst
zipimport.rst
zlib.rst
zoneinfo.rst