bpo-29341: Clarify that path-like objects are accepted in some os methods (GH-10101)
Some methods in the os module can accept path-like objects. This is documented in the general documentation but not in the function docstrings. To keep both in sync, the docstrings need to be updated to reflect that path-like objects are also accepted.
This commit is contained in:
BNMetrics
Pablo Galindo
parent
488c0a6cdf
commit
b942707fc2
|
|
@ -0,0 +1,2 @@
|
|||
Clarify in the docstrings of :mod:`os` methods that path-like objects are also accepted
|
||||
as input parameters.
|
||||
|
|
@ -9,7 +9,7 @@ PyDoc_STRVAR(os_stat__doc__,
|
|||
"Perform a stat system call on the given path.\n"
|
||||
"\n"
|
||||
" path\n"
|
||||
" Path to be examined; can be string, bytes, path-like object or\n"
|
||||
" Path to be examined; can be string, bytes, a path-like object or\n"
|
||||
" open-file-descriptor int.\n"
|
||||
" dir_fd\n"
|
||||
" If not None, it should be a file descriptor open to a directory,\n"
|
||||
|
|
@ -101,7 +101,7 @@ PyDoc_STRVAR(os_access__doc__,
|
|||
"Use the real uid/gid to test for access to a path.\n"
|
||||
"\n"
|
||||
" path\n"
|
||||
" Path to be tested; can be string or bytes\n"
|
||||
" Path to be tested; can be string, bytes, or a path-like object.\n"
|
||||
" mode\n"
|
||||
" Operating-system mode bitfield. Can be F_OK to test existence,\n"
|
||||
" or the inclusive-OR of R_OK, W_OK, and X_OK.\n"
|
||||
|
|
@ -304,7 +304,7 @@ PyDoc_STRVAR(os_chmod__doc__,
|
|||
"Change the access permissions of a file.\n"
|
||||
"\n"
|
||||
" path\n"
|
||||
" Path to be modified. May always be specified as a str or bytes.\n"
|
||||
" Path to be modified. May always be specified as a str, bytes, or a path-like object.\n"
|
||||
" On some platforms, path may also be specified as an open file descriptor.\n"
|
||||
" If this functionality is unavailable, using it raises an exception.\n"
|
||||
" mode\n"
|
||||
|
|
@ -655,7 +655,7 @@ PyDoc_STRVAR(os_chown__doc__,
|
|||
"Change the owner and group id of path to the numeric uid and gid.\\\n"
|
||||
"\n"
|
||||
" path\n"
|
||||
" Path to be examined; can be string, bytes, or open-file-descriptor int.\n"
|
||||
" Path to be examined; can be string, bytes, a path-like object, or open-file-descriptor int.\n"
|
||||
" dir_fd\n"
|
||||
" If not None, it should be a file descriptor open to a directory,\n"
|
||||
" and path should be relative; path will then be relative to that\n"
|
||||
|
|
@ -889,7 +889,7 @@ PyDoc_STRVAR(os_listdir__doc__,
|
|||
"\n"
|
||||
"Return a list containing the names of the files in the directory.\n"
|
||||
"\n"
|
||||
"path can be specified as either str or bytes. If path is bytes,\n"
|
||||
"path can be specified as either str, bytes, or a path-like object. If path is bytes,\n"
|
||||
" the filenames returned will also be bytes; in all other circumstances\n"
|
||||
" the filenames returned will be str.\n"
|
||||
"If path is None, uses the path=\'.\'.\n"
|
||||
|
|
@ -5532,7 +5532,7 @@ PyDoc_STRVAR(os_getxattr__doc__,
|
|||
"\n"
|
||||
"Return the value of extended attribute attribute on path.\n"
|
||||
"\n"
|
||||
"path may be either a string or an open file descriptor.\n"
|
||||
"path may be either a string, a path-like object, or an open file descriptor.\n"
|
||||
"If follow_symlinks is False, and the last element of the path is a symbolic\n"
|
||||
" link, getxattr will examine the symbolic link itself instead of the file\n"
|
||||
" the link points to.");
|
||||
|
|
@ -5580,7 +5580,7 @@ PyDoc_STRVAR(os_setxattr__doc__,
|
|||
"\n"
|
||||
"Set extended attribute attribute on path to value.\n"
|
||||
"\n"
|
||||
"path may be either a string or an open file descriptor.\n"
|
||||
"path may be either a string, a path-like object, or an open file descriptor.\n"
|
||||
"If follow_symlinks is False, and the last element of the path is a symbolic\n"
|
||||
" link, setxattr will modify the symbolic link itself instead of the file\n"
|
||||
" the link points to.");
|
||||
|
|
@ -5633,7 +5633,7 @@ PyDoc_STRVAR(os_removexattr__doc__,
|
|||
"\n"
|
||||
"Remove extended attribute attribute on path.\n"
|
||||
"\n"
|
||||
"path may be either a string or an open file descriptor.\n"
|
||||
"path may be either a string, a path-like object, or an open file descriptor.\n"
|
||||
"If follow_symlinks is False, and the last element of the path is a symbolic\n"
|
||||
" link, removexattr will modify the symbolic link itself instead of the file\n"
|
||||
" the link points to.");
|
||||
|
|
@ -5680,7 +5680,7 @@ PyDoc_STRVAR(os_listxattr__doc__,
|
|||
"\n"
|
||||
"Return a list of extended attributes on path.\n"
|
||||
"\n"
|
||||
"path may be either None, a string, or an open file descriptor.\n"
|
||||
"path may be either None, a string, a path-like object, or an open file descriptor.\n"
|
||||
"if path is None, listxattr will examine the current directory.\n"
|
||||
"If follow_symlinks is False, and the last element of the path is a symbolic\n"
|
||||
" link, listxattr will examine the symbolic link itself instead of the file\n"
|
||||
|
|
@ -6140,7 +6140,7 @@ PyDoc_STRVAR(os_scandir__doc__,
|
|||
"\n"
|
||||
"Return an iterator of DirEntry objects for given path.\n"
|
||||
"\n"
|
||||
"path can be specified as either str, bytes or path-like object. If path\n"
|
||||
"path can be specified as either str, bytes, or a path-like object. If path\n"
|
||||
"is bytes, the names of yielded DirEntry objects will also be bytes; in\n"
|
||||
"all other circumstances they will be str.\n"
|
||||
"\n"
|
||||
|
|
@ -6757,4 +6757,4 @@ exit:
|
|||
#ifndef OS_GETRANDOM_METHODDEF
|
||||
#define OS_GETRANDOM_METHODDEF
|
||||
#endif /* !defined(OS_GETRANDOM_METHODDEF) */
|
||||
/*[clinic end generated code: output=1603fddefffa1fb9 input=a9049054013a1b77]*/
|
||||
/*[clinic end generated code: output=f2951c34e0907fb6 input=a9049054013a1b77]*/
|
||||
|
|
|
|||
|
|
@ -2480,7 +2480,7 @@ class sched_param_converter(CConverter):
|
|||
os.stat
|
||||
|
||||
path : path_t(allow_fd=True)
|
||||
Path to be examined; can be string, bytes, path-like object or
|
||||
Path to be examined; can be string, bytes, a path-like object or
|
||||
open-file-descriptor int.
|
||||
|
||||
*
|
||||
|
|
@ -2508,7 +2508,7 @@ It's an error to use dir_fd or follow_symlinks when specifying path as
|
|||
|
||||
static PyObject *
|
||||
os_stat_impl(PyObject *module, path_t *path, int dir_fd, int follow_symlinks)
|
||||
/*[clinic end generated code: output=7d4976e6f18a59c5 input=270bd64e7bb3c8f7]*/
|
||||
/*[clinic end generated code: output=7d4976e6f18a59c5 input=01d362ebcc06996b]*/
|
||||
{
|
||||
return posix_do_stat("stat", path, dir_fd, follow_symlinks);
|
||||
}
|
||||
|
|
@ -2542,7 +2542,7 @@ os_lstat_impl(PyObject *module, path_t *path, int dir_fd)
|
|||
os.access -> bool
|
||||
|
||||
path: path_t
|
||||
Path to be tested; can be string or bytes
|
||||
Path to be tested; can be string, bytes, or a path-like object.
|
||||
|
||||
mode: int
|
||||
Operating-system mode bitfield. Can be F_OK to test existence,
|
||||
|
|
@ -2580,7 +2580,7 @@ Note that most operations will use the effective uid/gid, therefore this
|
|||
static int
|
||||
os_access_impl(PyObject *module, path_t *path, int mode, int dir_fd,
|
||||
int effective_ids, int follow_symlinks)
|
||||
/*[clinic end generated code: output=cf84158bc90b1a77 input=8e8c3a6ba791fee3]*/
|
||||
/*[clinic end generated code: output=cf84158bc90b1a77 input=3ffe4e650ee3bf20]*/
|
||||
{
|
||||
int return_value;
|
||||
|
||||
|
|
@ -2772,7 +2772,7 @@ os_fchdir_impl(PyObject *module, int fd)
|
|||
os.chmod
|
||||
|
||||
path: path_t(allow_fd='PATH_HAVE_FCHMOD')
|
||||
Path to be modified. May always be specified as a str or bytes.
|
||||
Path to be modified. May always be specified as a str, bytes, or a path-like object.
|
||||
On some platforms, path may also be specified as an open file descriptor.
|
||||
If this functionality is unavailable, using it raises an exception.
|
||||
|
||||
|
|
@ -2803,7 +2803,7 @@ dir_fd and follow_symlinks may not be implemented on your platform.
|
|||
static PyObject *
|
||||
os_chmod_impl(PyObject *module, path_t *path, int mode, int dir_fd,
|
||||
int follow_symlinks)
|
||||
/*[clinic end generated code: output=5cf6a94915cc7bff input=7f1618e5e15cc196]*/
|
||||
/*[clinic end generated code: output=5cf6a94915cc7bff input=989081551c00293b]*/
|
||||
{
|
||||
int result;
|
||||
|
||||
|
|
@ -3123,7 +3123,7 @@ os_fdatasync_impl(PyObject *module, int fd)
|
|||
os.chown
|
||||
|
||||
path : path_t(allow_fd='PATH_HAVE_FCHOWN')
|
||||
Path to be examined; can be string, bytes, or open-file-descriptor int.
|
||||
Path to be examined; can be string, bytes, a path-like object, or open-file-descriptor int.
|
||||
|
||||
uid: uid_t
|
||||
|
||||
|
|
@ -3161,7 +3161,7 @@ dir_fd and follow_symlinks may not be implemented on your platform.
|
|||
static PyObject *
|
||||
os_chown_impl(PyObject *module, path_t *path, uid_t uid, gid_t gid,
|
||||
int dir_fd, int follow_symlinks)
|
||||
/*[clinic end generated code: output=4beadab0db5f70cd input=a61cc35574814d5d]*/
|
||||
/*[clinic end generated code: output=4beadab0db5f70cd input=b08c5ec67996a97d]*/
|
||||
{
|
||||
int result;
|
||||
|
||||
|
|
@ -3688,7 +3688,7 @@ os.listdir
|
|||
|
||||
Return a list containing the names of the files in the directory.
|
||||
|
||||
path can be specified as either str or bytes. If path is bytes,
|
||||
path can be specified as either str, bytes, or a path-like object. If path is bytes,
|
||||
the filenames returned will also be bytes; in all other circumstances
|
||||
the filenames returned will be str.
|
||||
If path is None, uses the path='.'.
|
||||
|
|
@ -3704,7 +3704,7 @@ entries '.' and '..' even if they are present in the directory.
|
|||
|
||||
static PyObject *
|
||||
os_listdir_impl(PyObject *module, path_t *path)
|
||||
/*[clinic end generated code: output=293045673fcd1a75 input=09e300416e3cd729]*/
|
||||
/*[clinic end generated code: output=293045673fcd1a75 input=e3f58030f538295d]*/
|
||||
{
|
||||
#if defined(MS_WINDOWS) && !defined(HAVE_OPENDIR)
|
||||
return _listdir_windows_no_opendir(path, NULL);
|
||||
|
|
@ -11415,7 +11415,7 @@ os.getxattr
|
|||
|
||||
Return the value of extended attribute attribute on path.
|
||||
|
||||
path may be either a string or an open file descriptor.
|
||||
path may be either a string, a path-like object, or an open file descriptor.
|
||||
If follow_symlinks is False, and the last element of the path is a symbolic
|
||||
link, getxattr will examine the symbolic link itself instead of the file
|
||||
the link points to.
|
||||
|
|
@ -11425,7 +11425,7 @@ If follow_symlinks is False, and the last element of the path is a symbolic
|
|||
static PyObject *
|
||||
os_getxattr_impl(PyObject *module, path_t *path, path_t *attribute,
|
||||
int follow_symlinks)
|
||||
/*[clinic end generated code: output=5f2f44200a43cff2 input=8c8ea3bab78d89c2]*/
|
||||
/*[clinic end generated code: output=5f2f44200a43cff2 input=025789491708f7eb]*/
|
||||
{
|
||||
Py_ssize_t i;
|
||||
PyObject *buffer = NULL;
|
||||
|
|
@ -11487,7 +11487,7 @@ os.setxattr
|
|||
|
||||
Set extended attribute attribute on path to value.
|
||||
|
||||
path may be either a string or an open file descriptor.
|
||||
path may be either a string, a path-like object, or an open file descriptor.
|
||||
If follow_symlinks is False, and the last element of the path is a symbolic
|
||||
link, setxattr will modify the symbolic link itself instead of the file
|
||||
the link points to.
|
||||
|
|
@ -11497,7 +11497,7 @@ If follow_symlinks is False, and the last element of the path is a symbolic
|
|||
static PyObject *
|
||||
os_setxattr_impl(PyObject *module, path_t *path, path_t *attribute,
|
||||
Py_buffer *value, int flags, int follow_symlinks)
|
||||
/*[clinic end generated code: output=98b83f63fdde26bb input=f0d26833992015c2]*/
|
||||
/*[clinic end generated code: output=98b83f63fdde26bb input=c17c0103009042f0]*/
|
||||
{
|
||||
ssize_t result;
|
||||
|
||||
|
|
@ -11535,7 +11535,7 @@ os.removexattr
|
|||
|
||||
Remove extended attribute attribute on path.
|
||||
|
||||
path may be either a string or an open file descriptor.
|
||||
path may be either a string, a path-like object, or an open file descriptor.
|
||||
If follow_symlinks is False, and the last element of the path is a symbolic
|
||||
link, removexattr will modify the symbolic link itself instead of the file
|
||||
the link points to.
|
||||
|
|
@ -11545,7 +11545,7 @@ If follow_symlinks is False, and the last element of the path is a symbolic
|
|||
static PyObject *
|
||||
os_removexattr_impl(PyObject *module, path_t *path, path_t *attribute,
|
||||
int follow_symlinks)
|
||||
/*[clinic end generated code: output=521a51817980cda6 input=cdb54834161e3329]*/
|
||||
/*[clinic end generated code: output=521a51817980cda6 input=3d9a7d36fe2f7c4e]*/
|
||||
{
|
||||
ssize_t result;
|
||||
|
||||
|
|
@ -11578,7 +11578,7 @@ os.listxattr
|
|||
|
||||
Return a list of extended attributes on path.
|
||||
|
||||
path may be either None, a string, or an open file descriptor.
|
||||
path may be either None, a string, a path-like object, or an open file descriptor.
|
||||
if path is None, listxattr will examine the current directory.
|
||||
If follow_symlinks is False, and the last element of the path is a symbolic
|
||||
link, listxattr will examine the symbolic link itself instead of the file
|
||||
|
|
@ -11587,7 +11587,7 @@ If follow_symlinks is False, and the last element of the path is a symbolic
|
|||
|
||||
static PyObject *
|
||||
os_listxattr_impl(PyObject *module, path_t *path, int follow_symlinks)
|
||||
/*[clinic end generated code: output=bebdb4e2ad0ce435 input=08cca53ac0b07c13]*/
|
||||
/*[clinic end generated code: output=bebdb4e2ad0ce435 input=9826edf9fdb90869]*/
|
||||
{
|
||||
Py_ssize_t i;
|
||||
PyObject *result = NULL;
|
||||
|
|
@ -12836,7 +12836,7 @@ os.scandir
|
|||
|
||||
Return an iterator of DirEntry objects for given path.
|
||||
|
||||
path can be specified as either str, bytes or path-like object. If path
|
||||
path can be specified as either str, bytes, or a path-like object. If path
|
||||
is bytes, the names of yielded DirEntry objects will also be bytes; in
|
||||
all other circumstances they will be str.
|
||||
|
||||
|
|
@ -12845,7 +12845,7 @@ If path is None, uses the path='.'.
|
|||
|
||||
static PyObject *
|
||||
os_scandir_impl(PyObject *module, path_t *path)
|
||||
/*[clinic end generated code: output=6eb2668b675ca89e input=b139dc1c57f60846]*/
|
||||
/*[clinic end generated code: output=6eb2668b675ca89e input=6bdd312708fc3bb0]*/
|
||||
{
|
||||
ScandirIterator *iterator;
|
||||
#ifdef MS_WINDOWS
|
||||
|
|
|
|||
Loading…
Reference in New Issue