diff -r 0243f7da89cb Doc/faq/windows.rst --- a/Doc/faq/windows.rst Wed Jul 30 19:24:47 2014 -0400 +++ b/Doc/faq/windows.rst Wed Aug 13 10:44:21 2014 -0400 @@ -342,3 +342,67 @@ able to handle it. (If your copy of WinZip doesn't, get a newer one from http://www.winzip.com.) +How to use os.symlink links on Windows. +--------------------------------------- + +Symbolic links are a way to create a file that points to the contents of another file. They are comprised of two parts, the *source* file and the *link* file. The source file is a pre-existing file that contains content you would like to access through an alternative path (the link). + +Symbolic links are not supported in older versions of Windows. You will need to be running Windows 6.0 (Vista/Windows Server 2008) or later to create symbolic links. Calling :func:`os.symlink` in an earlier version will raise a :exc:`NotImplementedError`. + +An example of :func:`os.symlink` is as follows: + + >>> src = "C:\\Users\\Test\\Documents\\src\\" + >>> os.path.exists(src) + True + >>> lnk = "C:\\Users\\Test\\Documents\\lnk\\" + >>> os.path.exists(lnk) + False + >>> os.symlink(src, lnk) + +Now if you look at this folder in the FIle Explorer, you may notice that the lnk folder has been created, and it has a little arrow on the file icon. This indicates lnk is a link. There are multiple types of links, but covering them all is outside the scope of this section, but we know that in this case lnk is a symbolic link. + +You can now experiment by adding files to the lnk folder and to src folder. You will notice that files added to one folder are visible when looking in the other folder and vice versa. It's important to note that there exists only copy of each file, and they live in the src folder. The lnk path looks and can be interacted with like a normal folder, but it is a link so it only contains a reference to src, it does not contain files of its own. + +In the basic example, we used two directories, but symbolic links can also be applied to files. It works similarly in that you will have a single file accessible though two paths, and editing the file when accessing it though one path will be reflected when accessing it from the other. + +Symbolic links cannot take a pre-existing path as the link. Passing in a preexisting path as a link will result in a :exc:`FileExistsError` like so: + + >>> os.path.exists(dir) + True + >>> os.symlink(src, dir) + Traceback (most recent call last): + File "", line 1, in + os.symlink(src,dst) + FileExistsError: [WinError 183] Cannot create a file when that file already exists: 'C:\\Users\\Test\\Documents\\src\\' -> 'C:\\Users\\Test\\Documents\\dst\\' + +Another thing you should be aware of is that while we showed that normal editing of the file through either path behaves the same, not every interaction will yield the same results on both paths. If we revisit our original example with the src folder and lnk link, if we delete lnk through the File Explorer we will see that the link is deleted but the source folder is unaffected. + +To determine how a Python operation on a path to a symbolic link will behave, it is best to read the specific docs. In Python, operations on paths sometimes correlate to an operating system call (for example :func:`os.rmdir` and the rmdir command) in these cases (unless specified by the docs) Python usually defaults to the behavior of the operating system command. Sometimes the Python docs will explicitly specify if a function *follows symbolic links*. Following symbolic links means that if you pass a symbolic link in, that function will operate on the file the link refers to. If it does not follow symbolic links, then it will operate on the link file itself. + +When using symbolic links on Windows, you may encounter this :exc:`OSError`: + + >>> os.symlink(src, lnk) + Traceback (most recent call last): + File "", line 1, in + os.symlink(src, lnk') + OSError: symbolic link privilege not held + +First it would be useful to explain how privileges in Windows work. Privileges dictate what actions you can or cannot take. They exist as a safeguard. + +There are two ways to get around this :exc:`OSError` The quick and dirty method is to run Python as an administrator. To do this you you simply right click the Python shortcut and select 'Run as Administrator'. This method is tedious in that you will have to remember to run as administrator every time you would like to use symlinks in your code. It is also can also be problematic in that it is unnecessarily granting all administrator privileges when you may only need some specific privileges. + +The second method is to grant you user account permission to create symlinks. Any Python process launched by a user account will inherit that user's permissions by default. This is useful because you won't have to remember to run your script a particular way each time to grant the needed permissions, and you will only be granting the permissions that are actually relevant to the task at hand. + +Assigning privileges is a privilege itself that normal users do not have by default. If you user account does not have this privilege, you will have to log in as an Administrator or have your local Administrator help you. + +You can assign privileges through the User Rights Assignment dialog. To access this, open the Control Panel and select :menuselection:`Administrative Tools --> Local Security Policy --> Local Policies --> User Rights Assignment`. Here you will see a list of all the privileges that can be applied to a user or a user group. Select Create symbolic links and add your user account, then finally hit 'Apply'. If you relaunch Python you should now be able to use :func:`os.symlink`. + +A similar looking, but different error you may encounter is a :exc:`PermissionError`: + + >>> os.symlink(src, lnk) + Traceback (most recent call last): + File "", line 1, in + os.symlink(src,dst) + PermissionError: [WinError 5] Access is denied: 'C:\\Users\\Test\\Documents\\notownedbytest\\' -> 'C:\\Users\\Test\\Documents\\lnk\\' + +Privileges and permissions sound similar, but refer to two different concepts. Privileges, as previously discussed, determine what actions you can take. Permissions determine what files you can do those actions on. Each file has an 'owner' and by default the owner and Administrators have permission to exercise all of it's privileges on that file. You can grant other users the permissions on a file (assuming you have the privilege to do so) by right clicking a file, selecting Properties > Security.