Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(6)

Side by Side Diff: Doc/faq/windows.rst

Issue 10608: Add a section to Windows FAQ explaining os.symlink
Patch Set: Created 5 years, 6 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :tocdepth: 2 1 :tocdepth: 2
2 2
3 .. _windows-faq: 3 .. _windows-faq:
4 4
5 ===================== 5 =====================
6 Python on Windows FAQ 6 Python on Windows FAQ
7 ===================== 7 =====================
8 8
9 .. only:: html 9 .. only:: html
10 10
(...skipping 324 matching lines...) Expand 10 before | Expand all | Expand 10 after
335 --------------------------------------------------------- 335 ---------------------------------------------------------
336 336
337 Sometimes, when you download the documentation package to a Windows machine 337 Sometimes, when you download the documentation package to a Windows machine
338 using a web browser, the file extension of the saved file ends up being .EXE. 338 using a web browser, the file extension of the saved file ends up being .EXE.
339 This is a mistake; the extension should be .TGZ. 339 This is a mistake; the extension should be .TGZ.
340 340
341 Simply rename the downloaded file to have the .TGZ extension, and WinZip will be 341 Simply rename the downloaded file to have the .TGZ extension, and WinZip will be
342 able to handle it. (If your copy of WinZip doesn't, get a newer one from 342 able to handle it. (If your copy of WinZip doesn't, get a newer one from
343 http://www.winzip.com.) 343 http://www.winzip.com.)
344 344
345 How to use os.symlink links on Windows.
346 ---------------------------------------
347
348 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. T he source file is a pre-existing file that contains content you would like to ac cess through an alternative path (the link).
349
350 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 l inks. Calling :func:`os.symlink` in an earlier version will raise a :exc:`NotImp lementedError`.
351
352 An example of :func:`os.symlink` is as follows:
353
354 >>> src = "C:\\Users\\Test\\Documents\\src\\"
355 >>> os.path.exists(src)
356 True
357 >>> lnk = "C:\\Users\\Test\\Documents\\lnk\\"
358 >>> os.path.exists(lnk)
359 False
360 >>> os.symlink(src, lnk)
361
362 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 indic ates 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 symbol ic link.
363
364 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 ea ch file, and they live in the src folder. The lnk path looks and can be interact ed with like a normal folder, but it is a link so it only contains a reference t o src, it does not contain files of its own.
365
366 In the basic example, we used two directories, but symbolic links can also be ap plied to files. It works similarly in that you will have a single file accessibl e though two paths, and editing the file when accessing it though one path will be reflected when accessing it from the other.
367
368 Symbolic links cannot take a pre-existing path as the link. Passing in a preexis ting path as a link will result in a :exc:`FileExistsError` like so:
369
370 >>> os.path.exists(dir)
371 True
372 >>> os.symlink(src, dir)
373 Traceback (most recent call last):
374 File "<pyshell#13>", line 1, in <module>
375 os.symlink(src,dst)
376 FileExistsError: [WinError 183] Cannot create a file when that file already exists: 'C:\\Users\\Test\\Documents\\src\\' -> 'C:\\Users\\Test\\Documents\\dst\ \'
377
378 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 yi eld 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.
379
380 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 cor relate to an operating system call (for example :func:`os.rmdir` and the rmdir c ommand) in these cases (unless specified by the docs) Python usually defaults to the behavior of the operating system command. Sometimes the Python docs will ex plicitly specify if a function *follows symbolic links*. Following symbolic link s means that if you pass a symbolic link in, that function will operate on the f ile the link refers to. If it does not follow symbolic links, then it will opera te on the link file itself.
381
382 When using symbolic links on Windows, you may encounter this :exc:`OSError`:
383
384 >>> os.symlink(src, lnk)
385 Traceback (most recent call last):
386 File "<pyshell#13>", line 1, in <module>
387 os.symlink(src, lnk')
388 OSError: symbolic link privilege not held
389
390 First it would be useful to explain how privileges in Windows work. Privileges d ictate what actions you can or cannot take. They exist as a safeguard.
391
392 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 tha t 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 unn ecessarily granting all administrator privileges when you may only need some spe cific privileges.
393
394 The second method is to grant you user account permission to create symlinks. An y 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 scrip t 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.
395
396 Assigning privileges is a privilege itself that normal users do not have by defa ult. If you user account does not have this privilege, you will have to log in a s an Administrator or have your local Administrator help you.
397
398 You can assign privileges through the User Rights Assignment dialog. To access t his, open the Control Panel and select :menuselection:`Administrative Tools --> Local Security Policy --> Local Policies --> User Rights Assignment`. Here you w ill see a list of all the privileges that can be applied to a user or a user gro up. Select Create symbolic links and add your user account, then finally hit 'Ap ply'. If you relaunch Python you should now be able to use :func:`os.symlink`.
399
400 A similar looking, but different error you may encounter is a :exc:`PermissionEr ror`:
401
402 >>> os.symlink(src, lnk)
403 Traceback (most recent call last):
404 File "<pyshell#31>", line 1, in <module>
405 os.symlink(src,dst)
406 PermissionError: [WinError 5] Access is denied: 'C:\\Users\\Test\\Documents\ \notownedbytest\\' -> 'C:\\Users\\Test\\Documents\\lnk\\'
407
408 Privileges and permissions sound similar, but refer to two different concepts. P rivileges, as previously discussed, determine what actions you can take. Permiss ions 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 i t'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.
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+