os.py revision 8844e438b1e0a3546f15213df7741c3141859eeb
1r"""OS routines for Mac, NT, or Posix depending on what system we're on. 2 3This exports: 4 - all functions from posix, nt, os2, mac, or ce, e.g. unlink, stat, etc. 5 - os.path is one of the modules posixpath, ntpath, or macpath 6 - os.name is 'posix', 'nt', 'os2', 'mac', 'ce' or 'riscos' 7 - os.curdir is a string representing the current directory ('.' or ':') 8 - os.pardir is a string representing the parent directory ('..' or '::') 9 - os.sep is the (or a most common) pathname separator ('/' or ':' or '\\') 10 - os.extsep is the extension separator ('.' or '/') 11 - os.altsep is the alternate pathname separator (None or '/') 12 - os.pathsep is the component separator used in $PATH etc 13 - os.linesep is the line separator in text files ('\r' or '\n' or '\r\n') 14 - os.defpath is the default search path for executables 15 - os.devnull is the file path of the null device ('/dev/null', etc.) 16 17Programs that import and use 'os' stand a better chance of being 18portable between different platforms. Of course, they must then 19only use functions that are defined by all platforms (e.g., unlink 20and opendir), and leave all pathname manipulation to os.path 21(e.g., split and join). 22""" 23 24#' 25 26import sys 27 28_names = sys.builtin_module_names 29 30# Note: more names are added to __all__ later. 31__all__ = ["altsep", "curdir", "pardir", "sep", "pathsep", "linesep", 32 "defpath", "name", "path", "devnull", 33 "SEEK_SET", "SEEK_CUR", "SEEK_END"] 34 35def _get_exports_list(module): 36 try: 37 return list(module.__all__) 38 except AttributeError: 39 return [n for n in dir(module) if n[0] != '_'] 40 41if 'posix' in _names: 42 name = 'posix' 43 linesep = '\n' 44 from posix import * 45 try: 46 from posix import _exit 47 except ImportError: 48 pass 49 import posixpath as path 50 51 import posix 52 __all__.extend(_get_exports_list(posix)) 53 del posix 54 55elif 'nt' in _names: 56 name = 'nt' 57 linesep = '\r\n' 58 from nt import * 59 try: 60 from nt import _exit 61 except ImportError: 62 pass 63 import ntpath as path 64 65 import nt 66 __all__.extend(_get_exports_list(nt)) 67 del nt 68 69elif 'os2' in _names: 70 name = 'os2' 71 linesep = '\r\n' 72 from os2 import * 73 try: 74 from os2 import _exit 75 except ImportError: 76 pass 77 if sys.version.find('EMX GCC') == -1: 78 import ntpath as path 79 else: 80 import os2emxpath as path 81 from _emx_link import link 82 83 import os2 84 __all__.extend(_get_exports_list(os2)) 85 del os2 86 87elif 'mac' in _names: 88 name = 'mac' 89 linesep = '\r' 90 from mac import * 91 try: 92 from mac import _exit 93 except ImportError: 94 pass 95 import macpath as path 96 97 import mac 98 __all__.extend(_get_exports_list(mac)) 99 del mac 100 101elif 'ce' in _names: 102 name = 'ce' 103 linesep = '\r\n' 104 from ce import * 105 try: 106 from ce import _exit 107 except ImportError: 108 pass 109 # We can use the standard Windows path. 110 import ntpath as path 111 112 import ce 113 __all__.extend(_get_exports_list(ce)) 114 del ce 115 116elif 'riscos' in _names: 117 name = 'riscos' 118 linesep = '\n' 119 from riscos import * 120 try: 121 from riscos import _exit 122 except ImportError: 123 pass 124 import riscospath as path 125 126 import riscos 127 __all__.extend(_get_exports_list(riscos)) 128 del riscos 129 130else: 131 raise ImportError, 'no os specific module found' 132 133sys.modules['os.path'] = path 134from os.path import (curdir, pardir, sep, pathsep, defpath, extsep, altsep, 135 devnull) 136 137del _names 138 139# Python uses fixed values for the SEEK_ constants; they are mapped 140# to native constants if necessary in posixmodule.c 141SEEK_SET = 0 142SEEK_CUR = 1 143SEEK_END = 2 144 145#' 146 147# Super directory utilities. 148# (Inspired by Eric Raymond; the doc strings are mostly his) 149 150def makedirs(name, mode=0777): 151 """makedirs(path [, mode=0777]) 152 153 Super-mkdir; create a leaf directory and all intermediate ones. 154 Works like mkdir, except that any intermediate path segment (not 155 just the rightmost) will be created if it does not exist. This is 156 recursive. 157 158 """ 159 from errno import EEXIST 160 head, tail = path.split(name) 161 if not tail: 162 head, tail = path.split(head) 163 if head and tail and not path.exists(head): 164 try: 165 makedirs(head, mode) 166 except OSError, e: 167 # be happy if someone already created the path 168 if e.errno != EEXIST: 169 raise 170 if tail == curdir: # xxx/newdir/. exists if xxx/newdir exists 171 return 172 mkdir(name, mode) 173 174def removedirs(name): 175 """removedirs(path) 176 177 Super-rmdir; remove a leaf directory and all empty intermediate 178 ones. Works like rmdir except that, if the leaf directory is 179 successfully removed, directories corresponding to rightmost path 180 segments will be pruned away until either the whole path is 181 consumed or an error occurs. Errors during this latter phase are 182 ignored -- they generally mean that a directory was not empty. 183 184 """ 185 rmdir(name) 186 head, tail = path.split(name) 187 if not tail: 188 head, tail = path.split(head) 189 while head and tail: 190 try: 191 rmdir(head) 192 except error: 193 break 194 head, tail = path.split(head) 195 196def renames(old, new): 197 """renames(old, new) 198 199 Super-rename; create directories as necessary and delete any left 200 empty. Works like rename, except creation of any intermediate 201 directories needed to make the new pathname good is attempted 202 first. After the rename, directories corresponding to rightmost 203 path segments of the old name will be pruned way until either the 204 whole path is consumed or a nonempty directory is found. 205 206 Note: this function can fail with the new directory structure made 207 if you lack permissions needed to unlink the leaf directory or 208 file. 209 210 """ 211 head, tail = path.split(new) 212 if head and tail and not path.exists(head): 213 makedirs(head) 214 rename(old, new) 215 head, tail = path.split(old) 216 if head and tail: 217 try: 218 removedirs(head) 219 except error: 220 pass 221 222__all__.extend(["makedirs", "removedirs", "renames"]) 223 224def walk(top, topdown=True, onerror=None, followlinks=False): 225 """Directory tree generator. 226 227 For each directory in the directory tree rooted at top (including top 228 itself, but excluding '.' and '..'), yields a 3-tuple 229 230 dirpath, dirnames, filenames 231 232 dirpath is a string, the path to the directory. dirnames is a list of 233 the names of the subdirectories in dirpath (excluding '.' and '..'). 234 filenames is a list of the names of the non-directory files in dirpath. 235 Note that the names in the lists are just names, with no path components. 236 To get a full path (which begins with top) to a file or directory in 237 dirpath, do os.path.join(dirpath, name). 238 239 If optional arg 'topdown' is true or not specified, the triple for a 240 directory is generated before the triples for any of its subdirectories 241 (directories are generated top down). If topdown is false, the triple 242 for a directory is generated after the triples for all of its 243 subdirectories (directories are generated bottom up). 244 245 When topdown is true, the caller can modify the dirnames list in-place 246 (e.g., via del or slice assignment), and walk will only recurse into the 247 subdirectories whose names remain in dirnames; this can be used to prune 248 the search, or to impose a specific order of visiting. Modifying 249 dirnames when topdown is false is ineffective, since the directories in 250 dirnames have already been generated by the time dirnames itself is 251 generated. 252 253 By default errors from the os.listdir() call are ignored. If 254 optional arg 'onerror' is specified, it should be a function; it 255 will be called with one argument, an os.error instance. It can 256 report the error to continue with the walk, or raise the exception 257 to abort the walk. Note that the filename is available as the 258 filename attribute of the exception object. 259 260 By default, os.walk does not follow symbolic links to subdirectories on 261 systems that support them. In order to get this functionality, set the 262 optional argument 'followlinks' to true. 263 264 Caution: if you pass a relative pathname for top, don't change the 265 current working directory between resumptions of walk. walk never 266 changes the current directory, and assumes that the client doesn't 267 either. 268 269 Example: 270 271 from os.path import join, getsize 272 for root, dirs, files in walk('python/Lib/email'): 273 print root, "consumes", 274 print sum([getsize(join(root, name)) for name in files]), 275 print "bytes in", len(files), "non-directory files" 276 if 'CVS' in dirs: 277 dirs.remove('CVS') # don't visit CVS directories 278 """ 279 280 from os.path import join, isdir, islink 281 282 # We may not have read permission for top, in which case we can't 283 # get a list of the files the directory contains. os.path.walk 284 # always suppressed the exception then, rather than blow up for a 285 # minor reason when (say) a thousand readable directories are still 286 # left to visit. That logic is copied here. 287 try: 288 # Note that listdir and error are globals in this module due 289 # to earlier import-*. 290 names = listdir(top) 291 except error, err: 292 if onerror is not None: 293 onerror(err) 294 return 295 296 dirs, nondirs = [], [] 297 for name in names: 298 if isdir(join(top, name)): 299 dirs.append(name) 300 else: 301 nondirs.append(name) 302 303 if topdown: 304 yield top, dirs, nondirs 305 for name in dirs: 306 path = join(top, name) 307 if followlinks or not islink(path): 308 for x in walk(path, topdown, onerror, followlinks): 309 yield x 310 if not topdown: 311 yield top, dirs, nondirs 312 313__all__.append("walk") 314 315# Make sure os.environ exists, at least 316try: 317 environ 318except NameError: 319 environ = {} 320 321def execl(file, *args): 322 """execl(file, *args) 323 324 Execute the executable file with argument list args, replacing the 325 current process. """ 326 execv(file, args) 327 328def execle(file, *args): 329 """execle(file, *args, env) 330 331 Execute the executable file with argument list args and 332 environment env, replacing the current process. """ 333 env = args[-1] 334 execve(file, args[:-1], env) 335 336def execlp(file, *args): 337 """execlp(file, *args) 338 339 Execute the executable file (which is searched for along $PATH) 340 with argument list args, replacing the current process. """ 341 execvp(file, args) 342 343def execlpe(file, *args): 344 """execlpe(file, *args, env) 345 346 Execute the executable file (which is searched for along $PATH) 347 with argument list args and environment env, replacing the current 348 process. """ 349 env = args[-1] 350 execvpe(file, args[:-1], env) 351 352def execvp(file, args): 353 """execp(file, args) 354 355 Execute the executable file (which is searched for along $PATH) 356 with argument list args, replacing the current process. 357 args may be a list or tuple of strings. """ 358 _execvpe(file, args) 359 360def execvpe(file, args, env): 361 """execvpe(file, args, env) 362 363 Execute the executable file (which is searched for along $PATH) 364 with argument list args and environment env , replacing the 365 current process. 366 args may be a list or tuple of strings. """ 367 _execvpe(file, args, env) 368 369__all__.extend(["execl","execle","execlp","execlpe","execvp","execvpe"]) 370 371def _execvpe(file, args, env=None): 372 from errno import ENOENT, ENOTDIR 373 374 if env is not None: 375 func = execve 376 argrest = (args, env) 377 else: 378 func = execv 379 argrest = (args,) 380 env = environ 381 382 head, tail = path.split(file) 383 if head: 384 func(file, *argrest) 385 return 386 if 'PATH' in env: 387 envpath = env['PATH'] 388 else: 389 envpath = defpath 390 PATH = envpath.split(pathsep) 391 saved_exc = None 392 saved_tb = None 393 for dir in PATH: 394 fullname = path.join(dir, file) 395 try: 396 func(fullname, *argrest) 397 except error, e: 398 tb = sys.exc_info()[2] 399 if (e.errno != ENOENT and e.errno != ENOTDIR 400 and saved_exc is None): 401 saved_exc = e 402 saved_tb = tb 403 if saved_exc: 404 raise error, saved_exc, saved_tb 405 raise error, e, tb 406 407# Change environ to automatically call putenv() if it exists 408try: 409 # This will fail if there's no putenv 410 putenv 411except NameError: 412 pass 413else: 414 import UserDict 415 416 # Fake unsetenv() for Windows 417 # not sure about os2 here but 418 # I'm guessing they are the same. 419 420 if name in ('os2', 'nt'): 421 def unsetenv(key): 422 putenv(key, "") 423 424 if name == "riscos": 425 # On RISC OS, all env access goes through getenv and putenv 426 from riscosenviron import _Environ 427 elif name in ('os2', 'nt'): # Where Env Var Names Must Be UPPERCASE 428 # But we store them as upper case 429 class _Environ(UserDict.IterableUserDict): 430 def __init__(self, environ): 431 UserDict.UserDict.__init__(self) 432 data = self.data 433 for k, v in environ.items(): 434 data[k.upper()] = v 435 def __setitem__(self, key, item): 436 putenv(key, item) 437 self.data[key.upper()] = item 438 def __getitem__(self, key): 439 return self.data[key.upper()] 440 try: 441 unsetenv 442 except NameError: 443 def __delitem__(self, key): 444 del self.data[key.upper()] 445 else: 446 def __delitem__(self, key): 447 unsetenv(key) 448 del self.data[key.upper()] 449 def has_key(self, key): 450 return key.upper() in self.data 451 def __contains__(self, key): 452 return key.upper() in self.data 453 def get(self, key, failobj=None): 454 return self.data.get(key.upper(), failobj) 455 def update(self, dict=None, **kwargs): 456 if dict: 457 try: 458 keys = dict.keys() 459 except AttributeError: 460 # List of (key, value) 461 for k, v in dict: 462 self[k] = v 463 else: 464 # got keys 465 # cannot use items(), since mappings 466 # may not have them. 467 for k in keys: 468 self[k] = dict[k] 469 if kwargs: 470 self.update(kwargs) 471 def copy(self): 472 return dict(self) 473 474 else: # Where Env Var Names Can Be Mixed Case 475 class _Environ(UserDict.IterableUserDict): 476 def __init__(self, environ): 477 UserDict.UserDict.__init__(self) 478 self.data = environ 479 def __setitem__(self, key, item): 480 putenv(key, item) 481 self.data[key] = item 482 def update(self, dict=None, **kwargs): 483 if dict: 484 try: 485 keys = dict.keys() 486 except AttributeError: 487 # List of (key, value) 488 for k, v in dict: 489 self[k] = v 490 else: 491 # got keys 492 # cannot use items(), since mappings 493 # may not have them. 494 for k in keys: 495 self[k] = dict[k] 496 if kwargs: 497 self.update(kwargs) 498 try: 499 unsetenv 500 except NameError: 501 pass 502 else: 503 def __delitem__(self, key): 504 unsetenv(key) 505 del self.data[key] 506 def copy(self): 507 return dict(self) 508 509 510 environ = _Environ(environ) 511 512def getenv(key, default=None): 513 """Get an environment variable, return None if it doesn't exist. 514 The optional second argument can specify an alternate default.""" 515 return environ.get(key, default) 516__all__.append("getenv") 517 518def _exists(name): 519 try: 520 eval(name) 521 return True 522 except NameError: 523 return False 524 525# Supply spawn*() (probably only for Unix) 526if _exists("fork") and not _exists("spawnv") and _exists("execv"): 527 528 P_WAIT = 0 529 P_NOWAIT = P_NOWAITO = 1 530 531 # XXX Should we support P_DETACH? I suppose it could fork()**2 532 # and close the std I/O streams. Also, P_OVERLAY is the same 533 # as execv*()? 534 535 def _spawnvef(mode, file, args, env, func): 536 # Internal helper; func is the exec*() function to use 537 pid = fork() 538 if not pid: 539 # Child 540 try: 541 if env is None: 542 func(file, args) 543 else: 544 func(file, args, env) 545 except: 546 _exit(127) 547 else: 548 # Parent 549 if mode == P_NOWAIT: 550 return pid # Caller is responsible for waiting! 551 while 1: 552 wpid, sts = waitpid(pid, 0) 553 if WIFSTOPPED(sts): 554 continue 555 elif WIFSIGNALED(sts): 556 return -WTERMSIG(sts) 557 elif WIFEXITED(sts): 558 return WEXITSTATUS(sts) 559 else: 560 raise error, "Not stopped, signaled or exited???" 561 562 def spawnv(mode, file, args): 563 """spawnv(mode, file, args) -> integer 564 565Execute file with arguments from args in a subprocess. 566If mode == P_NOWAIT return the pid of the process. 567If mode == P_WAIT return the process's exit code if it exits normally; 568otherwise return -SIG, where SIG is the signal that killed it. """ 569 return _spawnvef(mode, file, args, None, execv) 570 571 def spawnve(mode, file, args, env): 572 """spawnve(mode, file, args, env) -> integer 573 574Execute file with arguments from args in a subprocess with the 575specified environment. 576If mode == P_NOWAIT return the pid of the process. 577If mode == P_WAIT return the process's exit code if it exits normally; 578otherwise return -SIG, where SIG is the signal that killed it. """ 579 return _spawnvef(mode, file, args, env, execve) 580 581 # Note: spawnvp[e] is't currently supported on Windows 582 583 def spawnvp(mode, file, args): 584 """spawnvp(mode, file, args) -> integer 585 586Execute file (which is looked for along $PATH) with arguments from 587args in a subprocess. 588If mode == P_NOWAIT return the pid of the process. 589If mode == P_WAIT return the process's exit code if it exits normally; 590otherwise return -SIG, where SIG is the signal that killed it. """ 591 return _spawnvef(mode, file, args, None, execvp) 592 593 def spawnvpe(mode, file, args, env): 594 """spawnvpe(mode, file, args, env) -> integer 595 596Execute file (which is looked for along $PATH) with arguments from 597args in a subprocess with the supplied environment. 598If mode == P_NOWAIT return the pid of the process. 599If mode == P_WAIT return the process's exit code if it exits normally; 600otherwise return -SIG, where SIG is the signal that killed it. """ 601 return _spawnvef(mode, file, args, env, execvpe) 602 603if _exists("spawnv"): 604 # These aren't supplied by the basic Windows code 605 # but can be easily implemented in Python 606 607 def spawnl(mode, file, *args): 608 """spawnl(mode, file, *args) -> integer 609 610Execute file with arguments from args in a subprocess. 611If mode == P_NOWAIT return the pid of the process. 612If mode == P_WAIT return the process's exit code if it exits normally; 613otherwise return -SIG, where SIG is the signal that killed it. """ 614 return spawnv(mode, file, args) 615 616 def spawnle(mode, file, *args): 617 """spawnle(mode, file, *args, env) -> integer 618 619Execute file with arguments from args in a subprocess with the 620supplied environment. 621If mode == P_NOWAIT return the pid of the process. 622If mode == P_WAIT return the process's exit code if it exits normally; 623otherwise return -SIG, where SIG is the signal that killed it. """ 624 env = args[-1] 625 return spawnve(mode, file, args[:-1], env) 626 627 628 __all__.extend(["spawnv", "spawnve", "spawnl", "spawnle",]) 629 630 631if _exists("spawnvp"): 632 # At the moment, Windows doesn't implement spawnvp[e], 633 # so it won't have spawnlp[e] either. 634 def spawnlp(mode, file, *args): 635 """spawnlp(mode, file, *args) -> integer 636 637Execute file (which is looked for along $PATH) with arguments from 638args in a subprocess with the supplied environment. 639If mode == P_NOWAIT return the pid of the process. 640If mode == P_WAIT return the process's exit code if it exits normally; 641otherwise return -SIG, where SIG is the signal that killed it. """ 642 return spawnvp(mode, file, args) 643 644 def spawnlpe(mode, file, *args): 645 """spawnlpe(mode, file, *args, env) -> integer 646 647Execute file (which is looked for along $PATH) with arguments from 648args in a subprocess with the supplied environment. 649If mode == P_NOWAIT return the pid of the process. 650If mode == P_WAIT return the process's exit code if it exits normally; 651otherwise return -SIG, where SIG is the signal that killed it. """ 652 env = args[-1] 653 return spawnvpe(mode, file, args[:-1], env) 654 655 656 __all__.extend(["spawnvp", "spawnvpe", "spawnlp", "spawnlpe",]) 657 658 659# Supply popen2 etc. (for Unix) 660if _exists("fork"): 661 if not _exists("popen2"): 662 def popen2(cmd, mode="t", bufsize=-1): 663 """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' 664 may be a sequence, in which case arguments will be passed directly to 665 the program without shell intervention (as with os.spawnv()). If 'cmd' 666 is a string it will be passed to the shell (as with os.system()). If 667 'bufsize' is specified, it sets the buffer size for the I/O pipes. The 668 file objects (child_stdin, child_stdout) are returned.""" 669 import popen2 670 stdout, stdin = popen2.popen2(cmd, bufsize) 671 return stdin, stdout 672 __all__.append("popen2") 673 674 if not _exists("popen3"): 675 def popen3(cmd, mode="t", bufsize=-1): 676 """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' 677 may be a sequence, in which case arguments will be passed directly to 678 the program without shell intervention (as with os.spawnv()). If 'cmd' 679 is a string it will be passed to the shell (as with os.system()). If 680 'bufsize' is specified, it sets the buffer size for the I/O pipes. The 681 file objects (child_stdin, child_stdout, child_stderr) are returned.""" 682 import popen2 683 stdout, stdin, stderr = popen2.popen3(cmd, bufsize) 684 return stdin, stdout, stderr 685 __all__.append("popen3") 686 687 if not _exists("popen4"): 688 def popen4(cmd, mode="t", bufsize=-1): 689 """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' 690 may be a sequence, in which case arguments will be passed directly to 691 the program without shell intervention (as with os.spawnv()). If 'cmd' 692 is a string it will be passed to the shell (as with os.system()). If 693 'bufsize' is specified, it sets the buffer size for the I/O pipes. The 694 file objects (child_stdin, child_stdout_stderr) are returned.""" 695 import popen2 696 stdout, stdin = popen2.popen4(cmd, bufsize) 697 return stdin, stdout 698 __all__.append("popen4") 699 700import copy_reg as _copy_reg 701 702def _make_stat_result(tup, dict): 703 return stat_result(tup, dict) 704 705def _pickle_stat_result(sr): 706 (type, args) = sr.__reduce__() 707 return (_make_stat_result, args) 708 709try: 710 _copy_reg.pickle(stat_result, _pickle_stat_result, _make_stat_result) 711except NameError: # stat_result may not exist 712 pass 713 714def _make_statvfs_result(tup, dict): 715 return statvfs_result(tup, dict) 716 717def _pickle_statvfs_result(sr): 718 (type, args) = sr.__reduce__() 719 return (_make_statvfs_result, args) 720 721try: 722 _copy_reg.pickle(statvfs_result, _pickle_statvfs_result, 723 _make_statvfs_result) 724except NameError: # statvfs_result may not exist 725 pass 726 727if not _exists("urandom"): 728 def urandom(n): 729 """urandom(n) -> str 730 731 Return a string of n random bytes suitable for cryptographic use. 732 733 """ 734 try: 735 _urandomfd = open("/dev/urandom", O_RDONLY) 736 except (OSError, IOError): 737 raise NotImplementedError("/dev/urandom (or equivalent) not found") 738 bytes = "" 739 while len(bytes) < n: 740 bytes += read(_urandomfd, n - len(bytes)) 741 close(_urandomfd) 742 return bytes 743