Implement #1578269. Patch by Jason R. Coombs.

Added Windows support for os.symlink when run on Windows 6.0 or greater,
aka Vista. Previous Windows versions will raise NotImplementedError
when trying to symlink.

Includes numerous test updates and additions to test_os, including
a symlink_support module because of the fact that privilege escalation
is required in order to run the tests to ensure that the user is able
to create symlinks. By default, accounts do not have the required
privilege, so the escalation code will have to be exposed later (or
documented on how to do so). I'll be following up with that work next.

Note that the tests use ctypes, which was agreed on during the PyCon
language summit.

2 files changed, 28 insertions, 8 deletions

diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index c838983..7fcb2a9 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -231,11 +231,15 @@ applications should use string objects to access all files.
 
 .. function:: samefile(path1, path2)
 
-   Return ``True`` if both pathname arguments refer to the same file or directory
-   (as indicated by device number and i-node number). Raise an exception if a
-   :func:`os.stat` call on either pathname fails.
+   Return ``True`` if both pathname arguments refer to the same file or directory.
+   On Unix, this is determined by the device number and i-node number and raises an
+   exception if a :func:`os.stat` call on either pathname fails.
 
-   Availability: Unix.
+   On Windows, two files are the same if they resolve to the same final path
+   name using the Windows API call GetFinalPathNameByHandle and this function
+   raises an exception if handles cannot be obtained to either file.
+
+   Availability: Windows, Unix.
 
 
 .. function:: sameopenfile(fp1, fp2)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index b74350d..d8835f6 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1065,7 +1065,7 @@ Files and Directories
 
    Like :func:`stat`, but do not follow symbolic links.  This is an alias for
    :func:`stat` on platforms that do not support symbolic links, such as
-   Windows.
+   Windows prior to 6.0 (Vista).
 
 
 .. function:: mkfifo(path[, mode])
@@ -1181,7 +1181,7 @@ Files and Directories
    and the call may raise an UnicodeDecodeError. If the *path* is a bytes
    object, the result will be a bytes object.
 
-   Availability: Unix.
+   Availability: Unix, Windows.
 
 
 .. function:: remove(path)
@@ -1341,9 +1341,25 @@ Files and Directories
 
 .. function:: symlink(source, link_name)
 
-   Create a symbolic link pointing to *source* named *link_name*.
+   Create a symbolic link pointing to *source* named *link_name*.  On Windows,
+   symlink version takes an additional, optional parameter,
+   *target_is_directory*, which defaults to False.
 
-   Availability: Unix.
+   symlink(source, link_name, target_is_directory=False)
+
+   On Windows, a symlink represents a file or a directory, and does not
+   morph to the target dynamically.  For this reason, when creating a
+   symlink on Windows, if the target is not already present, the symlink
+   will default to being a file symlink.  If *target_is_directory* is set to
+   True, the symlink will be created as a directory symlink.  This
+   parameter is ignored if the target exists (and the symlink is created
+   with the same type as the target).
+
+   Symbolic link support was introduced in Windows 6.0 (Vista). *symlink*
+   will raise a NotImplementedError on Windows versions earlier than 6.0. The
+   SeCreateSymbolicLinkPrivilege is required in order to create symlinks.
+
+   Availability:  Unix, Windows 6.0.
 
 
 .. function:: unlink(path)