Lib/os.py

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