https://github.com/python/cpython/commit/610377056bad696915d70590429e68002bee9006
commit: 610377056bad696915d70590429e68002bee9006
branch: main
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2025-11-08T12:17:59+02:00
summary:
gh-140615: Update docstrings in the fcntl module (GH-140619)
* Refer to bytes objects or bytes-like objects instead of strings.
* Remove backticks -- they do not have effect on formatting.
* Re-wrap lines to ensure the pydoc output fits in 80 coluimns.
* Remove references to the 1024 bytes limit.
files:
M Modules/clinic/fcntlmodule.c.h
M Modules/fcntlmodule.c
diff --git a/Modules/clinic/fcntlmodule.c.h b/Modules/clinic/fcntlmodule.c.h
index 2b61d9f87083f0..718f80bfe736a2 100644
--- a/Modules/clinic/fcntlmodule.c.h
+++ b/Modules/clinic/fcntlmodule.c.h
@@ -8,17 +8,22 @@ PyDoc_STRVAR(fcntl_fcntl__doc__,
"fcntl($module, fd, cmd, arg=0, /)\n"
"--\n"
"\n"
-"Perform the operation `cmd` on file descriptor fd.\n"
+"Perform the operation cmd on file descriptor fd.\n"
"\n"
-"The values used for `cmd` are operating system dependent, and are available\n"
-"as constants in the fcntl module, using the same names as used in\n"
-"the relevant C header files. The argument arg is optional, and\n"
-"defaults to 0; it may be an int or a string. If arg is given as a string,\n"
-"the return value of fcntl is a string of that length, containing the\n"
-"resulting value put in the arg buffer by the operating system. The length\n"
-"of the arg string is not allowed to exceed 1024 bytes. If the arg given\n"
-"is an integer or if none is specified, the result value is an integer\n"
-"corresponding to the return value of the fcntl call in the C code.");
+"The values used for cmd are operating system dependent, and are\n"
+"available as constants in the fcntl module, using the same names as used\n"
+"in the relevant C header files. The argument arg is optional, and\n"
+"defaults to 0; it may be an integer, a bytes-like object or a string.\n"
+"If arg is given as a string, it will be encoded to binary using the\n"
+"UTF-8 encoding.\n"
+"\n"
+"If the arg given is an integer or if none is specified, the result value\n"
+"is an integer corresponding to the return value of the fcntl() call in\n"
+"the C code.\n"
+"\n"
+"If arg is given as a bytes-like object, the return value of fcntl() is a\n"
+"bytes object of that length, containing the resulting value put in the\n"
+"arg buffer by the operating system.");
#define FCNTL_FCNTL_METHODDEF \
{"fcntl", _PyCFunction_CAST(fcntl_fcntl), METH_FASTCALL,
fcntl_fcntl__doc__},
@@ -60,34 +65,33 @@ PyDoc_STRVAR(fcntl_ioctl__doc__,
"ioctl($module, fd, request, arg=0, mutate_flag=True, /)\n"
"--\n"
"\n"
-"Perform the operation `request` on file descriptor `fd`.\n"
+"Perform the operation request on file descriptor fd.\n"
"\n"
-"The values used for `request` are operating system dependent, and are
available\n"
-"as constants in the fcntl or termios library modules, using the same names
as\n"
-"used in the relevant C header files.\n"
+"The values used for request are operating system dependent, and are\n"
+"available as constants in the fcntl or termios library modules, using\n"
+"the same names as used in the relevant C header files.\n"
"\n"
-"The argument `arg` is optional, and defaults to 0; it may be an int or a\n"
-"buffer containing character data (most likely a string or an array).\n"
+"The argument arg is optional, and defaults to 0; it may be an integer, a\n"
+"bytes-like object or a string. If arg is given as a string, it will be\n"
+"encoded to binary using the UTF-8 encoding.\n"
"\n"
-"If the argument is a mutable buffer (such as an array) and if the\n"
-"mutate_flag argument (which is only allowed in this case) is true then the\n"
-"buffer is (in effect) passed to the operating system and changes made by\n"
-"the OS will be reflected in the contents of the buffer after the call has\n"
-"returned. The return value is the integer returned by the ioctl system\n"
-"call.\n"
+"If the arg given is an integer or if none is specified, the result value\n"
+"is an integer corresponding to the return value of the ioctl() call in\n"
+"the C code.\n"
"\n"
-"If the argument is a mutable buffer and the mutable_flag argument is false,\n"
-"the behavior is as if a string had been passed.\n"
+"If the argument is a mutable buffer (such as a bytearray) and the\n"
+"mutate_flag argument is true (default) then the buffer is (in effect)\n"
+"passed to the operating system and changes made by the OS will be\n"
+"reflected in the contents of the buffer after the call has returned.\n"
+"The return value is the integer returned by the ioctl() system call.\n"
"\n"
-"If the argument is an immutable buffer (most likely a string) then a copy\n"
-"of the buffer is passed to the operating system and the return value is a\n"
-"string of the same length containing whatever the operating system put in\n"
-"the buffer. The length of the arg buffer in this case is not allowed to\n"
-"exceed 1024 bytes.\n"
+"If the argument is a mutable buffer and the mutable_flag argument is\n"
+"false, the behavior is as if an immutable buffer had been passed.\n"
"\n"
-"If the arg given is an integer or if none is specified, the result value is\n"
-"an integer corresponding to the return value of the ioctl call in the C\n"
-"code.");
+"If the argument is an immutable buffer then a copy of the buffer is\n"
+"passed to the operating system and the return value is a bytes object of\n"
+"the same length containing whatever the operating system put in the\n"
+"buffer.");
#define FCNTL_IOCTL_METHODDEF \
{"ioctl", _PyCFunction_CAST(fcntl_ioctl), METH_FASTCALL,
fcntl_ioctl__doc__},
@@ -154,7 +158,7 @@ PyDoc_STRVAR(fcntl_flock__doc__,
"flock($module, fd, operation, /)\n"
"--\n"
"\n"
-"Perform the lock operation `operation` on file descriptor `fd`.\n"
+"Perform the lock operation on file descriptor fd.\n"
"\n"
"See the Unix manual page for flock(2) for details (On some systems, this\n"
"function is emulated using fcntl()).");
@@ -195,22 +199,22 @@ PyDoc_STRVAR(fcntl_lockf__doc__,
"\n"
"A wrapper around the fcntl() locking calls.\n"
"\n"
-"`fd` is the file descriptor of the file to lock or unlock, and operation is
one\n"
-"of the following values:\n"
+"fd is the file descriptor of the file to lock or unlock, and operation\n"
+"is one of the following values:\n"
"\n"
" LOCK_UN - unlock\n"
" LOCK_SH - acquire a shared lock\n"
" LOCK_EX - acquire an exclusive lock\n"
"\n"
"When operation is LOCK_SH or LOCK_EX, it can also be bitwise ORed with\n"
-"LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and the\n"
-"lock cannot be acquired, an OSError will be raised and the exception will\n"
-"have an errno attribute set to EACCES or EAGAIN (depending on the operating\n"
-"system -- for portability, check for either value).\n"
+"LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and\n"
+"the lock cannot be acquired, an OSError will be raised and the exception\n"
+"will have an errno attribute set to EACCES or EAGAIN (depending on the\n"
+"operating system -- for portability, check for either value).\n"
"\n"
-"`len` is the number of bytes to lock, with the default meaning to lock to\n"
-"EOF. `start` is the byte offset, relative to `whence`, to that the lock\n"
-"starts. `whence` is as with fileobj.seek(), specifically:\n"
+"len is the number of bytes to lock, with the default meaning to lock to\n"
+"EOF. start is the byte offset, relative to whence, to that the lock\n"
+"starts. whence is as with fileobj.seek(), specifically:\n"
"\n"
" 0 - relative to the start of the file (SEEK_SET)\n"
" 1 - relative to the current buffer position (SEEK_CUR)\n"
@@ -265,4 +269,4 @@ fcntl_lockf(PyObject *module, PyObject *const *args,
Py_ssize_t nargs)
exit:
return return_value;
}
-/*[clinic end generated code: output=9773e44da302dc7c input=a9049054013a1b77]*/
+/*[clinic end generated code: output=c782fcf9dd6690e0 input=a9049054013a1b77]*/
diff --git a/Modules/fcntlmodule.c b/Modules/fcntlmodule.c
index df2c9994127997..e373bf368813ac 100644
--- a/Modules/fcntlmodule.c
+++ b/Modules/fcntlmodule.c
@@ -40,22 +40,27 @@ fcntl.fcntl
arg: object(c_default='NULL') = 0
/
-Perform the operation `cmd` on file descriptor fd.
-
-The values used for `cmd` are operating system dependent, and are available
-as constants in the fcntl module, using the same names as used in
-the relevant C header files. The argument arg is optional, and
-defaults to 0; it may be an int or a string. If arg is given as a string,
-the return value of fcntl is a string of that length, containing the
-resulting value put in the arg buffer by the operating system. The length
-of the arg string is not allowed to exceed 1024 bytes. If the arg given
-is an integer or if none is specified, the result value is an integer
-corresponding to the return value of the fcntl call in the C code.
+Perform the operation cmd on file descriptor fd.
+
+The values used for cmd are operating system dependent, and are
+available as constants in the fcntl module, using the same names as used
+in the relevant C header files. The argument arg is optional, and
+defaults to 0; it may be an integer, a bytes-like object or a string.
+If arg is given as a string, it will be encoded to binary using the
+UTF-8 encoding.
+
+If the arg given is an integer or if none is specified, the result value
+is an integer corresponding to the return value of the fcntl() call in
+the C code.
+
+If arg is given as a bytes-like object, the return value of fcntl() is a
+bytes object of that length, containing the resulting value put in the
+arg buffer by the operating system.
[clinic start generated code]*/
static PyObject *
fcntl_fcntl_impl(PyObject *module, int fd, int code, PyObject *arg)
-/*[clinic end generated code: output=888fc93b51c295bd input=7955340198e5f334]*/
+/*[clinic end generated code: output=888fc93b51c295bd input=77340720f11665da]*/
{
int ret;
int async_err = 0;
@@ -151,7 +156,6 @@ fcntl_fcntl_impl(PyObject *module, int fd, int code,
PyObject *arg)
/*[clinic input]
-@permit_long_docstring_body
fcntl.ioctl
fd: fildes
@@ -160,40 +164,39 @@ fcntl.ioctl
mutate_flag as mutate_arg: bool = True
/
-Perform the operation `request` on file descriptor `fd`.
+Perform the operation request on file descriptor fd.
-The values used for `request` are operating system dependent, and are available
-as constants in the fcntl or termios library modules, using the same names as
-used in the relevant C header files.
+The values used for request are operating system dependent, and are
+available as constants in the fcntl or termios library modules, using
+the same names as used in the relevant C header files.
-The argument `arg` is optional, and defaults to 0; it may be an int or a
-buffer containing character data (most likely a string or an array).
+The argument arg is optional, and defaults to 0; it may be an integer, a
+bytes-like object or a string. If arg is given as a string, it will be
+encoded to binary using the UTF-8 encoding.
-If the argument is a mutable buffer (such as an array) and if the
-mutate_flag argument (which is only allowed in this case) is true then the
-buffer is (in effect) passed to the operating system and changes made by
-the OS will be reflected in the contents of the buffer after the call has
-returned. The return value is the integer returned by the ioctl system
-call.
+If the arg given is an integer or if none is specified, the result value
+is an integer corresponding to the return value of the ioctl() call in
+the C code.
-If the argument is a mutable buffer and the mutable_flag argument is false,
-the behavior is as if a string had been passed.
+If the argument is a mutable buffer (such as a bytearray) and the
+mutate_flag argument is true (default) then the buffer is (in effect)
+passed to the operating system and changes made by the OS will be
+reflected in the contents of the buffer after the call has returned.
+The return value is the integer returned by the ioctl() system call.
-If the argument is an immutable buffer (most likely a string) then a copy
-of the buffer is passed to the operating system and the return value is a
-string of the same length containing whatever the operating system put in
-the buffer. The length of the arg buffer in this case is not allowed to
-exceed 1024 bytes.
+If the argument is a mutable buffer and the mutable_flag argument is
+false, the behavior is as if an immutable buffer had been passed.
-If the arg given is an integer or if none is specified, the result value is
-an integer corresponding to the return value of the ioctl call in the C
-code.
+If the argument is an immutable buffer then a copy of the buffer is
+passed to the operating system and the return value is a bytes object of
+the same length containing whatever the operating system put in the
+buffer.
[clinic start generated code]*/
static PyObject *
fcntl_ioctl_impl(PyObject *module, int fd, unsigned long code, PyObject *arg,
int mutate_arg)
-/*[clinic end generated code: output=f72baba2454d7a62 input=d7fe504d335449e2]*/
+/*[clinic end generated code: output=f72baba2454d7a62 input=954fe75c208cc492]*/
{
/* We use the unsigned non-checked 'I' format for the 'code' parameter
because the system expects it to be a 32bit bit field value
@@ -340,7 +343,7 @@ fcntl.flock
operation as code: int
/
-Perform the lock operation `operation` on file descriptor `fd`.
+Perform the lock operation on file descriptor fd.
See the Unix manual page for flock(2) for details (On some systems, this
function is emulated using fcntl()).
@@ -348,7 +351,7 @@ function is emulated using fcntl()).
static PyObject *
fcntl_flock_impl(PyObject *module, int fd, int code)
-/*[clinic end generated code: output=84059e2b37d2fc64 input=0bfc00f795953452]*/
+/*[clinic end generated code: output=84059e2b37d2fc64 input=ade68943e8599f0a]*/
{
int ret;
int async_err = 0;
@@ -400,7 +403,6 @@ fcntl_flock_impl(PyObject *module, int fd, int code)
/*[clinic input]
-@permit_long_docstring_body
fcntl.lockf
fd: fildes
@@ -412,22 +414,22 @@ fcntl.lockf
A wrapper around the fcntl() locking calls.
-`fd` is the file descriptor of the file to lock or unlock, and operation is one
-of the following values:
+fd is the file descriptor of the file to lock or unlock, and operation
+is one of the following values:
LOCK_UN - unlock
LOCK_SH - acquire a shared lock
LOCK_EX - acquire an exclusive lock
When operation is LOCK_SH or LOCK_EX, it can also be bitwise ORed with
-LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and the
-lock cannot be acquired, an OSError will be raised and the exception will
-have an errno attribute set to EACCES or EAGAIN (depending on the operating
-system -- for portability, check for either value).
+LOCK_NB to avoid blocking on lock acquisition. If LOCK_NB is used and
+the lock cannot be acquired, an OSError will be raised and the exception
+will have an errno attribute set to EACCES or EAGAIN (depending on the
+operating system -- for portability, check for either value).
-`len` is the number of bytes to lock, with the default meaning to lock to
-EOF. `start` is the byte offset, relative to `whence`, to that the lock
-starts. `whence` is as with fileobj.seek(), specifically:
+len is the number of bytes to lock, with the default meaning to lock to
+EOF. start is the byte offset, relative to whence, to that the lock
+starts. whence is as with fileobj.seek(), specifically:
0 - relative to the start of the file (SEEK_SET)
1 - relative to the current buffer position (SEEK_CUR)
@@ -437,7 +439,7 @@ starts. `whence` is as with fileobj.seek(), specifically:
static PyObject *
fcntl_lockf_impl(PyObject *module, int fd, int code, PyObject *lenobj,
PyObject *startobj, int whence)
-/*[clinic end generated code: output=4985e7a172e7461a input=f666662ec2edd775]*/
+/*[clinic end generated code: output=4985e7a172e7461a input=369bef4d7a1c5ff4]*/
{
int ret;
int async_err = 0;
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
