gh-99547: Add isjunction methods for checking if a path is a junction (GH-99548)

4 files changed, 42 insertions, 2 deletions

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 6d52a03..50e0896 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -266,6 +266,15 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
+.. function:: isjunction(path)
+
+   Return ``True`` if *path* refers to an :func:`existing <lexists>` directory
+   entry that is a junction.  Always return ``False`` if junctions are not
+   supported on the current platform.
+
+   .. versionadded:: 3.12
+
+
 .. function:: islink(path)
 
    Return ``True`` if *path* refers to an :func:`existing <exists>` directory
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 3387d08..775aa32 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2738,6 +2738,17 @@ features:
       This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
       but :exc:`FileNotFoundError` is caught and not raised.
 
+   .. method:: is_junction()
+
+      Return ``True`` if this entry is a junction (even if broken);
+      return ``False`` if the entry points to a regular directory, any kind
+      of file, a symlink, or if it doesn't exist anymore.
+
+      The result is cached on the ``os.DirEntry`` object. Call
+      :func:`os.path.isjunction` to fetch up-to-date information.
+
+      .. versionadded:: 3.12
+
    .. method:: stat(*, follow_symlinks=True)
 
       Return a :class:`stat_result` object for this entry. This method
@@ -2760,8 +2771,8 @@ features:
    Note that there is a nice correspondence between several attributes
    and methods of ``os.DirEntry`` and of :class:`pathlib.Path`.  In
    particular, the ``name`` attribute has the same
-   meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()``
-   and ``stat()`` methods.
+   meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()``,
+   ``is_junction()``, and ``stat()`` methods.
 
    .. versionadded:: 3.5
 
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 944963e..6537637 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -891,6 +891,14 @@ call fails (for example because the path doesn't exist).
    other errors (such as permission errors) are propagated.
 
 
+.. method:: Path.is_junction()
+
+   Return ``True`` if the path points to a junction, and ``False`` for any other
+   type of file. Currently only Windows supports junctions.
+
+   .. versionadded:: 3.12
+
+
 .. method:: Path.is_mount()
 
    Return ``True`` if the path is a :dfn:`mount point`: a point in a
diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 8e9a4f0..a9b69c2 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -234,6 +234,10 @@ pathlib
   more consistent with :func:`os.path.relpath`.
   (Contributed by Domenico Ragusa in :issue:`40358`.)
 
+* Add :meth:`pathlib.Path.is_junction` as a proxy to :func:`os.path.isjunction`.
+  (Contributed by Charles Machalow in :gh:`99547`.)
+
+
 dis
 ---
 
@@ -252,6 +256,14 @@ os
   for a process with :func:`os.pidfd_open` in non-blocking mode.
   (Contributed by Kumar Aditya in :gh:`93312`.)
 
+* Add :func:`os.path.isjunction` to check if a given path is a junction.
+  (Contributed by Charles Machalow in :gh:`99547`.)
+
+* :class:`os.DirEntry` now includes an :meth:`os.DirEntry.is_junction`
+  method to check if the entry is a junction.
+  (Contributed by Charles Machalow in :gh:`99547`.)
+
+
 shutil
 ------