Lib/os.py

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