Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-08 06:10:17 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-140615: Update docstrings in the fcntl module (GH-140619)

Browse source 
* 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.
This commit is contained in:
Serhiy Storchaka 2025-11-08 12:17:59 +02:00 • committed by GitHub
parent 7e90bac3cc
commit 610377056b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 97 additions and 91 deletions
Download patch file Download diff file Expand all files Collapse all files

90
Modules/clinic/fcntlmodule.c.h generated
View file

@ -8,17 +8,22 @@ PyDoc_STRVAR(fcntl_fcntl__doc__,
"fcntl($module, fd, cmd, arg=0, /)\n" "fcntl($module, fd, cmd, arg=0, /)\n"
"--\n" "--\n"
"\n" "\n"
"Perform the operation `cmd` on file descriptor fd.\n" "Perform the operation cmd on file descriptor fd.\n"
"\n" "\n"
"The values used for `cmd` are operating system dependent, and are available\n" "The values used for cmd are operating system dependent, and are\n"
"as constants in the fcntl module, using the same names as used in\n" "available as constants in the fcntl module, using the same names as used\n"
"the relevant C header files. The argument arg is optional, and\n" "in 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" "defaults to 0; it may be an integer, a bytes-like object or a string.\n"
"the return value of fcntl is a string of that length, containing the\n" "If arg is given as a string, it will be encoded to binary using the\n"
"resulting value put in the arg buffer by the operating system. The length\n" "UTF-8 encoding.\n"
"of the arg string is not allowed to exceed 1024 bytes. If the arg given\n" "\n"
"is an integer or if none is specified, the result value is an integer\n" "If the arg given is an integer or if none is specified, the result value\n"
"corresponding to the return value of the fcntl call in the C code."); "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 \ #define FCNTL_FCNTL_METHODDEF \
{"fcntl", _PyCFunction_CAST(fcntl_fcntl), METH_FASTCALL, fcntl_fcntl__doc__}, {"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" "ioctl($module, fd, request, arg=0, mutate_flag=True, /)\n"
"--\n" "--\n"
"\n" "\n"
"Perform the operation `request` on file descriptor `fd`.\n" "Perform the operation request on file descriptor fd.\n"
"\n" "\n"
"The values used for `request` are operating system dependent, and are available\n" "The values used for request are operating system dependent, and are\n"
"as constants in the fcntl or termios library modules, using the same names as\n" "available as constants in the fcntl or termios library modules, using\n"
"used in the relevant C header files.\n" "the same names as used in the relevant C header files.\n"
"\n" "\n"
"The argument `arg` is optional, and defaults to 0; it may be an int or a\n" "The argument arg is optional, and defaults to 0; it may be an integer, a\n"
"buffer containing character data (most likely a string or an array).\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" "\n"
"If the argument is a mutable buffer (such as an array) and if the\n" "If the arg given is an integer or if none is specified, the result value\n"
"mutate_flag argument (which is only allowed in this case) is true then the\n" "is an integer corresponding to the return value of the ioctl() call in\n"
"buffer is (in effect) passed to the operating system and changes made by\n" "the C code.\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"
"\n" "\n"
"If the argument is a mutable buffer and the mutable_flag argument is false,\n" "If the argument is a mutable buffer (such as a bytearray) and the\n"
"the behavior is as if a string had been passed.\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" "\n"
"If the argument is an immutable buffer (most likely a string) then a copy\n" "If the argument is a mutable buffer and the mutable_flag argument is\n"
"of the buffer is passed to the operating system and the return value is a\n" "false, the behavior is as if an immutable buffer had been passed.\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"
"\n" "\n"
"If the arg given is an integer or if none is specified, the result value is\n" "If the argument is an immutable buffer then a copy of the buffer is\n"
"an integer corresponding to the return value of the ioctl call in the C\n" "passed to the operating system and the return value is a bytes object of\n"
"code."); "the same length containing whatever the operating system put in the\n"
"buffer.");
#define FCNTL_IOCTL_METHODDEF \ #define FCNTL_IOCTL_METHODDEF \
{"ioctl", _PyCFunction_CAST(fcntl_ioctl), METH_FASTCALL, fcntl_ioctl__doc__}, {"ioctl", _PyCFunction_CAST(fcntl_ioctl), METH_FASTCALL, fcntl_ioctl__doc__},
@ -154,7 +158,7 @@ PyDoc_STRVAR(fcntl_flock__doc__,
"flock($module, fd, operation, /)\n" "flock($module, fd, operation, /)\n"
"--\n" "--\n"
"\n" "\n"
"Perform the lock operation `operation` on file descriptor `fd`.\n" "Perform the lock operation on file descriptor fd.\n"
"\n" "\n"
"See the Unix manual page for flock(2) for details (On some systems, this\n" "See the Unix manual page for flock(2) for details (On some systems, this\n"
"function is emulated using fcntl())."); "function is emulated using fcntl()).");
@ -195,22 +199,22 @@ PyDoc_STRVAR(fcntl_lockf__doc__,
"\n" "\n"
"A wrapper around the fcntl() locking calls.\n" "A wrapper around the fcntl() locking calls.\n"
"\n" "\n"
"`fd` is the file descriptor of the file to lock or unlock, and operation is one\n" "fd is the file descriptor of the file to lock or unlock, and operation\n"
"of the following values:\n" "is one of the following values:\n"
"\n" "\n"
" LOCK_UN - unlock\n" " LOCK_UN - unlock\n"
" LOCK_SH - acquire a shared lock\n" " LOCK_SH - acquire a shared lock\n"
" LOCK_EX - acquire an exclusive lock\n" " LOCK_EX - acquire an exclusive lock\n"
"\n" "\n"
"When operation is LOCK_SH or LOCK_EX, it can also be bitwise ORed with\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_NB to avoid blocking on lock acquisition. If LOCK_NB is used and\n"
"lock cannot be acquired, an OSError will be raised and the exception will\n" "the lock cannot be acquired, an OSError will be raised and the exception\n"
"have an errno attribute set to EACCES or EAGAIN (depending on the operating\n" "will have an errno attribute set to EACCES or EAGAIN (depending on the\n"
"system -- for portability, check for either value).\n" "operating system -- for portability, check for either value).\n"
"\n" "\n"
"`len` is the number of bytes to lock, with the default meaning to lock to\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" "EOF. start is the byte offset, relative to whence, to that the lock\n"
"starts. `whence` is as with fileobj.seek(), specifically:\n" "starts. whence is as with fileobj.seek(), specifically:\n"
"\n" "\n"
" 0 - relative to the start of the file (SEEK_SET)\n" " 0 - relative to the start of the file (SEEK_SET)\n"
" 1 - relative to the current buffer position (SEEK_CUR)\n" " 1 - relative to the current buffer position (SEEK_CUR)\n"
@ -265,4 +269,4 @@ skip_optional:
exit: exit:
return return_value; return return_value;
} }
/*[clinic end generated code: output=9773e44da302dc7c input=a9049054013a1b77]*/ /*[clinic end generated code: output=c782fcf9dd6690e0 input=a9049054013a1b77]*/

