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