traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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 2018-11-02 15:20:19 +00:00 committed by Pablo Galindo
parent 488c0a6cdf
commit b942707fc2
3 changed files with 33 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Misc/NEWS.d/next/Core and Builtins/2018-10-25-20-53-32.bpo-29341.jH-AMF.rst Normal file
View File

@ -0,0 +1,2 @@
Clarify in the docstrings of :mod:`os` methods that path-like objects are also accepted
as input parameters.

22
Modules/clinic/posixmodule.c.h generated
View File

@ -9,7 +9,7 @@ PyDoc_STRVAR(os_stat__doc__,
"Perform a stat system call on the given path.\n" "Perform a stat system call on the given path.\n"
"\n" "\n"
" path\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" " open-file-descriptor int.\n"
" dir_fd\n" " dir_fd\n"
" If not None, it should be a file descriptor open to a directory,\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" "Use the real uid/gid to test for access to a path.\n"
"\n" "\n"
" path\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" " mode\n"
" Operating-system mode bitfield. Can be F_OK to test existence,\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" " 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" "Change the access permissions of a file.\n"
"\n" "\n"
" path\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" " 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" " If this functionality is unavailable, using it raises an exception.\n"
" mode\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" "Change the owner and group id of path to the numeric uid and gid.\\\n"
"\n" "\n"
" path\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" " dir_fd\n"
" If not None, it should be a file descriptor open to a directory,\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" " and path should be relative; path will then be relative to that\n"
@ -889,7 +889,7 @@ PyDoc_STRVAR(os_listdir__doc__,
"\n" "\n"
"Return a list containing the names of the files in the directory.\n" "Return a list containing the names of the files in the directory.\n"
"\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 also be bytes; in all other circumstances\n"
" the filenames returned will be str.\n" " the filenames returned will be str.\n"
"If path is None, uses the path=\'.\'.\n" "If path is None, uses the path=\'.\'.\n"
@ -5532,7 +5532,7 @@ PyDoc_STRVAR(os_getxattr__doc__,
"\n" "\n"
"Return the value of extended attribute attribute on path.\n" "Return the value of extended attribute attribute on path.\n"
"\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" "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" " link, getxattr will examine the symbolic link itself instead of the file\n"
" the link points to."); " the link points to.");
@ -5580,7 +5580,7 @@ PyDoc_STRVAR(os_setxattr__doc__,
"\n" "\n"
"Set extended attribute attribute on path to value.\n" "Set extended attribute attribute on path to value.\n"
"\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" "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" " link, setxattr will modify the symbolic link itself instead of the file\n"
" the link points to."); " the link points to.");
@ -5633,7 +5633,7 @@ PyDoc_STRVAR(os_removexattr__doc__,
"\n" "\n"
"Remove extended attribute attribute on path.\n" "Remove extended attribute attribute on path.\n"
"\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" "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" " link, removexattr will modify the symbolic link itself instead of the file\n"
" the link points to."); " the link points to.");
@ -5680,7 +5680,7 @@ PyDoc_STRVAR(os_listxattr__doc__,
"\n" "\n"
"Return a list of extended attributes on path.\n" "Return a list of extended attributes on path.\n"
"\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 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" "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" " link, listxattr will examine the symbolic link itself instead of the file\n"
@ -6140,7 +6140,7 @@ PyDoc_STRVAR(os_scandir__doc__,
"\n" "\n"
"Return an iterator of DirEntry objects for given path.\n" "Return an iterator of DirEntry objects for given path.\n"
"\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" "is bytes, the names of yielded DirEntry objects will also be bytes; in\n"
"all other circumstances they will be str.\n" "all other circumstances they will be str.\n"
"\n" "\n"
@ -6757,4 +6757,4 @@ exit:
#ifndef OS_GETRANDOM_METHODDEF #ifndef OS_GETRANDOM_METHODDEF
#define OS_GETRANDOM_METHODDEF #define OS_GETRANDOM_METHODDEF
#endif /* !defined(OS_GETRANDOM_METHODDEF) */ #endif /* !defined(OS_GETRANDOM_METHODDEF) */
/*[clinic end generated code: output=1603fddefffa1fb9 input=a9049054013a1b77]*/ /*[clinic end generated code: output=f2951c34e0907fb6 input=a9049054013a1b77]*/

40
Modules/posixmodule.c
View File

@ -2480,7 +2480,7 @@ class sched_param_converter(CConverter):
os.stat os.stat
path : path_t(allow_fd=True) 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. 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 * static PyObject *
os_stat_impl(PyObject *module, path_t *path, int dir_fd, int follow_symlinks) 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); 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 os.access -> bool
path: path_t 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 mode: int
Operating-system mode bitfield. Can be F_OK to test existence, 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 static int
os_access_impl(PyObject *module, path_t *path, int mode, int dir_fd, os_access_impl(PyObject *module, path_t *path, int mode, int dir_fd,
int effective_ids, int follow_symlinks) 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; int return_value;
@ -2772,7 +2772,7 @@ os_fchdir_impl(PyObject *module, int fd)
os.chmod os.chmod
path: path_t(allow_fd='PATH_HAVE_FCHMOD') 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. On some platforms, path may also be specified as an open file descriptor.
If this functionality is unavailable, using it raises an exception. 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 * static PyObject *
os_chmod_impl(PyObject *module, path_t *path, int mode, int dir_fd, os_chmod_impl(PyObject *module, path_t *path, int mode, int dir_fd,
int follow_symlinks) int follow_symlinks)
/*[clinic end generated code: output=5cf6a94915cc7bff input=7f1618e5e15cc196]*/ /*[clinic end generated code: output=5cf6a94915cc7bff input=989081551c00293b]*/
{ {
int result; int result;
@ -3123,7 +3123,7 @@ os_fdatasync_impl(PyObject *module, int fd)
os.chown os.chown
path : path_t(allow_fd='PATH_HAVE_FCHOWN') 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 uid: uid_t
@ -3161,7 +3161,7 @@ dir_fd and follow_symlinks may not be implemented on your platform.
static PyObject * static PyObject *
os_chown_impl(PyObject *module, path_t *path, uid_t uid, gid_t gid, os_chown_impl(PyObject *module, path_t *path, uid_t uid, gid_t gid,
int dir_fd, int follow_symlinks) int dir_fd, int follow_symlinks)
/*[clinic end generated code: output=4beadab0db5f70cd input=a61cc35574814d5d]*/ /*[clinic end generated code: output=4beadab0db5f70cd input=b08c5ec67996a97d]*/
{ {
int result; int result;
@ -3688,7 +3688,7 @@ os.listdir
Return a list containing the names of the files in the directory. 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 also be bytes; in all other circumstances
the filenames returned will be str. the filenames returned will be str.
If path is None, uses the path='.'. If path is None, uses the path='.'.
@ -3704,7 +3704,7 @@ entries '.' and '..' even if they are present in the directory.
static PyObject * static PyObject *
os_listdir_impl(PyObject *module, path_t *path) 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) #if defined(MS_WINDOWS) && !defined(HAVE_OPENDIR)
return _listdir_windows_no_opendir(path, NULL); return _listdir_windows_no_opendir(path, NULL);
@ -11415,7 +11415,7 @@ os.getxattr
Return the value of extended attribute attribute on path. 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 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 link, getxattr will examine the symbolic link itself instead of the file
the link points to. 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 * static PyObject *
os_getxattr_impl(PyObject *module, path_t *path, path_t *attribute, os_getxattr_impl(PyObject *module, path_t *path, path_t *attribute,
int follow_symlinks) int follow_symlinks)
/*[clinic end generated code: output=5f2f44200a43cff2 input=8c8ea3bab78d89c2]*/ /*[clinic end generated code: output=5f2f44200a43cff2 input=025789491708f7eb]*/
{ {
Py_ssize_t i; Py_ssize_t i;
PyObject *buffer = NULL; PyObject *buffer = NULL;
@ -11487,7 +11487,7 @@ os.setxattr
Set extended attribute attribute on path to value. 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 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 link, setxattr will modify the symbolic link itself instead of the file
the link points to. 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 * static PyObject *
os_setxattr_impl(PyObject *module, path_t *path, path_t *attribute, os_setxattr_impl(PyObject *module, path_t *path, path_t *attribute,
Py_buffer *value, int flags, int follow_symlinks) 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; ssize_t result;
@ -11535,7 +11535,7 @@ os.removexattr
Remove extended attribute attribute on path. 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 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 link, removexattr will modify the symbolic link itself instead of the file
the link points to. 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 * static PyObject *
os_removexattr_impl(PyObject *module, path_t *path, path_t *attribute, os_removexattr_impl(PyObject *module, path_t *path, path_t *attribute,
int follow_symlinks) int follow_symlinks)
/*[clinic end generated code: output=521a51817980cda6 input=cdb54834161e3329]*/ /*[clinic end generated code: output=521a51817980cda6 input=3d9a7d36fe2f7c4e]*/
{ {
ssize_t result; ssize_t result;
@ -11578,7 +11578,7 @@ os.listxattr
Return a list of extended attributes on path. 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 path is None, listxattr will examine the current directory.
If follow_symlinks is False, and the last element of the path is a symbolic 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 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 * static PyObject *
os_listxattr_impl(PyObject *module, path_t *path, int follow_symlinks) 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; Py_ssize_t i;
PyObject *result = NULL; PyObject *result = NULL;
@ -12836,7 +12836,7 @@ os.scandir
Return an iterator of DirEntry objects for given path. 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 is bytes, the names of yielded DirEntry objects will also be bytes; in
all other circumstances they will be str. all other circumstances they will be str.
@ -12845,7 +12845,7 @@ If path is None, uses the path='.'.
static PyObject * static PyObject *
os_scandir_impl(PyObject *module, path_t *path) 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; ScandirIterator *iterator;
#ifdef MS_WINDOWS #ifdef MS_WINDOWS