mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Merged upstream changes.

Browse source
This commit is contained in:
Vinay Sajip 2012-06-24 11:24:05 +01:00
commit dd7987382d
6 changed files with 284 additions and 364 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Doc/library/email.headerregistry.rst
View file

@ -268,7 +268,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
also take a list of supplemental parameters, which have a common format. also take a list of supplemental parameters, which have a common format.
This class serves as a base for all the MIME headers that take parameters. This class serves as a base for all the MIME headers that take parameters.
.. attrbibute:: params .. attribute:: params
A dictionary mapping parameter names to parameter values. A dictionary mapping parameter names to parameter values.

548
Doc/library/os.rst
View file

@ -645,7 +645,7 @@ as internal buffering of data.
.. function:: closerange(fd_low, fd_high) .. function:: closerange(fd_low, fd_high)
Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive), Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
ignoring errors. Equivalent to:: ignoring errors. Equivalent to (but much faster than)::
for fd in range(fd_low, fd_high): for fd in range(fd_low, fd_high):
try: try:
@ -729,6 +729,7 @@ as internal buffering of data.
Availability: Unix, Windows. Availability: Unix, Windows.
.. function:: fstatvfs(fd) .. function:: fstatvfs(fd)
Return information about the filesystem containing the file associated with file Return information about the filesystem containing the file associated with file
@ -823,13 +824,8 @@ as internal buffering of data.
this module too (see :ref:`open-constants`). In particular, on Windows adding this module too (see :ref:`open-constants`). In particular, on Windows adding
:const:`O_BINARY` is needed to open files in binary mode. :const:`O_BINARY` is needed to open files in binary mode.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
@ -1171,6 +1167,49 @@ Querying the size of a terminal
Files and Directories Files and Directories
--------------------- ---------------------
On some Unix platforms, many of these functions support one or more of these
features:
.. _path_fd:
* For some functions, the *path* argument can be not only a string giving a path
name, but also a file descriptor. The function will then operate on the file
referred to by the descriptor. (For POSIX systems, this will use the ``f...``
versions of the function.)
You can check whether or not *path* can be specified as a file descriptor on
your platform using :data:`os.supports_fd`. If it is unavailable, using it
will raise a :exc:`NotImplementedError`.
If the function also supports *dir_fd* or *follow_symlinks* arguments, it is
an error to specify one of those when supplying *path* as a file descriptor.
.. _dir_fd:
* For functions with a *dir_fd* parameter: If *dir_fd* is not ``None``, it
should be a file descriptor referring to a directory, and the path to operate
on should be relative; path will then be relative to that directory. If the
path is absolute, *dir_fd* is ignored. (For POSIX systems, this will use the
``f...at`` versions of the function.)
You can check whether or not *dir_fd* is supported on your platform using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise a
:exc:`NotImplementedError`.
.. _follow_symlinks:
* For functions ith a *follow_symlinks* parameter: If *follow_symlinks* is
``False``, and the last element of the path to operate on is a symbolic link,
the function will operate on the symbolic link itself instead of the file the
link points to. (For POSIX systems, this will use the ``l...`` versions of
the function.)
You can check whether or not *follow_symlinks* is supported on your platform
using :data:`os.supports_follow_symlinks`. If it is unavailable, using it
will raise a :exc:`NotImplementedError`.
.. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True) .. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)
Use the real uid/gid to test for access to *path*. Note that most operations Use the real uid/gid to test for access to *path*. Note that most operations
@ -1182,13 +1221,8 @@ Files and Directories
:const:`False` if not. See the Unix man page :manpage:`access(2)` for more :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
information. information.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support specifying :ref:`paths relative to directory
directory, and *path* should be relative; path will then be relative to descriptors <dir_fd>` and :ref:`not following symlinks <follow_symlinks>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *effective_ids* is ``True``, :func:`access` will perform its access If *effective_ids* is ``True``, :func:`access` will perform its access
checks using the effective uid/gid instead of the real uid/gid. checks using the effective uid/gid instead of the real uid/gid.
@ -1196,13 +1230,6 @@ Files and Directories
or not it is available using :data:`os.supports_effective_ids`. If it is or not it is available using :data:`os.supports_effective_ids`. If it is
unavailable, using it will raise a :exc:`NotImplementedError`. unavailable, using it will raise a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`access` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
.. note:: .. note::
@ -1268,24 +1295,21 @@ Files and Directories
Change the current working directory to *path*. Change the current working directory to *path*.
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`working on a file descriptor <path_fd>`. The
This functionality may not be supported on your platform; you can check descriptor must refer to an opened directory, not an open file.
whether or not it is available using :data:`os.supports_fd`. If it is
unavailable, using it will raise a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying *path* as a file descriptor Added support for specifying *path* as a file descriptor
on some platforms, and the *dir_fd*, *effective_ids*, and on some platforms.
*follow_symlinks* parameters.
.. function:: fchdir(fd) .. function:: fchdir(fd)
Change the current working directory to the directory represented by the file Change the current working directory to the directory represented by the file
descriptor *fd*. The descriptor must refer to an opened directory, not an open descriptor *fd*. The descriptor must refer to an opened directory, not an
file. Equivalent to ``os.chdir(fd)``. open file. Equivalent to ``os.chdir(fd)``.
Availability: Unix. Availability: Unix.
@ -1322,12 +1346,7 @@ Files and Directories
* :data:`stat.SF_NOUNLINK` * :data:`stat.SF_NOUNLINK`
* :data:`stat.SF_SNAPSHOT` * :data:`stat.SF_SNAPSHOT`
If *follow_symlinks* is ``False``, and the last element of the path is a This function can support :ref:`not following symlinks <follow_symlinks>`.
symbolic link, :func:`follow_symlinks` will examine the symbolic link itself
instead of the file the link points to. *follow_symlinks* may not be
supported on your platform; you can check whether or not it is available
using :data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
Availability: Unix. Availability: Unix.
@ -1367,37 +1386,17 @@ Files and Directories
* :data:`stat.S_IWOTH` * :data:`stat.S_IWOTH`
* :data:`stat.S_IXOTH` * :data:`stat.S_IXOTH`
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>`,
This functionality may not be supported on your platform; you can check :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
whether or not it is available using :data:`os.supports_fd`. If it is following symlinks <follow_symlinks>`.
unavailable, using it will raise a :exc:`NotImplementedError`.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a
directory, and *path* should be relative; path will then be relative to
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`chmod` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
It is an error to use *dir_fd* or *follow_symlinks* when specifying
*path* as an open file descriptor.
Availability: Unix, Windows. Availability: Unix, Windows.
.. note:: .. note::
Although Windows supports :func:`chmod`, you can only set the file's read-only Although Windows supports :func:`chmod`, you can only set the file's
flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD`` read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
constants or a corresponding integer value). All other bits are constants or a corresponding integer value). All other bits are ignored.
ignored.
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying *path* as an open file descriptor, Added support for specifying *path* as an open file descriptor,
@ -1406,31 +1405,12 @@ Files and Directories
.. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True) .. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)
Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave Change the owner and group id of *path* to the numeric *uid* and *gid*. To
one of the ids unchanged, set it to -1. leave one of the ids unchanged, set it to -1.
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>`,
This functionality may not be supported on your platform; you can check :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
whether or not it is available using :data:`os.supports_fd`. If it is following symlinks <follow_symlinks>`.
unavailable, using it will raise a :exc:`NotImplementedError`.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a
directory, and *path* should be relative; path will then be relative to
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`chown` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
It is an error to use *dir_fd* or *follow_symlinks* when specifying
*path* as an open file descriptor.
See :func:`shutil.chown` for a higher-level function that accepts names in See :func:`shutil.chown` for a higher-level function that accepts names in
addition to numeric ids. addition to numeric ids.
@ -1442,29 +1422,11 @@ Files and Directories
and the *dir_fd* and *follow_symlinks* arguments. and the *dir_fd* and *follow_symlinks* arguments.
.. function:: getxattr(path, attribute, *, follow_symlinks=True)
Return the value of the extended filesystem attribute *attribute* for
*path*. *attribute* can be bytes or str. If it is str, it is encoded
with the filesystem encoding.
*path* may be specified as either a string or an open file descriptor.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`setxattr` will examine the symbolic link itself
instead of the file the link points to. It is an error to use
*follow_symlinks* when specifying *path* as an open file descriptor.
Availability: Linux
.. versionadded:: 3.3
.. function:: lchflags(path, flags) .. function:: lchflags(path, flags)
Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do
follow symbolic links. not follow symbolic links. Equivalent to ``os.chflags(path, flags,
Equivalent to ``os.chflags(path, flags, follow_symlinks=False)``. follow_symlinks=False)``.
Availability: Unix. Availability: Unix.
@ -1472,18 +1434,18 @@ Files and Directories
.. function:: lchmod(path, mode) .. function:: lchmod(path, mode)
Change the mode of *path* to the numeric *mode*. If path is a symlink, this Change the mode of *path* to the numeric *mode*. If path is a symlink, this
affects the symlink rather than the target. See the docs for :func:`chmod` affects the symlink rather than the target. See the docs for :func:`chmod`
for possible values of *mode*. for possible values of *mode*. Equivalent to ``os.chmod(path, mode,
Equivalent to ``os.chmod(path, mode, follow_symlinks=False)``. follow_symlinks=False)``.
Availability: Unix. Availability: Unix.
.. function:: lchown(path, uid, gid) .. function:: lchown(path, uid, gid)
Change the owner and group id of *path* to the numeric *uid* and *gid*. This Change the owner and group id of *path* to the numeric *uid* and *gid*. This
function will not follow symbolic links. function will not follow symbolic links. Equivalent to ``os.chown(path, uid,
Equivalent to ``os.chown(path, uid, gid, follow_symlinks=False)``. gid, follow_symlinks=False)``.
Availability: Unix. Availability: Unix.
@ -1492,21 +1454,17 @@ Files and Directories
Create a hard link pointing to *src* named *dst*. Create a hard link pointing to *src* named *dst*.
If either *src_dir_fd* or *dst_dir_fd* is not ``None``, it should be a If either *src_dir_fd* or *dst_dir_fd* is not ``None``, it should be a file
file descriptor referring to a directory, and the corresponding path descriptor referring to a directory, and the corresponding path (*src* or
(*src* or *dst*) should be relative; that path will then be relative to *dst*) should be relative; that path will then be relative to that directory.
that directory. (If *src* is absolute, *src_dir_fd* is ignored; the same (If *src* is absolute, *src_dir_fd* is ignored; the same goes for *dst* and
goes for *dst* and *dst_dir_fd*.) *dst_dir_fd*.) *src_dir_fd* and *dst_dir_fd* may not be supported on your
*src_dir_fd* and *dst_dir_fd* may not be supported on your platform; platform; you can check whether or not they are available using
you can check whether or not they are available using :data:`os.supports_dir_fd`. :data:`os.supports_dir_fd`. If they are unavailable, using either will raise
If they are unavailable, using either will raise a :exc:`NotImplementedError`. a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of *src* is a This function can also support :ref:`not following symlinks
symbolic link, :func:`link` will use the symbolic link itself instead <follow_symlinks>`.
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
@ -1520,16 +1478,15 @@ Files and Directories
.. function:: listdir(path='.') .. function:: listdir(path='.')
Return a list containing the names of the entries in the directory given by Return a list containing the names of the entries in the directory given by
*path* (default: ``'.'``). The list is in arbitrary order. It does not include the special *path* (default: ``'.'``). The list is in arbitrary order. It does not
entries ``'.'`` and ``'..'`` even if they are present in the directory. include the special entries ``'.'`` and ``'..'`` even if they are present in
the directory.
This function can be called with a bytes or string argument, and returns This function can be called with a bytes or string argument, and returns
filenames of the same datatype. filenames of the same datatype.
On some platforms, *path* may also be specified as an open file descriptor. This function can also support :ref:`specifying an open file descriptor
This functionality may not be supported on your platform; you can check <path_fd>` (referring to a directory).
whether or not it is available using :data:`os.supports_fd`. If it is
unavailable, using it will raise a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
@ -1539,25 +1496,6 @@ Files and Directories
.. versionadded:: 3.3 .. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*. Added support for specifying an open file descriptor for *path*.
.. function:: listxattr(path=None, *, follow_symlinks=True)
Return a list of the extended filesystem attributes on *path*.
The attributes in the list are represented as strings decoded
with the filesystem encoding.
*path* may be specified as either ``None``, a string, or an open file
descriptor. If *path* is ``None``, :func:`listxattr` will examine the
current directory.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`listxattr` will examine the symbolic link itself
instead of the file the link points to. It is an error to use
*follow_symlinks* when specifying *path* as an open file descriptor.
Availability: Linux
.. versionadded:: 3.3
.. function:: lstat(path, *, dir_fd=None) .. function:: lstat(path, *, dir_fd=None)
@ -1566,13 +1504,8 @@ Files and Directories
platforms that do not support symbolic links, this is an alias for platforms that do not support symbolic links, this is an alias for
:func:`~os.stat`. (Equivalent to ``os.stat(path, follow_symlinks=False)``.) :func:`~os.stat`. (Equivalent to ``os.stat(path, follow_symlinks=False)``.)
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
.. versionchanged:: 3.2 .. versionchanged:: 3.2
Added support for Windows 6.0 (Vista) symbolic links. Added support for Windows 6.0 (Vista) symbolic links.
@ -1586,13 +1519,8 @@ Files and Directories
Create a FIFO (a named pipe) named *path* with numeric mode *mode*. Create a FIFO (a named pipe) named *path* with numeric mode *mode*.
The current umask value is first masked out from the mode. The current umask value is first masked out from the mode.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
FIFOs are pipes that can be accessed like regular files. FIFOs exist until they FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
@ -1616,13 +1544,8 @@ Files and Directories
*device* defines the newly created device special file (probably using *device* defines the newly created device special file (probably using
:func:`os.makedev`), otherwise it is ignored. :func:`os.makedev`), otherwise it is ignored.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
.. versionadded:: 3.3 .. versionadded:: 3.3
The *dir_fd* argument. The *dir_fd* argument.
@ -1649,17 +1572,12 @@ Files and Directories
Create a directory named *path* with numeric mode *mode*. Create a directory named *path* with numeric mode *mode*.
On some systems, *mode* is ignored. Where it is used, the current On some systems, *mode* is ignored. Where it is used, the current umask
umask value is first masked out. If the directory already value is first masked out. If the directory already exists, :exc:`OSError`
exists, :exc:`OSError` is raised. is raised.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
It is also possible to create temporary directories; see the It is also possible to create temporary directories; see the
:mod:`tempfile` module's :func:`tempfile.mkdtemp` function. :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
@ -1725,21 +1643,16 @@ Files and Directories
.. function:: readlink(path, *, dir_fd=None) .. function:: readlink(path, *, dir_fd=None)
Return a string representing the path to which the symbolic link points. The Return a string representing the path to which the symbolic link points. The
result may be either an absolute or relative pathname; if it is relative, it may result may be either an absolute or relative pathname; if it is relative, it
be converted to an absolute pathname using ``os.path.join(os.path.dirname(path), may be converted to an absolute pathname using
result)``. ``os.path.join(os.path.dirname(path), result)``.
If the *path* is a string object, the result will also be a string object, If the *path* is a string object, the result will also be a string object,
and the call may raise an UnicodeDecodeError. If the *path* is a bytes and the call may raise an UnicodeDecodeError. If the *path* is a bytes
object, the result will be a bytes object. object, the result will be a bytes object.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can also support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
Availability: Unix, Windows Availability: Unix, Windows
@ -1752,16 +1665,11 @@ Files and Directories
.. function:: remove(path, *, dir_fd=None) .. function:: remove(path, *, dir_fd=None)
Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is
is raised. Use :func:`rmdir` to remove directories. raised. Use :func:`rmdir` to remove directories.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
On Windows, attempting to remove a file that is in use causes an exception to On Windows, attempting to remove a file that is in use causes an exception to
be raised; on Unix, the directory entry is removed but the storage allocated be raised; on Unix, the directory entry is removed but the storage allocated
@ -1789,25 +1697,6 @@ Files and Directories
successfully removed. successfully removed.
.. function:: removexattr(path, attribute, *, follow_symlinks=True)
Removes the extended filesystem attribute *attribute* from *path*.
*attribute* should be bytes or str. If it is a string, it is encoded
with the filesystem encoding.
*path* may be specified as either a string or an open file descriptor.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`removexattr` will remove the attribute from the
symbolic link itself instead of the file the link points to. It is an
error to use *follow_symlinks* when specifying *path* as an open file
descriptor.
Availability: Linux
.. versionadded:: 3.3
.. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None) .. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
Rename the file or directory *src* to *dst*. If *dst* is a directory, Rename the file or directory *src* to *dst*. If *dst* is a directory,
@ -1876,13 +1765,8 @@ Files and Directories
empty, otherwise, :exc:`OSError` is raised. In order to remove whole empty, otherwise, :exc:`OSError` is raised. In order to remove whole
directory trees, :func:`shutil.rmtree` can be used. directory trees, :func:`shutil.rmtree` can be used.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
Availability: Unix, Windows. Availability: Unix, Windows.
@ -1890,51 +1774,6 @@ Files and Directories
The *dir_fd* parameter. The *dir_fd* parameter.
.. data:: XATTR_SIZE_MAX
The maximum size the value of an extended attribute can be. Currently, this
is 64 kilobytes on Linux.
.. data:: XATTR_CREATE
This is a possible value for the flags argument in :func:`setxattr`. It
indicates the operation must create an attribute.
.. data:: XATTR_REPLACE
This is a possible value for the flags argument in :func:`setxattr`. It
indicates the operation must replace an existing attribute.
.. function:: setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)
Set the extended filesystem attribute *attribute* on *path* to *value*.
*attribute* must be a bytes or str with no embedded NULs. If it is a str,
it is encoded with the filesystem encoding. *flags* may be
:data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is
given and the attribute does not exist, ``EEXISTS`` will be raised.
If :data:`XATTR_CREATE` is given and the attribute already exists, the
attribute will not be created and ``ENODATA`` will be raised.
*path* may be specified as either a string or an open file descriptor.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`setxattr` will examine the symbolic link itself
instead of the file the link points to. It is an error to use
*follow_symlinks* when specifying *path* as an open file descriptor.
Availability: Linux
.. note::
A bug in Linux kernel versions less than 2.6.39 caused the flags argument
to be ignored on some filesystems.
.. versionadded:: 3.3
.. function:: stat(path, *, dir_fd=None, follow_symlinks=True) .. function:: stat(path, *, dir_fd=None, follow_symlinks=True)
Perform the equivalent of a :c:func:`stat` system call on the given path. Perform the equivalent of a :c:func:`stat` system call on the given path.
@ -2002,30 +1841,17 @@ Files and Directories
If you need the exact timestamps you should always use If you need the exact timestamps you should always use
:attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`. :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`.
For backward compatibility, the return value of :func:`~os.stat` is also accessible For backward compatibility, the return value of :func:`~os.stat` is also
as a tuple of at least 10 integers giving the most important (and portable) accessible as a tuple of at least 10 integers giving the most important (and
members of the :c:type:`stat` structure, in the order :attr:`st_mode`, portable) members of the :c:type:`stat` structure, in the order
:attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`, :attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`,
:attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`, :attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`,
:attr:`st_ctime`. More items may be added at the end by some implementations. :attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by
some implementations.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`specifying an open file descriptor
directory, and *path* should be relative; path will then be relative to <path_fd>`, :ref:`specifying a file descriptor <path_fd>` and :ref:`not
that directory. (If *path* is absolute, *dir_fd* is ignored.) following symlinks <follow_symlinks>`.
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`stat` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
It is an error to use *dir_fd* or *follow_symlinks* when specifying
*path* as an open file descriptor.
.. index:: module: stat .. index:: module: stat
@ -2094,10 +1920,7 @@ Files and Directories
read-only, and if :const:`ST_NOSUID` is set, the semantics of read-only, and if :const:`ST_NOSUID` is set, the semantics of
setuid/setgid bits are disabled or not supported. setuid/setgid bits are disabled or not supported.
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>`.
This functionality may not be supported on your platform; you can check
whether or not it is available using :data:`os.supports_fd`. If it is
unavailable, using it will raise a :exc:`NotImplementedError`.
.. versionchanged:: 3.2 .. versionchanged:: 3.2
The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added. The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
@ -2132,17 +1955,17 @@ Files and Directories
.. data:: supports_effective_ids .. data:: supports_effective_ids
An object implementing collections.Set indicating which functions in the An object implementing collections.Set indicating which functions in the
:mod:`os` permit use of the *effective_id* parameter for :func:`os.access`. :mod:`os` permit use of the *effective_ids* parameter for :func:`os.access`.
If the local platform supports it, the collection will contain If the local platform supports it, the collection will contain
:func:`os.access`, otherwise it will be empty. :func:`os.access`, otherwise it will be empty.
To check whether you can use the *effective_id* parameter for To check whether you can use the *effective_ids* parameter for
:func:`os.access`, use the ``in`` operator on ``supports_dir_fd``, like so:: :func:`os.access`, use the ``in`` operator on ``supports_dir_fd``, like so::
os.access in os.supports_effective_ids os.access in os.supports_effective_ids
Currently *effective_id* only works on UNIX platforms; Currently *effective_ids* only works on Unix platforms; it does not work on
it does not work on Windows. Windows.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -2196,13 +2019,8 @@ Files and Directories
Symbolic link support was introduced in Windows 6.0 (Vista). :func:`symlink` Symbolic link support was introduced in Windows 6.0 (Vista). :func:`symlink`
will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0. will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a This function can support :ref:`paths relative to directory descriptors
directory, and *path* should be relative; path will then be relative to <dir_fd>`.
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
.. note:: .. note::
@ -2247,7 +2065,7 @@ Files and Directories
.. function:: unlink(path, *, dir_fd=None) .. function:: unlink(path, *, dir_fd=None)
Remove (delete) the file *path*. This function is identical to Remove (delete) the file *path*. This function is identical to
:func:`remove`; the :func:`unlink` name is its traditional Unix :func:`remove`; the ``unlink`` name is its traditional Unix
name. Please see the documentation for :func:`remove` for name. Please see the documentation for :func:`remove` for
further information. further information.
@ -2287,28 +2105,9 @@ Files and Directories
use the *st_atime_ns* and *st_mtime_ns* fields from the :func:`os.stat` use the *st_atime_ns* and *st_mtime_ns* fields from the :func:`os.stat`
result object with the *ns* parameter to `utime`. result object with the *ns* parameter to `utime`.
On some platforms, *path* may also be specified as an open file descriptor. This function can support :ref:`specifying a file descriptor <path_fd>`,
This functionality may not be supported on your platform; you can check :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
whether or not it is available using :data:`os.supports_fd`. If it is following symlinks <follow_symlinks>`.
unavailable, using it will raise a :exc:`NotImplementedError`.
If *dir_fd* is not ``None``, it should be a file descriptor referring to a
directory, and *path* should be relative; path will then be relative to
that directory. (If *path* is absolute, *dir_fd* is ignored.)
*dir_fd* may not be supported on your platform;
you can check whether or not it is available using
:data:`os.supports_dir_fd`. If it is unavailable, using it will raise
a :exc:`NotImplementedError`.
If *follow_symlinks* is ``False``, and the last element of the path is a
symbolic link, :func:`utime` will examine the symbolic link itself instead
of the file the link points to. *follow_symlinks* may not be supported
on your platform; you can check whether or not it is available using
:data:`os.supports_follow_symlinks`. If it is unavailable,
using it will raise a :exc:`NotImplementedError`.
It is an error to use *dir_fd* or *follow_symlinks* when specifying
*path* as an open file descriptor.
Availability: Unix, Windows. Availability: Unix, Windows.
@ -2362,9 +2161,9 @@ Files and Directories
.. note:: .. note::
Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a Be aware that setting *followlinks* to ``True`` can lead to infinite
link points to a parent directory of itself. :func:`walk` does not keep track of recursion if a link points to a parent directory of itself. :func:`walk`
the directories it visited already. does not keep track of the directories it visited already.
.. note:: .. note::
@ -2451,6 +2250,81 @@ Files and Directories
.. versionadded:: 3.3 .. versionadded:: 3.3
Linux extended attributes
~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 3.3
These functions are all available on Linux only.
.. function:: getxattr(path, attribute, *, follow_symlinks=True)
Return the value of the extended filesystem attribute *attribute* for
*path*. *attribute* can be bytes or str. If it is str, it is encoded
with the filesystem encoding.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
.. function:: listxattr(path=None, *, follow_symlinks=True)
Return a list of the extended filesystem attributes on *path*. The
attributes in the list are represented as strings decoded with the filesystem
encoding. If *path* is ``None``, :func:`listxattr` will examine the current
directory.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
.. function:: removexattr(path, attribute, *, follow_symlinks=True)
Removes the extended filesystem attribute *attribute* from *path*.
*attribute* should be bytes or str. If it is a string, it is encoded
with the filesystem encoding.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
.. function:: setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)
Set the extended filesystem attribute *attribute* on *path* to *value*.
*attribute* must be a bytes or str with no embedded NULs. If it is a str,
it is encoded with the filesystem encoding. *flags* may be
:data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is
given and the attribute does not exist, ``EEXISTS`` will be raised.
If :data:`XATTR_CREATE` is given and the attribute already exists, the
attribute will not be created and ``ENODATA`` will be raised.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
.. note::
A bug in Linux kernel versions less than 2.6.39 caused the flags argument
to be ignored on some filesystems.
.. data:: XATTR_SIZE_MAX
The maximum size the value of an extended attribute can be. Currently, this
is 64 kilobytes on Linux.
.. data:: XATTR_CREATE
This is a possible value for the flags argument in :func:`setxattr`. It
indicates the operation must create an attribute.
.. data:: XATTR_REPLACE
This is a possible value for the flags argument in :func:`setxattr`. It
indicates the operation must replace an existing attribute.
.. _os-process: .. _os-process:
Process Management Process Management

6
Lib/test/test_random.py
View file

@ -34,8 +34,12 @@ class TestBasicOps(unittest.TestCase):
self.assertEqual(randseq, self.randomlist(N)) self.assertEqual(randseq, self.randomlist(N))
def test_seedargs(self): def test_seedargs(self):
# Seed value with a negative hash.
class MySeed(object):
def __hash__(self):
return -1729
for arg in [None, 0, 0, 1, 1, -1, -1, 10**20, -(10**20), for arg in [None, 0, 0, 1, 1, -1, -1, 10**20, -(10**20),
3.14, 1+2j, 'a', tuple('abc')]: 3.14, 1+2j, 'a', tuple('abc'), MySeed()]:
self.gen.seed(arg) self.gen.seed(arg)
for arg in [list(range(3)), dict(one=1)]: for arg in [list(range(3)), dict(one=1)]:
self.assertRaises(TypeError, self.gen.seed, arg) self.assertRaises(TypeError, self.gen.seed, arg)

4
Misc/NEWS
View file

@ -55,6 +55,10 @@ Core and Builtins
Library Library
------- -------
- Speed up _decimal by another 10-15% by caching the thread local context
that was last accessed. In the pi benchmark (64-bit platform, prec=9),
_decimal is now only 1.5x slower than float.
- Remove the packaging module, which is not ready for prime time. - Remove the packaging module, which is not ready for prime time.
- Issue #15154: Add "dir_fd" parameter to os.rmdir, remove "rmdir" - Issue #15154: Add "dir_fd" parameter to os.rmdir, remove "rmdir"

79
Modules/_decimal/_decimal.c
View file

@ -76,6 +76,9 @@ typedef struct {
PyObject *traps; PyObject *traps;
PyObject *flags; PyObject *flags;
int capitals; int capitals;
#ifndef WITHOUT_THREADS
PyThreadState *tstate;
#endif
} PyDecContextObject; } PyDecContextObject;
typedef struct { typedef struct {
@ -123,6 +126,8 @@ static PyObject *module_context = NULL;
#else #else
/* Key for thread state dictionary */ /* Key for thread state dictionary */
static PyObject *tls_context_key = NULL; static PyObject *tls_context_key = NULL;
/* Invariant: NULL or the most recently accessed thread local context */
static PyDecContextObject *cached_context = NULL;
#endif #endif
/* Template for creating new thread contexts, calling Context() without /* Template for creating new thread contexts, calling Context() without
@ -1182,6 +1187,9 @@ context_new(PyTypeObject *type, PyObject *args UNUSED, PyObject *kwds UNUSED)
SdFlagAddr(self->flags) = &ctx->status; SdFlagAddr(self->flags) = &ctx->status;
CtxCaps(self) = 1; CtxCaps(self) = 1;
#ifndef WITHOUT_THREADS
self->tstate = NULL;
#endif
return (PyObject *)self; return (PyObject *)self;
} }
@ -1189,6 +1197,11 @@ context_new(PyTypeObject *type, PyObject *args UNUSED, PyObject *kwds UNUSED)
static void static void
context_dealloc(PyDecContextObject *self) context_dealloc(PyDecContextObject *self)
{ {
#ifndef WITHOUT_THREADS
if (self == cached_context) {
cached_context = NULL;
}
#endif
Py_XDECREF(self->traps); Py_XDECREF(self->traps);
Py_XDECREF(self->flags); Py_XDECREF(self->flags);
Py_TYPE(self)->tp_free(self); Py_TYPE(self)->tp_free(self);
@ -1555,18 +1568,19 @@ PyDec_SetCurrentContext(PyObject *self UNUSED, PyObject *v)
} }
#else #else
/* /*
* Thread local storage currently has a speed penalty of about 16%. * Thread local storage currently has a speed penalty of about 4%.
* All functions that map Python's arithmetic operators to mpdecimal * All functions that map Python's arithmetic operators to mpdecimal
* functions have to look up the current context for each and every * functions have to look up the current context for each and every
* operation. * operation.
*/ */
/* Return borrowed reference to thread local context. */ /* Get the context from the thread state dictionary. */
static PyObject * static PyObject *
current_context(void) current_context_from_dict(void)
{ {
PyObject *dict = NULL; PyObject *dict;
PyObject *tl_context = NULL; PyObject *tl_context;
PyThreadState *tstate;
dict = PyThreadState_GetDict(); dict = PyThreadState_GetDict();
if (dict == NULL) { if (dict == NULL) {
@ -1577,32 +1591,54 @@ current_context(void)
tl_context = PyDict_GetItemWithError(dict, tls_context_key); tl_context = PyDict_GetItemWithError(dict, tls_context_key);
if (tl_context != NULL) { if (tl_context != NULL) {
/* We already have a thread local context and /* We already have a thread local context. */
* return a borrowed reference. */
CONTEXT_CHECK(tl_context); CONTEXT_CHECK(tl_context);
return tl_context;
}
if (PyErr_Occurred()) {
return NULL;
} }
else {
if (PyErr_Occurred()) {
return NULL;
}
/* Otherwise, set up a new thread local context. */ /* Set up a new thread local context. */
tl_context = context_copy(default_context_template); tl_context = context_copy(default_context_template);
if (tl_context == NULL) { if (tl_context == NULL) {
return NULL; return NULL;
} }
CTX(tl_context)->status = 0; CTX(tl_context)->status = 0;
if (PyDict_SetItem(dict, tls_context_key, tl_context) < 0) { if (PyDict_SetItem(dict, tls_context_key, tl_context) < 0) {
Py_DECREF(tl_context);
return NULL;
}
Py_DECREF(tl_context); Py_DECREF(tl_context);
return NULL;
} }
Py_DECREF(tl_context);
/* refcount is 1 */ /* Cache the context of the current thread, assuming that it
* will be accessed several times before a thread switch. */
tstate = PyThreadState_GET();
if (tstate) {
cached_context = (PyDecContextObject *)tl_context;
cached_context->tstate = tstate;
}
/* Borrowed reference with refcount==1 */
return tl_context; return tl_context;
} }
/* Return borrowed reference to thread local context. */
static PyObject *
current_context(void)
{
PyThreadState *tstate;
tstate = PyThreadState_GET();
if (cached_context && cached_context->tstate == tstate) {
return (PyObject *)cached_context;
}
return current_context_from_dict();
}
/* ctxobj := borrowed reference to the current context */ /* ctxobj := borrowed reference to the current context */
#define CURRENT_CONTEXT(ctxobj) \ #define CURRENT_CONTEXT(ctxobj) \
ctxobj = current_context(); \ ctxobj = current_context(); \
@ -1664,6 +1700,7 @@ PyDec_SetCurrentContext(PyObject *self UNUSED, PyObject *v)
Py_INCREF(v); Py_INCREF(v);
} }
cached_context = NULL;
if (PyDict_SetItem(dict, tls_context_key, v) < 0) { if (PyDict_SetItem(dict, tls_context_key, v) < 0) {
Py_DECREF(v); Py_DECREF(v);
return NULL; return NULL;

9
Modules/_randommodule.c
View file

@ -228,16 +228,17 @@ random_seed(RandomObject *self, PyObject *args)
Py_INCREF(Py_None); Py_INCREF(Py_None);
return Py_None; return Py_None;
} }
/* If the arg is an int or long, use its absolute value; else use /* This algorithm relies on the number being unsigned.
* the absolute value of its hash code. * So: if the arg is a PyLong, use its absolute value.
* Otherwise use its hash value, cast to unsigned.
*/ */
if (PyLong_Check(arg)) if (PyLong_Check(arg))
n = PyNumber_Absolute(arg); n = PyNumber_Absolute(arg);
else { else {
Py_ssize_t hash = PyObject_Hash(arg); Py_hash_t hash = PyObject_Hash(arg);
if (hash == -1) if (hash == -1)
goto Done; goto Done;
n = PyLong_FromSsize_t(hash); n = PyLong_FromSize_t((size_t)hash);
} }
if (n == NULL) if (n == NULL)
goto Done; goto Done;