diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/os.rst | 53 | ||||
| -rw-r--r-- | Doc/library/shutil.rst | 4 | ||||
| -rw-r--r-- | Doc/library/stat.rst | 10 | ||||
| -rw-r--r-- | Doc/whatsnew/3.8.rst | 21 |
4 files changed, 86 insertions, 2 deletions
diff --git a/Doc/library/os.rst b/Doc/library/os.rst index c74d687..6cbfb74 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1858,6 +1858,12 @@ features: .. versionchanged:: 3.6 Accepts a :term:`path-like object` for *src* and *dst*. + .. versionchanged:: 3.8 + On Windows, now opens reparse points that represent another path + (name surrogates), including symbolic links and directory junctions. + Other kinds of reparse points are resolved by the operating system as + for :func:`~os.stat`. + .. function:: mkdir(path, mode=0o777, *, dir_fd=None) @@ -2039,6 +2045,10 @@ features: This function can also support :ref:`paths relative to directory descriptors <dir_fd>`. + When trying to resolve a path that may contain links, use + :func:`~os.path.realpath` to properly handle recursion and platform + differences. + .. availability:: Unix, Windows. .. versionchanged:: 3.2 @@ -2053,6 +2063,11 @@ features: .. versionchanged:: 3.8 Accepts a :term:`path-like object` and a bytes object on Windows. + .. versionchanged:: 3.8 + Added support for directory junctions, and changed to return the + substitution path (which typically includes ``\\?\`` prefix) rather + than the optional "print name" field that was previously returned. + .. function:: remove(path, *, dir_fd=None) Remove (delete) the file *path*. If *path* is a directory, an @@ -2366,7 +2381,8 @@ features: On Unix, this method always requires a system call. On Windows, it only requires a system call if *follow_symlinks* is ``True`` and the - entry is a symbolic link. + entry is a reparse point (for example, a symbolic link or directory + junction). On Windows, the ``st_ino``, ``st_dev`` and ``st_nlink`` attributes of the :class:`stat_result` are always set to zero. Call :func:`os.stat` to @@ -2403,6 +2419,17 @@ features: This function can support :ref:`specifying a file descriptor <path_fd>` and :ref:`not following symlinks <follow_symlinks>`. + On Windows, passing ``follow_symlinks=False`` will disable following all + name-surrogate reparse points, which includes symlinks and directory + junctions. Other types of reparse points that do not resemble links or that + the operating system is unable to follow will be opened directly. When + following a chain of multiple links, this may result in the original link + being returned instead of the non-link that prevented full traversal. To + obtain stat results for the final path in this case, use the + :func:`os.path.realpath` function to resolve the path name as far as + possible and call :func:`lstat` on the result. This does not apply to + dangling symlinks or junction points, which will raise the usual exceptions. + .. index:: module: stat Example:: @@ -2427,6 +2454,14 @@ features: .. versionchanged:: 3.6 Accepts a :term:`path-like object`. + .. versionchanged:: 3.8 + On Windows, all reparse points that can be resolved by the operating + system are now followed, and passing ``follow_symlinks=False`` + disables following all name surrogate reparse points. If the operating + system reaches a reparse point that it is not able to follow, *stat* now + returns the information for the original path as if + ``follow_symlinks=False`` had been specified instead of raising an error. + .. class:: stat_result @@ -2578,7 +2613,7 @@ features: File type. - On Windows systems, the following attribute is also available: + On Windows systems, the following attributes are also available: .. attribute:: st_file_attributes @@ -2587,6 +2622,12 @@ features: :c:func:`GetFileInformationByHandle`. See the ``FILE_ATTRIBUTE_*`` constants in the :mod:`stat` module. + .. attribute:: st_reparse_tag + + When :attr:`st_file_attributes` has the ``FILE_ATTRIBUTE_REPARSE_POINT`` + set, this field contains the tag identifying the type of reparse point. + See the ``IO_REPARSE_TAG_*`` constants in the :mod:`stat` module. + The standard module :mod:`stat` defines functions and constants that are useful for extracting information from a :c:type:`stat` structure. (On Windows, some items are filled with dummy values.) @@ -2614,6 +2655,14 @@ features: .. versionadded:: 3.7 Added the :attr:`st_fstype` member to Solaris/derivatives. + .. versionadded:: 3.8 + Added the :attr:`st_reparse_tag` member on Windows. + + .. versionchanged:: 3.8 + On Windows, the :attr:`st_mode` member now identifies special + files as :const:`S_IFCHR`, :const:`S_IFIFO` or :const:`S_IFBLK` + as appropriate. + .. function:: statvfs(path) Perform a :c:func:`statvfs` system call on the given path. The return value is diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index eaeee8d..a51e068 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -304,6 +304,10 @@ Directory and files operations Added a symlink attack resistant version that is used automatically if platform supports fd-based functions. + .. versionchanged:: 3.8 + On Windows, will no longer delete the contents of a directory junction + before removing the junction. + .. attribute:: rmtree.avoids_symlink_attacks Indicates whether the current platform and implementation provides a diff --git a/Doc/library/stat.rst b/Doc/library/stat.rst index c8f6904..f48a0a9 100644 --- a/Doc/library/stat.rst +++ b/Doc/library/stat.rst @@ -425,3 +425,13 @@ for more detail on the meaning of these constants. FILE_ATTRIBUTE_VIRTUAL .. versionadded:: 3.5 + +On Windows, the following constants are available for comparing against the +``st_reparse_tag`` member returned by :func:`os.lstat`. These are well-known +constants, but are not an exhaustive list. + +.. data:: IO_REPARSE_TAG_SYMLINK + IO_REPARSE_TAG_MOUNT_POINT + IO_REPARSE_TAG_APPEXECLINK + + .. versionadded:: 3.8 diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 93758e9..0294e9a 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -808,6 +808,21 @@ A new :func:`os.memfd_create` function was added to wrap the ``memfd_create()`` syscall. (Contributed by Zackery Spytz and Christian Heimes in :issue:`26836`.) +On Windows, much of the manual logic for handling reparse points (including +symlinks and directory junctions) has been delegated to the operating system. +Specifically, :func:`os.stat` will now traverse anything supported by the +operating system, while :func:`os.lstat` will only open reparse points that +identify as "name surrogates" while others are opened as for :func:`os.stat`. +In all cases, :attr:`stat_result.st_mode` will only have ``S_IFLNK`` set for +symbolic links and not other kinds of reparse points. To identify other kinds +of reparse point, check the new :attr:`stat_result.st_reparse_tag` attribute. + +On Windows, :func:`os.readlink` is now able to read directory junctions. Note +that :func:`~os.path.islink` will return ``False`` for directory junctions, +and so code that checks ``islink`` first will continue to treat junctions as +directories, while code that handles errors from :func:`os.readlink` may now +treat junctions as links. + os.path ------- @@ -824,6 +839,9 @@ characters or bytes unrepresentable at the OS level. environment variable and does not use :envvar:`HOME`, which is not normally set for regular user accounts. +:func:`~os.path.isdir` on Windows no longer returns true for a link to a +non-existent directory. + :func:`~os.path.realpath` on Windows now resolves reparse points, including symlinks and directory junctions. @@ -912,6 +930,9 @@ format for new archives to improve portability and standards conformance, inherited from the corresponding change to the :mod:`tarfile` module. (Contributed by C.A.M. Gerlach in :issue:`30661`.) +:func:`shutil.rmtree` on Windows now removes directory junctions without +recursively removing their contents first. + ssl --- |