From 2cf36e245899a585fe2867a8063b6dbe77ba511a Mon Sep 17 00:00:00 2001 From: barneygale Date: Sat, 13 Jan 2024 18:58:55 +0000 Subject: [PATCH 1/3] GH-105900: Fix `pathlib.Path.symlink_to(target_is_directory=...)` docs Clarify that *target_is_directory* only matters if the target doesn't exist. --- Doc/library/pathlib.rst | 8 +++++--- .../2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst | 2 ++ 2 files changed, 7 insertions(+), 3 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 60791725c2323d..46382790827bba 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1510,9 +1510,11 @@ call fails (for example because the path doesn't exist). .. method:: Path.symlink_to(target, target_is_directory=False) - Make this path a symbolic link to *target*. Under Windows, - *target_is_directory* must be true (default ``False``) if the link's target - is a directory. Under POSIX, *target_is_directory*'s value is ignored. + Make this path a symbolic link to *target*. Under Windows, if the target + is present, the type of the symlink will be created to match. Otherwise, + the symlink will be created as a directory if *target_is_directory* is + ``True`` or a file symlink (the default) otherwise. Under POSIX, + *target_is_directory*'s value is ignored. :: diff --git a/Misc/NEWS.d/next/Documentation/2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst b/Misc/NEWS.d/next/Documentation/2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst new file mode 100644 index 00000000000000..04a6824af9bd89 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst @@ -0,0 +1,2 @@ +Fix misleading documentation for *target_is_directory* parameter of +:meth:`pathlib.Path.symlink_to`. From 9a8d6b7e02afb2fa3ebaf6189c8a5491778c7880 Mon Sep 17 00:00:00 2001 From: barneygale Date: Tue, 16 Jan 2024 01:06:36 +0000 Subject: [PATCH 2/3] Delete news entry. --- .../2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst | 2 -- 1 file changed, 2 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst diff --git a/Misc/NEWS.d/next/Documentation/2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst b/Misc/NEWS.d/next/Documentation/2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst deleted file mode 100644 index 04a6824af9bd89..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2024-01-13-18-58-04.gh-issue-105900.go-Qkk.rst +++ /dev/null @@ -1,2 +0,0 @@ -Fix misleading documentation for *target_is_directory* parameter of -:meth:`pathlib.Path.symlink_to`. From 4b092d8eb44fbc1ad9e302717b1dbeea55336992 Mon Sep 17 00:00:00 2001 From: barneygale Date: Tue, 23 Jan 2024 04:37:55 +0000 Subject: [PATCH 3/3] Use wording from `os.symlink` docs --- Doc/library/pathlib.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 46382790827bba..c2a0bcf0f7a419 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1510,11 +1510,13 @@ call fails (for example because the path doesn't exist). .. method:: Path.symlink_to(target, target_is_directory=False) - Make this path a symbolic link to *target*. Under Windows, if the target - is present, the type of the symlink will be created to match. Otherwise, - the symlink will be created as a directory if *target_is_directory* is - ``True`` or a file symlink (the default) otherwise. Under POSIX, - *target_is_directory*'s value is ignored. + Make this path a symbolic link pointing to *target*. + + On Windows, a symlink represents either a file or a directory, and does not + morph to the target dynamically. If the target is present, the type of the + symlink will be created to match. Otherwise, the symlink will be created + as a directory if *target_is_directory* is ``True`` or a file symlink (the + default) otherwise. On non-Windows platforms, *target_is_directory* is ignored. ::