1
# Bazaar -- distributed version control
 
 
3
# Copyright (C) 2005 by Canonical Ltd
 
 
5
# This program is free software; you can redistribute it and/or modify
 
 
6
# it under the terms of the GNU General Public License as published by
 
 
7
# the Free Software Foundation; either version 2 of the License, or
 
 
8
# (at your option) any later version.
 
 
10
# This program is distributed in the hope that it will be useful,
 
 
11
# but WITHOUT ANY WARRANTY; without even the implied warranty of
 
 
12
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
 
13
# GNU General Public License for more details.
 
 
15
# You should have received a copy of the GNU General Public License
 
 
16
# along with this program; if not, write to the Free Software
 
 
17
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
 
19
from cStringIO import StringIO
 
 
23
from stat import (S_ISREG, S_ISDIR, S_ISLNK, ST_MODE, ST_SIZE,
 
 
24
                  S_ISCHR, S_ISBLK, S_ISFIFO, S_ISSOCK)
 
 
28
from bzrlib.lazy_import import lazy_import
 
 
29
lazy_import(globals(), """
 
 
31
from ntpath import (abspath as _nt_abspath,
 
 
33
                    normpath as _nt_normpath,
 
 
34
                    realpath as _nt_realpath,
 
 
35
                    splitdrive as _nt_splitdrive,
 
 
45
from tempfile import (
 
 
55
from bzrlib.errors import (
 
 
57
    BzrBadParameterNotUnicode,
 
 
62
from bzrlib.symbol_versioning import (
 
 
66
from bzrlib.trace import mutter
 
 
69
# On win32, O_BINARY is used to indicate the file should
 
 
70
# be opened in binary mode, rather than text mode.
 
 
71
# On other platforms, O_BINARY doesn't exist, because
 
 
72
# they always open in binary mode, so it is okay to
 
 
73
# OR with 0 on those platforms
 
 
74
O_BINARY = getattr(os, 'O_BINARY', 0)
 
 
77
def make_readonly(filename):
 
 
78
    """Make a filename read-only."""
 
 
79
    mod = os.stat(filename).st_mode
 
 
81
    os.chmod(filename, mod)
 
 
84
def make_writable(filename):
 
 
85
    mod = os.stat(filename).st_mode
 
 
87
    os.chmod(filename, mod)
 
 
94
    """Return a quoted filename filename
 
 
96
    This previously used backslash quoting, but that works poorly on
 
 
98
    # TODO: I'm not really sure this is the best format either.x
 
 
100
    if _QUOTE_RE is None:
 
 
101
        _QUOTE_RE = re.compile(r'([^a-zA-Z0-9.,:/\\_~-])')
 
 
103
    if _QUOTE_RE.search(f):
 
 
109
_directory_kind = 'directory'
 
 
112
    stat.S_IFDIR:_directory_kind,
 
 
113
    stat.S_IFCHR:'chardev',
 
 
114
    stat.S_IFBLK:'block',
 
 
117
    stat.S_IFLNK:'symlink',
 
 
118
    stat.S_IFSOCK:'socket',
 
 
122
def file_kind_from_stat_mode(stat_mode, _formats=_formats, _unknown='unknown'):
 
 
123
    """Generate a file kind from a stat mode. This is used in walkdirs.
 
 
125
    Its performance is critical: Do not mutate without careful benchmarking.
 
 
128
        return _formats[stat_mode & 0170000]
 
 
133
def file_kind(f, _lstat=os.lstat, _mapper=file_kind_from_stat_mode):
 
 
135
        return _mapper(_lstat(f).st_mode)
 
 
137
        if getattr(e, 'errno', None) == errno.ENOENT:
 
 
138
            raise errors.NoSuchFile(f)
 
 
143
    """Return the current umask"""
 
 
144
    # Assume that people aren't messing with the umask while running
 
 
145
    # XXX: This is not thread safe, but there is no way to get the
 
 
146
    #      umask without setting it
 
 
152
def kind_marker(kind):
 
 
155
    elif kind == _directory_kind:
 
 
157
    elif kind == 'symlink':
 
 
160
        raise BzrError('invalid file kind %r' % kind)
 
 
162
lexists = getattr(os.path, 'lexists', None)
 
 
166
            if getattr(os, 'lstat') is not None:
 
 
172
            if e.errno == errno.ENOENT:
 
 
175
                raise BzrError("lstat/stat of (%r): %r" % (f, e))
 
 
178
def fancy_rename(old, new, rename_func, unlink_func):
 
 
179
    """A fancy rename, when you don't have atomic rename.
 
 
181
    :param old: The old path, to rename from
 
 
182
    :param new: The new path, to rename to
 
 
183
    :param rename_func: The potentially non-atomic rename function
 
 
184
    :param unlink_func: A way to delete the target file if the full rename succeeds
 
 
187
    # sftp rename doesn't allow overwriting, so play tricks:
 
 
189
    base = os.path.basename(new)
 
 
190
    dirname = os.path.dirname(new)
 
 
191
    tmp_name = u'tmp.%s.%.9f.%d.%s' % (base, time.time(), os.getpid(), rand_chars(10))
 
 
192
    tmp_name = pathjoin(dirname, tmp_name)
 
 
194
    # Rename the file out of the way, but keep track if it didn't exist
 
 
195
    # We don't want to grab just any exception
 
 
196
    # something like EACCES should prevent us from continuing
 
 
197
    # The downside is that the rename_func has to throw an exception
 
 
198
    # with an errno = ENOENT, or NoSuchFile
 
 
201
        rename_func(new, tmp_name)
 
 
202
    except (NoSuchFile,), e:
 
 
205
        # RBC 20060103 abstraction leakage: the paramiko SFTP clients rename
 
 
206
        # function raises an IOError with errno is None when a rename fails.
 
 
207
        # This then gets caught here.
 
 
208
        if e.errno not in (None, errno.ENOENT, errno.ENOTDIR):
 
 
211
        if (getattr(e, 'errno', None) is None
 
 
212
            or e.errno not in (errno.ENOENT, errno.ENOTDIR)):
 
 
219
        # This may throw an exception, in which case success will
 
 
221
        rename_func(old, new)
 
 
225
            # If the file used to exist, rename it back into place
 
 
226
            # otherwise just delete it from the tmp location
 
 
228
                unlink_func(tmp_name)
 
 
230
                rename_func(tmp_name, new)
 
 
233
# In Python 2.4.2 and older, os.path.abspath and os.path.realpath
 
 
234
# choke on a Unicode string containing a relative path if
 
 
235
# os.getcwd() returns a non-sys.getdefaultencoding()-encoded
 
 
237
_fs_enc = sys.getfilesystemencoding()
 
 
238
def _posix_abspath(path):
 
 
239
    # jam 20060426 rather than encoding to fsencoding
 
 
240
    # copy posixpath.abspath, but use os.getcwdu instead
 
 
241
    if not posixpath.isabs(path):
 
 
242
        path = posixpath.join(getcwd(), path)
 
 
243
    return posixpath.normpath(path)
 
 
246
def _posix_realpath(path):
 
 
247
    return posixpath.realpath(path.encode(_fs_enc)).decode(_fs_enc)
 
 
250
def _win32_fixdrive(path):
 
 
251
    """Force drive letters to be consistent.
 
 
253
    win32 is inconsistent whether it returns lower or upper case
 
 
254
    and even if it was consistent the user might type the other
 
 
255
    so we force it to uppercase
 
 
256
    running python.exe under cmd.exe return capital C:\\
 
 
257
    running win32 python inside a cygwin shell returns lowercase c:\\
 
 
259
    drive, path = _nt_splitdrive(path)
 
 
260
    return drive.upper() + path
 
 
263
def _win32_abspath(path):
 
 
264
    # Real _nt_abspath doesn't have a problem with a unicode cwd
 
 
265
    return _win32_fixdrive(_nt_abspath(unicode(path)).replace('\\', '/'))
 
 
268
def _win32_realpath(path):
 
 
269
    # Real _nt_realpath doesn't have a problem with a unicode cwd
 
 
270
    return _win32_fixdrive(_nt_realpath(unicode(path)).replace('\\', '/'))
 
 
273
def _win32_pathjoin(*args):
 
 
274
    return _nt_join(*args).replace('\\', '/')
 
 
277
def _win32_normpath(path):
 
 
278
    return _win32_fixdrive(_nt_normpath(unicode(path)).replace('\\', '/'))
 
 
282
    return _win32_fixdrive(os.getcwdu().replace('\\', '/'))
 
 
285
def _win32_mkdtemp(*args, **kwargs):
 
 
286
    return _win32_fixdrive(tempfile.mkdtemp(*args, **kwargs).replace('\\', '/'))
 
 
289
def _win32_rename(old, new):
 
 
290
    """We expect to be able to atomically replace 'new' with old.
 
 
292
    On win32, if new exists, it must be moved out of the way first,
 
 
296
        fancy_rename(old, new, rename_func=os.rename, unlink_func=os.unlink)
 
 
298
        if e.errno in (errno.EPERM, errno.EACCES, errno.EBUSY, errno.EINVAL):
 
 
299
            # If we try to rename a non-existant file onto cwd, we get 
 
 
300
            # EPERM or EACCES instead of ENOENT, this will raise ENOENT 
 
 
301
            # if the old path doesn't exist, sometimes we get EACCES
 
 
302
            # On Linux, we seem to get EBUSY, on Mac we get EINVAL
 
 
308
    return unicodedata.normalize('NFKC', os.getcwdu())
 
 
311
# Default is to just use the python builtins, but these can be rebound on
 
 
312
# particular platforms.
 
 
313
abspath = _posix_abspath
 
 
314
realpath = _posix_realpath
 
 
315
pathjoin = os.path.join
 
 
316
normpath = os.path.normpath
 
 
319
dirname = os.path.dirname
 
 
320
basename = os.path.basename
 
 
321
# These were already imported into local scope
 
 
322
# mkdtemp = tempfile.mkdtemp
 
 
323
# rmtree = shutil.rmtree
 
 
325
MIN_ABS_PATHLENGTH = 1
 
 
328
if sys.platform == 'win32':
 
 
329
    abspath = _win32_abspath
 
 
330
    realpath = _win32_realpath
 
 
331
    pathjoin = _win32_pathjoin
 
 
332
    normpath = _win32_normpath
 
 
333
    getcwd = _win32_getcwd
 
 
334
    mkdtemp = _win32_mkdtemp
 
 
335
    rename = _win32_rename
 
 
337
    MIN_ABS_PATHLENGTH = 3
 
 
339
    def _win32_delete_readonly(function, path, excinfo):
 
 
340
        """Error handler for shutil.rmtree function [for win32]
 
 
341
        Helps to remove files and dirs marked as read-only.
 
 
343
        type_, value = excinfo[:2]
 
 
344
        if function in (os.remove, os.rmdir) \
 
 
345
            and type_ == OSError \
 
 
346
            and value.errno == errno.EACCES:
 
 
352
    def rmtree(path, ignore_errors=False, onerror=_win32_delete_readonly):
 
 
353
        """Replacer for shutil.rmtree: could remove readonly dirs/files"""
 
 
354
        return shutil.rmtree(path, ignore_errors, onerror)
 
 
355
elif sys.platform == 'darwin':
 
 
359
def get_terminal_encoding():
 
 
360
    """Find the best encoding for printing to the screen.
 
 
362
    This attempts to check both sys.stdout and sys.stdin to see
 
 
363
    what encoding they are in, and if that fails it falls back to
 
 
364
    bzrlib.user_encoding.
 
 
365
    The problem is that on Windows, locale.getpreferredencoding()
 
 
366
    is not the same encoding as that used by the console:
 
 
367
    http://mail.python.org/pipermail/python-list/2003-May/162357.html
 
 
369
    On my standard US Windows XP, the preferred encoding is
 
 
370
    cp1252, but the console is cp437
 
 
372
    output_encoding = getattr(sys.stdout, 'encoding', None)
 
 
373
    if not output_encoding:
 
 
374
        input_encoding = getattr(sys.stdin, 'encoding', None)
 
 
375
        if not input_encoding:
 
 
376
            output_encoding = bzrlib.user_encoding
 
 
377
            mutter('encoding stdout as bzrlib.user_encoding %r', output_encoding)
 
 
379
            output_encoding = input_encoding
 
 
380
            mutter('encoding stdout as sys.stdin encoding %r', output_encoding)
 
 
382
        mutter('encoding stdout as sys.stdout encoding %r', output_encoding)
 
 
383
    return output_encoding
 
 
386
def normalizepath(f):
 
 
387
    if getattr(os.path, 'realpath', None) is not None:
 
 
391
    [p,e] = os.path.split(f)
 
 
392
    if e == "" or e == "." or e == "..":
 
 
395
        return pathjoin(F(p), e)
 
 
399
    """Copy a file to a backup.
 
 
401
    Backups are named in GNU-style, with a ~ suffix.
 
 
403
    If the file is already a backup, it's not copied.
 
 
409
    if has_symlinks() and os.path.islink(fn):
 
 
410
        target = os.readlink(fn)
 
 
411
        os.symlink(target, bfn)
 
 
419
    outf = file(bfn, 'wb')
 
 
427
    """True if f is an accessible directory."""
 
 
429
        return S_ISDIR(os.lstat(f)[ST_MODE])
 
 
435
    """True if f is a regular file."""
 
 
437
        return S_ISREG(os.lstat(f)[ST_MODE])
 
 
442
    """True if f is a symlink."""
 
 
444
        return S_ISLNK(os.lstat(f)[ST_MODE])
 
 
448
def is_inside(dir, fname):
 
 
449
    """True if fname is inside dir.
 
 
451
    The parameters should typically be passed to osutils.normpath first, so
 
 
452
    that . and .. and repeated slashes are eliminated, and the separators
 
 
453
    are canonical for the platform.
 
 
455
    The empty string as a dir name is taken as top-of-tree and matches 
 
 
458
    # XXX: Most callers of this can actually do something smarter by 
 
 
459
    # looking at the inventory
 
 
469
    return fname.startswith(dir)
 
 
472
def is_inside_any(dir_list, fname):
 
 
473
    """True if fname is inside any of given dirs."""
 
 
474
    for dirname in dir_list:
 
 
475
        if is_inside(dirname, fname):
 
 
481
def is_inside_or_parent_of_any(dir_list, fname):
 
 
482
    """True if fname is a child or a parent of any of the given files."""
 
 
483
    for dirname in dir_list:
 
 
484
        if is_inside(dirname, fname) or is_inside(fname, dirname):
 
 
490
def pumpfile(fromfile, tofile):
 
 
491
    """Copy contents of one file to another."""
 
 
494
        b = fromfile.read(BUFSIZE)
 
 
500
def file_iterator(input_file, readsize=32768):
 
 
502
        b = input_file.read(readsize)
 
 
509
    if getattr(f, 'tell', None) is not None:
 
 
522
def sha_strings(strings):
 
 
523
    """Return the sha-1 of concatenation of strings"""
 
 
525
    map(s.update, strings)
 
 
535
def fingerprint_file(f):
 
 
540
    return {'size': size,
 
 
541
            'sha1': s.hexdigest()}
 
 
544
def compare_files(a, b):
 
 
545
    """Returns true if equal in contents"""
 
 
556
def local_time_offset(t=None):
 
 
557
    """Return offset of local zone from GMT, either at present or at time t."""
 
 
558
    # python2.3 localtime() can't take None
 
 
562
    if time.localtime(t).tm_isdst and time.daylight:
 
 
565
        return -time.timezone
 
 
568
def format_date(t, offset=0, timezone='original', date_fmt=None, 
 
 
570
    ## TODO: Perhaps a global option to use either universal or local time?
 
 
571
    ## Or perhaps just let people set $TZ?
 
 
572
    assert isinstance(t, float)
 
 
574
    if timezone == 'utc':
 
 
577
    elif timezone == 'original':
 
 
580
        tt = time.gmtime(t + offset)
 
 
581
    elif timezone == 'local':
 
 
582
        tt = time.localtime(t)
 
 
583
        offset = local_time_offset(t)
 
 
585
        raise BzrError("unsupported timezone format %r" % timezone,
 
 
586
                       ['options are "utc", "original", "local"'])
 
 
588
        date_fmt = "%a %Y-%m-%d %H:%M:%S"
 
 
590
        offset_str = ' %+03d%02d' % (offset / 3600, (offset / 60) % 60)
 
 
593
    return (time.strftime(date_fmt, tt) +  offset_str)
 
 
596
def compact_date(when):
 
 
597
    return time.strftime('%Y%m%d%H%M%S', time.gmtime(when))
 
 
602
    """Return size of given open file."""
 
 
603
    return os.fstat(f.fileno())[ST_SIZE]
 
 
606
# Define rand_bytes based on platform.
 
 
608
    # Python 2.4 and later have os.urandom,
 
 
609
    # but it doesn't work on some arches
 
 
611
    rand_bytes = os.urandom
 
 
612
except (NotImplementedError, AttributeError):
 
 
613
    # If python doesn't have os.urandom, or it doesn't work,
 
 
614
    # then try to first pull random data from /dev/urandom
 
 
615
    if os.path.exists("/dev/urandom"):
 
 
616
        rand_bytes = file('/dev/urandom', 'rb').read
 
 
617
    # Otherwise, use this hack as a last resort
 
 
619
        # not well seeded, but better than nothing
 
 
624
                s += chr(random.randint(0, 255))
 
 
629
ALNUM = '0123456789abcdefghijklmnopqrstuvwxyz'
 
 
631
    """Return a random string of num alphanumeric characters
 
 
633
    The result only contains lowercase chars because it may be used on 
 
 
634
    case-insensitive filesystems.
 
 
637
    for raw_byte in rand_bytes(num):
 
 
638
        s += ALNUM[ord(raw_byte) % 36]
 
 
642
## TODO: We could later have path objects that remember their list
 
 
643
## decomposition (might be too tricksy though.)
 
 
646
    """Turn string into list of parts."""
 
 
647
    assert isinstance(p, basestring)
 
 
649
    # split on either delimiter because people might use either on
 
 
651
    ps = re.split(r'[\\/]', p)
 
 
656
            raise BzrError("sorry, %r not allowed in path" % f)
 
 
657
        elif (f == '.') or (f == ''):
 
 
664
    assert isinstance(p, list)
 
 
666
        if (f == '..') or (f is None) or (f == ''):
 
 
667
            raise BzrError("sorry, %r not allowed in path" % f)
 
 
671
@deprecated_function(zero_nine)
 
 
672
def appendpath(p1, p2):
 
 
676
        return pathjoin(p1, p2)
 
 
680
    """Split s into lines, but without removing the newline characters."""
 
 
681
    lines = s.split('\n')
 
 
682
    result = [line + '\n' for line in lines[:-1]]
 
 
684
        result.append(lines[-1])
 
 
688
def hardlinks_good():
 
 
689
    return sys.platform not in ('win32', 'cygwin', 'darwin')
 
 
692
def link_or_copy(src, dest):
 
 
693
    """Hardlink a file, or copy it if it can't be hardlinked."""
 
 
694
    if not hardlinks_good():
 
 
695
        shutil.copyfile(src, dest)
 
 
699
    except (OSError, IOError), e:
 
 
700
        if e.errno != errno.EXDEV:
 
 
702
        shutil.copyfile(src, dest)
 
 
704
def delete_any(full_path):
 
 
705
    """Delete a file or directory."""
 
 
709
    # We may be renaming a dangling inventory id
 
 
710
        if e.errno not in (errno.EISDIR, errno.EACCES, errno.EPERM):
 
 
716
    if getattr(os, 'symlink', None) is not None:
 
 
722
def contains_whitespace(s):
 
 
723
    """True if there are any whitespace characters in s."""
 
 
724
    for ch in string.whitespace:
 
 
731
def contains_linebreaks(s):
 
 
732
    """True if there is any vertical whitespace in s."""
 
 
740
def relpath(base, path):
 
 
741
    """Return path relative to base, or raise exception.
 
 
743
    The path may be either an absolute path or a path relative to the
 
 
744
    current working directory.
 
 
746
    os.path.commonprefix (python2.4) has a bad bug that it works just
 
 
747
    on string prefixes, assuming that '/u' is a prefix of '/u2'.  This
 
 
751
    assert len(base) >= MIN_ABS_PATHLENGTH, ('Length of base must be equal or'
 
 
752
        ' exceed the platform minimum length (which is %d)' % 
 
 
759
    while len(head) >= len(base):
 
 
762
        head, tail = os.path.split(head)
 
 
766
        raise PathNotChild(rp, base)
 
 
774
def safe_unicode(unicode_or_utf8_string):
 
 
775
    """Coerce unicode_or_utf8_string into unicode.
 
 
777
    If it is unicode, it is returned.
 
 
778
    Otherwise it is decoded from utf-8. If a decoding error
 
 
779
    occurs, it is wrapped as a If the decoding fails, the exception is wrapped 
 
 
780
    as a BzrBadParameter exception.
 
 
782
    if isinstance(unicode_or_utf8_string, unicode):
 
 
783
        return unicode_or_utf8_string
 
 
785
        return unicode_or_utf8_string.decode('utf8')
 
 
786
    except UnicodeDecodeError:
 
 
787
        raise BzrBadParameterNotUnicode(unicode_or_utf8_string)
 
 
790
_platform_normalizes_filenames = False
 
 
791
if sys.platform == 'darwin':
 
 
792
    _platform_normalizes_filenames = True
 
 
795
def normalizes_filenames():
 
 
796
    """Return True if this platform normalizes unicode filenames.
 
 
798
    Mac OSX does, Windows/Linux do not.
 
 
800
    return _platform_normalizes_filenames
 
 
803
def _accessible_normalized_filename(path):
 
 
804
    """Get the unicode normalized path, and if you can access the file.
 
 
806
    On platforms where the system normalizes filenames (Mac OSX),
 
 
807
    you can access a file by any path which will normalize correctly.
 
 
808
    On platforms where the system does not normalize filenames 
 
 
809
    (Windows, Linux), you have to access a file by its exact path.
 
 
811
    Internally, bzr only supports NFC/NFKC normalization, since that is 
 
 
812
    the standard for XML documents.
 
 
814
    So return the normalized path, and a flag indicating if the file
 
 
815
    can be accessed by that path.
 
 
818
    return unicodedata.normalize('NFKC', unicode(path)), True
 
 
821
def _inaccessible_normalized_filename(path):
 
 
822
    __doc__ = _accessible_normalized_filename.__doc__
 
 
824
    normalized = unicodedata.normalize('NFKC', unicode(path))
 
 
825
    return normalized, normalized == path
 
 
828
if _platform_normalizes_filenames:
 
 
829
    normalized_filename = _accessible_normalized_filename
 
 
831
    normalized_filename = _inaccessible_normalized_filename
 
 
834
def terminal_width():
 
 
835
    """Return estimated terminal width."""
 
 
836
    if sys.platform == 'win32':
 
 
837
        import bzrlib.win32console
 
 
838
        return bzrlib.win32console.get_console_size()[0]
 
 
841
        import struct, fcntl, termios
 
 
842
        s = struct.pack('HHHH', 0, 0, 0, 0)
 
 
843
        x = fcntl.ioctl(1, termios.TIOCGWINSZ, s)
 
 
844
        width = struct.unpack('HHHH', x)[1]
 
 
849
            width = int(os.environ['COLUMNS'])
 
 
858
def supports_executable():
 
 
859
    return sys.platform != "win32"
 
 
862
def set_or_unset_env(env_variable, value):
 
 
863
    """Modify the environment, setting or removing the env_variable.
 
 
865
    :param env_variable: The environment variable in question
 
 
866
    :param value: The value to set the environment to. If None, then
 
 
867
        the variable will be removed.
 
 
868
    :return: The original value of the environment variable.
 
 
870
    orig_val = os.environ.get(env_variable)
 
 
872
        if orig_val is not None:
 
 
873
            del os.environ[env_variable]
 
 
875
        if isinstance(value, unicode):
 
 
876
            value = value.encode(bzrlib.user_encoding)
 
 
877
        os.environ[env_variable] = value
 
 
881
_validWin32PathRE = re.compile(r'^([A-Za-z]:[/\\])?[^:<>*"?\|]*$')
 
 
884
def check_legal_path(path):
 
 
885
    """Check whether the supplied path is legal.  
 
 
886
    This is only required on Windows, so we don't test on other platforms
 
 
889
    if sys.platform != "win32":
 
 
891
    if _validWin32PathRE.match(path) is None:
 
 
892
        raise IllegalPath(path)
 
 
895
def walkdirs(top, prefix=""):
 
 
896
    """Yield data about all the directories in a tree.
 
 
898
    This yields all the data about the contents of a directory at a time.
 
 
899
    After each directory has been yielded, if the caller has mutated the list
 
 
900
    to exclude some directories, they are then not descended into.
 
 
902
    The data yielded is of the form:
 
 
903
    ((directory-relpath, directory-path-from-top),
 
 
904
    [(relpath, basename, kind, lstat), ...]),
 
 
905
     - directory-relpath is the relative path of the directory being returned
 
 
906
       with respect to top. prefix is prepended to this.
 
 
907
     - directory-path-from-root is the path including top for this directory. 
 
 
908
       It is suitable for use with os functions.
 
 
909
     - relpath is the relative path within the subtree being walked.
 
 
910
     - basename is the basename of the path
 
 
911
     - kind is the kind of the file now. If unknown then the file is not
 
 
912
       present within the tree - but it may be recorded as versioned. See
 
 
914
     - lstat is the stat data *if* the file was statted.
 
 
915
     - planned, not implemented: 
 
 
916
       path_from_tree_root is the path from the root of the tree.
 
 
918
    :param prefix: Prefix the relpaths that are yielded with 'prefix'. This 
 
 
919
        allows one to walk a subtree but get paths that are relative to a tree
 
 
921
    :return: an iterator over the dirs.
 
 
923
    #TODO there is a bit of a smell where the results of the directory-
 
 
924
    # summary in this, and the path from the root, may not agree 
 
 
925
    # depending on top and prefix - i.e. ./foo and foo as a pair leads to
 
 
926
    # potentially confusing output. We should make this more robust - but
 
 
927
    # not at a speed cost. RBC 20060731
 
 
930
    _directory = _directory_kind
 
 
931
    _listdir = os.listdir
 
 
932
    pending = [(prefix, "", _directory, None, top)]
 
 
935
        currentdir = pending.pop()
 
 
936
        # 0 - relpath, 1- basename, 2- kind, 3- stat, 4-toppath
 
 
939
            relroot = currentdir[0] + '/'
 
 
942
        for name in sorted(_listdir(top)):
 
 
943
            abspath = top + '/' + name
 
 
944
            statvalue = lstat(abspath)
 
 
945
            dirblock.append((relroot + name, name,
 
 
946
                file_kind_from_stat_mode(statvalue.st_mode),
 
 
948
        yield (currentdir[0], top), dirblock
 
 
949
        # push the user specified dirs from dirblock
 
 
950
        for dir in reversed(dirblock):
 
 
951
            if dir[2] == _directory:
 
 
955
def copy_tree(from_path, to_path, handlers={}):
 
 
956
    """Copy all of the entries in from_path into to_path.
 
 
958
    :param from_path: The base directory to copy. 
 
 
959
    :param to_path: The target directory. If it does not exist, it will
 
 
961
    :param handlers: A dictionary of functions, which takes a source and
 
 
962
        destinations for files, directories, etc.
 
 
963
        It is keyed on the file kind, such as 'directory', 'symlink', or 'file'
 
 
964
        'file', 'directory', and 'symlink' should always exist.
 
 
965
        If they are missing, they will be replaced with 'os.mkdir()',
 
 
966
        'os.readlink() + os.symlink()', and 'shutil.copy2()', respectively.
 
 
968
    # Now, just copy the existing cached tree to the new location
 
 
969
    # We use a cheap trick here.
 
 
970
    # Absolute paths are prefixed with the first parameter
 
 
971
    # relative paths are prefixed with the second.
 
 
972
    # So we can get both the source and target returned
 
 
973
    # without any extra work.
 
 
975
    def copy_dir(source, dest):
 
 
978
    def copy_link(source, dest):
 
 
979
        """Copy the contents of a symlink"""
 
 
980
        link_to = os.readlink(source)
 
 
981
        os.symlink(link_to, dest)
 
 
983
    real_handlers = {'file':shutil.copy2,
 
 
985
                     'directory':copy_dir,
 
 
987
    real_handlers.update(handlers)
 
 
989
    if not os.path.exists(to_path):
 
 
990
        real_handlers['directory'](from_path, to_path)
 
 
992
    for dir_info, entries in walkdirs(from_path, prefix=to_path):
 
 
993
        for relpath, name, kind, st, abspath in entries:
 
 
994
            real_handlers[kind](abspath, relpath)
 
 
997
def path_prefix_key(path):
 
 
998
    """Generate a prefix-order path key for path.
 
 
1000
    This can be used to sort paths in the same way that walkdirs does.
 
 
1002
    return (dirname(path) , path)
 
 
1005
def compare_paths_prefix_order(path_a, path_b):
 
 
1006
    """Compare path_a and path_b to generate the same order walkdirs uses."""
 
 
1007
    key_a = path_prefix_key(path_a)
 
 
1008
    key_b = path_prefix_key(path_b)
 
 
1009
    return cmp(key_a, key_b)
 
 
1012
_cached_user_encoding = None
 
 
1015
def get_user_encoding():
 
 
1016
    """Find out what the preferred user encoding is.
 
 
1018
    This is generally the encoding that is used for command line parameters
 
 
1019
    and file contents. This may be different from the terminal encoding
 
 
1020
    or the filesystem encoding.
 
 
1022
    :return: A string defining the preferred user encoding
 
 
1024
    global _cached_user_encoding
 
 
1025
    if _cached_user_encoding is not None:
 
 
1026
        return _cached_user_encoding
 
 
1028
    if sys.platform == 'darwin':
 
 
1029
        # work around egregious python 2.4 bug
 
 
1030
        sys.platform = 'posix'
 
 
1034
            sys.platform = 'darwin'
 
 
1039
        _cached_user_encoding = locale.getpreferredencoding()
 
 
1040
    except locale.Error, e:
 
 
1041
        sys.stderr.write('bzr: warning: %s\n'
 
 
1042
                         '  Could not what text encoding to use.\n'
 
 
1043
                         '  This error usually means your Python interpreter\n'
 
 
1044
                         '  doesn\'t support the locale set by $LANG (%s)\n'
 
 
1045
                         "  Continuing with ascii encoding.\n"
 
 
1046
                         % (e, os.environ.get('LANG')))
 
 
1048
    if _cached_user_encoding is None:
 
 
1049
        _cached_user_encoding = 'ascii'
 
 
1050
    return _cached_user_encoding