Document that the built-in open() when called with a file descriptor ignores "mode" argument

[piotr-dobrogost]

At https://docs.python.org/3/library/functions.html#open, in the documentation of the mode argument there is no information that this argument is ignored when the function is called with a file descriptor instead of a path.

See Why does os.fdopen ignore mode? SO question. The question talks about os.fdopen() but according to https://docs.python.org/3/library/os.html#os.fdopen

This is an alias of the open() built-in function and accepts the same arguments.

so I think it should be enough to place the information in the documentation of the mode argument of the built-in open() function. This way it would document the built-in open() function but also the os.fdopen() function by virtue of the latter being an alias of the former.

[tiran]

builtin open() does not ignore the mode parameter. The argument is used to determinate the type of object. The open() function does not verify that the properties of the fd matches the arguments:

>>> fd = os.open("testfile.txt", os.O_WRONLY | os.O_CREAT)

>>> f1 = open(fd, mode="r")
>>> f1
<_io.TextIOWrapper name=3 mode='r' encoding='UTF-8'>
>>> f1.read()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: [Errno 9] Bad file descriptor
>>> f1.write("foo")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
io.UnsupportedOperation: not writable

>>> f2 = open(fd, mode="rb")
>>> f2
<_io.BufferedReader name=3>

[piotr-dobrogost]

The open() function does not verify that the properties of the fd matches the arguments

Well, this is surprising. If the properties of the fd can't be verified (or it's undesired for them to be verified for some reason) then it should be clearly stated in the documentation that it's a caller's responsibility to match them with the value of the mode argument. Also in this case there should be information on what exactly matching the properties of the fd means.