98
Modules/fcntlmodule.c
View file

@ -40,22 +40,27 @@ fcntl.fcntl
arg: object(c_default='NULL') = 0 arg: object(c_default='NULL') = 0
/ /
Perform the operation `cmd` on file descriptor fd. Perform the operation cmd on file descriptor fd.
The values used for `cmd` are operating system dependent, and are available The values used for cmd are operating system dependent, and are
as constants in the fcntl module, using the same names as used in available as constants in the fcntl module, using the same names as used
the relevant C header files. The argument arg is optional, and 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, defaults to 0; it may be an integer, a bytes-like object or a string.
the return value of fcntl is a string of that length, containing the If arg is given as a string, it will be encoded to binary using the
resulting value put in the arg buffer by the operating system. The length UTF-8 encoding.
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 If the arg given is an integer or if none is specified, the result value
corresponding to the return value of the fcntl call in the C code. 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]*/ [clinic start generated code]*/
static PyObject * static PyObject *
fcntl_fcntl_impl(PyObject *module, int fd, int code, PyObject *arg) 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 ret;
int async_err = 0; int async_err = 0;
@ -151,7 +156,6 @@ fcntl_fcntl_impl(PyObject *module, int fd, int code, PyObject *arg)
/*[clinic input] /*[clinic input]
@permit_long_docstring_body
fcntl.ioctl fcntl.ioctl
fd: fildes fd: fildes
@ -160,40 +164,39 @@ fcntl.ioctl
mutate_flag as mutate_arg: bool = True 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 The values used for request are operating system dependent, and are
as constants in the fcntl or termios library modules, using the same names as available as constants in the fcntl or termios library modules, using
used in the relevant C header files. 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 The argument arg is optional, and defaults to 0; it may be an integer, a
buffer containing character data (most likely a string or an array). 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 If the arg given is an integer or if none is specified, the result value
mutate_flag argument (which is only allowed in this case) is true then the is an integer corresponding to the return value of the ioctl() call in
buffer is (in effect) passed to the operating system and changes made by the C code.
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 a mutable buffer and the mutable_flag argument is false, If the argument is a mutable buffer (such as a bytearray) and the
the behavior is as if a string had been passed. 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 If the argument is a mutable buffer and the mutable_flag argument is
of the buffer is passed to the operating system and the return value is a false, the behavior is as if an immutable buffer had been passed.
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 arg given is an integer or if none is specified, the result value is If the argument is an immutable buffer then a copy of the buffer is
an integer corresponding to the return value of the ioctl call in the C passed to the operating system and the return value is a bytes object of
code. the same length containing whatever the operating system put in the
buffer.
[clinic start generated code]*/ [clinic start generated code]*/
static PyObject * static PyObject *
fcntl_ioctl_impl(PyObject *module, int fd, unsigned long code, PyObject *arg, fcntl_ioctl_impl(PyObject *module, int fd, unsigned long code, PyObject *arg,
int mutate_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 /* We use the unsigned non-checked 'I' format for the 'code' parameter
because the system expects it to be a 32bit bit field value because the system expects it to be a 32bit bit field value
@ -340,7 +343,7 @@ fcntl.flock
operation as code: int 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 See the Unix manual page for flock(2) for details (On some systems, this
function is emulated using fcntl()). function is emulated using fcntl()).
@ -348,7 +351,7 @@ function is emulated using fcntl()).
static PyObject * static PyObject *
fcntl_flock_impl(PyObject *module, int fd, int code) 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 ret;
int async_err = 0; int async_err = 0;
@ -400,7 +403,6 @@ fcntl_flock_impl(PyObject *module, int fd, int code)
/*[clinic input] /*[clinic input]
@permit_long_docstring_body
fcntl.lockf fcntl.lockf
fd: fildes fd: fildes
@ -412,22 +414,22 @@ fcntl.lockf
A wrapper around the fcntl() locking calls. A wrapper around the fcntl() locking calls.
`fd` is the file descriptor of the file to lock or unlock, and operation is one fd is the file descriptor of the file to lock or unlock, and operation
of the following values: is one of the following values:
LOCK_UN - unlock LOCK_UN - unlock
LOCK_SH - acquire a shared lock LOCK_SH - acquire a shared lock
LOCK_EX - acquire an exclusive lock LOCK_EX - acquire an exclusive lock
When operation is LOCK_SH or LOCK_EX, it can also be bitwise ORed with 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_NB to avoid blocking on lock acquisition. If LOCK_NB is used and
lock cannot be acquired, an OSError will be raised and the exception will the lock cannot be acquired, an OSError will be raised and the exception
have an errno attribute set to EACCES or EAGAIN (depending on the operating will have an errno attribute set to EACCES or EAGAIN (depending on the
system -- for portability, check for either value). operating system -- for portability, check for either value).
`len` is the number of bytes to lock, with the default meaning to lock to 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 EOF. start is the byte offset, relative to whence, to that the lock
starts. `whence` is as with fileobj.seek(), specifically: starts. whence is as with fileobj.seek(), specifically:
0 - relative to the start of the file (SEEK_SET) 0 - relative to the start of the file (SEEK_SET)
1 - relative to the current buffer position (SEEK_CUR) 1 - relative to the current buffer position (SEEK_CUR)
@ -437,7 +439,7 @@ starts. `whence` is as with fileobj.seek(), specifically:
static PyObject * static PyObject *
fcntl_lockf_impl(PyObject *module, int fd, int code, PyObject *lenobj, fcntl_lockf_impl(PyObject *module, int fd, int code, PyObject *lenobj,
PyObject *startobj, int whence) PyObject *startobj, int whence)
/*[clinic end generated code: output=4985e7a172e7461a input=f666662ec2edd775]*/ /*[clinic end generated code: output=4985e7a172e7461a input=369bef4d7a1c5ff4]*/
{ {
int ret; int ret;
int async_err = 0; int async_err = 0;