API docs for “bzrlib.osutils”

Line #	Kind	Name	Docs
80	Function	make_readonly	Make a filename read-only.
88	Function	make_writable	Undocumented
95	Function	minimum_path_selection	Return the smallset subset of paths which are outside paths.
115	Function	quotefn	Return a quoted filename filename
133	Function	get_umask	Return the current umask
151	Function	kind_marker	Undocumented
160	Function	lexists	Undocumented
172	Function	fancy_rename	A fancy rename, when you don't have atomic rename.
384	Function	rmtree	Replacer for shutil.rmtree: could remove readonly dirs/files
391	Function	get_terminal_encoding	Find the best encoding for printing to the screen.
437	Function	normalizepath	Undocumented
449	Function	isdir	True if f is an accessible directory.
457	Function	isfile	True if f is a regular file.
464	Function	islink	True if f is a symlink.
471	Function	is_inside	True if fname is inside dir.
495	Function	is_inside_any	True if fname is inside any of given dirs.
503	Function	is_inside_or_parent_of_any	True if fname is a child or a parent of any of the given files.
511	Function	pumpfile	Copy contents of one file to another.
550	Function	pump_string_file	Write bytes to file_handle in many smaller writes.
568	Function	file_iterator	Undocumented
576	Function	sha_file	Calculate the hexdigest of an open file.
591	Function	sha_file_by_name	Calculate the SHA1 of a file by reading the full text
605	Function	sha_strings	Return the sha-1 of concatenation of strings
612	Function	sha_string	Undocumented
616	Function	fingerprint_file	Undocumented
622	Function	compare_files	Returns true if equal in contents
634	Function	local_time_offset	Return offset of local zone from GMT, either at present or at time t.
643	Function	format_date	Return a formatted date string.
661	Function	format_local_date	Return an unicode date string formatted according to the current locale.
702	Function	compact_date	Undocumented
706	Function	format_delta	Get a nice looking string for a time delta.
755	Function	filesize	Return size of given open file.
774	Function	rand_bytes	Undocumented
784	Function	rand_chars	Return a random string of num alphanumeric characters
799	Function	splitpath	Turn string into list of parts.
815	Function	joinpath	Undocumented
822	Function	split_lines	Split s into lines, but without removing the newline characters.
831	Function	hardlinks_good	Undocumented
835	Function	link_or_copy	Hardlink a file, or copy it if it can't be hardlinked.
853	Function	delete_any	Delete a file or directory.
861	Function	has_symlinks	Undocumented
868	Function	has_hardlinks	Undocumented
875	Function	host_os_dereferences_symlinks	Undocumented
880	Function	contains_whitespace	True if there are any whitespace characters in s.
900	Function	contains_linebreaks	True if there is any vertical whitespace in s.
909	Function	relpath	Return path relative to base, or raise exception.
944	Function	safe_unicode	Coerce unicode_or_utf8_string into unicode.
960	Function	safe_utf8	Coerce unicode_or_utf8_string to a utf8 string.
984	Function	safe_revision_id	Revision ids should now be utf8, but at one point they were unicode.
1005	Function	safe_file_id	File ids should now be utf8, but at one point they were unicode.
1030	Function	normalizes_filenames	Return True if this platform normalizes unicode filenames.
1069	Function	terminal_width	Return estimated terminal width.
1092	Function	supports_executable	Undocumented
1096	Function	supports_posix_readonly	Return True if 'readonly' has POSIX semantics, False otherwise.
1109	Function	set_or_unset_env	Modify the environment, setting or removing the env_variable.
1131	Function	check_legal_path	Check whether the supplied path is legal.
1170	Function	walkdirs	Yield data about all the directories in a tree.
1236	Class	DirReader	An interface for reading directories.
1321	Class	UnicodeDirReader	A dir reader for non-utf8 file systems, which transcodes.
1372	Function	copy_tree	Copy all of the entries in from_path into to_path.
1414	Function	path_prefix_key	Generate a prefix-order path key for path.
1422	Function	compare_paths_prefix_order	Compare path_a and path_b to generate the same order walkdirs uses.
1432	Function	get_user_encoding	Find out what the preferred user encoding is.
1505	Function	get_host_name	Return the current unicode host name.
1519	Function	recv_all	Receive an exact number of bytes.
1538	Function	send_all	Send all bytes on a socket.
1549	Function	dereference_path	Determine the real path to a file.
1563	Function	supports_mapi	Return True if we can use MAPI to launch a mail client.
1568	Function	resource_string	Load a resource from a package and return it as a string.
1597	Function	file_kind_from_stat_mode_thunk	Undocumented
1611	Function	file_kind	Undocumented
1621	Function	getchar 0	Undocumented
1626	Function	getchar	Undocumented
238	Function	_posix_abspath	Undocumented
246	Function	_posix_realpath	Undocumented
250	Function	_win32_fixdrive	Force drive letters to be consistent.
263	Function	_win32_abspath	Undocumented
268	Function	_win98_abspath	Return the absolute version of a path.
295	Function	_win32_realpath	Undocumented
300	Function	_win32_pathjoin	Undocumented
304	Function	_win32_normpath	Undocumented
308	Function	_win32_getcwd	Undocumented
312	Function	_win32_mkdtemp	Undocumented
316	Function	_win32_rename	We expect to be able to atomically replace 'new' with old.
334	Function	_mac_getcwd	Undocumented
371	Function	_win32_delete_readonly	Error handler for shutil.rmtree function [for win32]
680	Function	_format_date	Undocumented
1038	Function	_accessible_normalized_filename	Get the unicode normalized path, and if you can access the file.
1056	Function	_inaccessible_normalized_filename	Undocumented
1144	Function	_is_error_enotdir	Check if this exception represents ENOTDIR.
1264	Function	_walkdirs_utf8	Yield data about all the directories in a tree.

def make_readonly(filename):

Make a filename read-only.

def make_writable(filename):

Undocumented

def minimum_path_selection(paths):

Return the smallset subset of paths which are outside paths.

Parameters	paths	A container (and hence not None) of paths.
Returns	A set of paths sufficient to include everything in paths via is_inside_any, drawn from the paths parameter.

def quotefn(f):

Return a quoted filename filename

This previously used backslash quoting, but that works poorly on Windows.

def get_umask():

Return the current umask

def kind_marker(kind):

Undocumented

def lexists(f):

Undocumented

def fancy_rename(old, new, rename_func, unlink_func):

A fancy rename, when you don't have atomic rename.

Parameters	old	The old path, to rename from
	new	The new path, to rename to
	rename_func	The potentially non-atomic rename function
	unlink_func	A way to delete the target file if the full rename succeeds

def _posix_abspath(path):

Undocumented

def _posix_realpath(path):

Undocumented

def _win32_fixdrive(path):

Force drive letters to be consistent.

win32 is inconsistent whether it returns lower or upper case and even if it was consistent the user might type the other so we force it to uppercase running python.exe under cmd.exe return capital C:running win32 python inside a cygwin shell returns lowercase c:

def _win32_abspath(path):

Undocumented

def _win98_abspath(path):

Return the absolute version of a path. Windows 98 safe implementation (python reimplementation of Win32 API function GetFullPathNameW)

def _win32_realpath(path):

Undocumented

def _win32_pathjoin(*args):

Undocumented

def _win32_normpath(path):

Undocumented

def _win32_getcwd():

Undocumented

def _win32_mkdtemp(*args, **kwargs):

Undocumented

def _win32_rename(old, new):

We expect to be able to atomically replace 'new' with old.

On win32, if new exists, it must be moved out of the way first, and then deleted.

def _mac_getcwd():

Undocumented

def _win32_delete_readonly(function, path, excinfo):

Error handler for shutil.rmtree function [for win32] Helps to remove files and dirs marked as read-only.

def rmtree(path, ignore_errors=False, onerror=_win32_delete_readonly):

Replacer for shutil.rmtree: could remove readonly dirs/files

def get_terminal_encoding():

Find the best encoding for printing to the screen.

This attempts to check both sys.stdout and sys.stdin to see what encoding they are in, and if that fails it falls back to osutils.get_user_encoding(). The problem is that on Windows, locale.getpreferredencoding() is not the same encoding as that used by the console: http://mail.python.org/pipermail/python-list/2003-May/162357.html

On my standard US Windows XP, the preferred encoding is cp1252, but the console is cp437

def normalizepath(f):

Undocumented

def isdir(f):

True if f is an accessible directory.

def isfile(f):

True if f is a regular file.

def islink(f):

True if f is a symlink.

def is_inside(dir, fname):

True if fname is inside dir.

The parameters should typically be passed to osutils.normpath first, so that . and .. and repeated slashes are eliminated, and the separators are canonical for the platform.

The empty string as a dir name is taken as top-of-tree and matches everything.

def is_inside_any(dir_list, fname):

True if fname is inside any of given dirs.

def is_inside_or_parent_of_any(dir_list, fname):

True if fname is a child or a parent of any of the given files.

def pumpfile(from_file, to_file, read_length=-1, buff_size=32768):

Copy contents of one file to another.

The read_length can either be -1 to read to end-of-file (EOF) or it can specify the maximum number of bytes to read.

The buff_size represents the maximum size for each read operation performed on from_file.

Returns The number of bytes copied.

def pump_string_file(bytes, file_handle, segment_size=None):

Write bytes to file_handle in many smaller writes.

Parameters	bytes	The string to write.
	file_handle	The file to write to.

def file_iterator(input_file, readsize=32768):

Undocumented

def sha_file(f):

Calculate the hexdigest of an open file.

The file cursor should be already at the start.

def sha_file_by_name(fname):

Calculate the SHA1 of a file by reading the full text

def sha_strings(strings, _factory=sha):

Return the sha-1 of concatenation of strings

def sha_string(f, _factory=sha):

Undocumented

def fingerprint_file(f):

Undocumented

def compare_files(a, b):

Returns true if equal in contents

def local_time_offset(t=None):

Return offset of local zone from GMT, either at present or at time t.

def format_date(t, offset=0, timezone='original', date_fmt=None, show_offset=True):

Return a formatted date string.

Parameters	t	Seconds since the epoch.
	offset	Timezone offset in seconds east of utc.
	timezone	How to display the time: 'utc', 'original' for the timezone specified by offset, or 'local' for the process's current timezone.
	date_fmt	strftime format.
	show_offset	Whether to append the timezone.

def format_local_date(t, offset=0, timezone='original', date_fmt=None, show_offset=True):

Return an unicode date string formatted according to the current locale.

Parameters	t	Seconds since the epoch.
	offset	Timezone offset in seconds east of utc.
	timezone	How to display the time: 'utc', 'original' for the timezone specified by offset, or 'local' for the process's current timezone.
	date_fmt	strftime format.
	show_offset	Whether to append the timezone.

def _format_date(t, offset, timezone, date_fmt, show_offset):

Undocumented

def compact_date(when):

Undocumented

def format_delta(delta):

Get a nice looking string for a time delta.

Parameters	delta	The time difference in seconds, can be positive or negative. positive indicates time in the past, negative indicates time in the future. (usually time.time() - stored_time)
Returns	String formatted to show approximate resolution

def filesize(f):

Return size of given open file.

def rand_bytes(n):

Undocumented

def rand_chars(num):

Return a random string of num alphanumeric characters

The result only contains lowercase chars because it may be used on case-insensitive filesystems.

def splitpath(p):

Turn string into list of parts.

def joinpath(p):

Undocumented

def split_lines(s):

Split s into lines, but without removing the newline characters.

def hardlinks_good():

Undocumented

def link_or_copy(src, dest):

Hardlink a file, or copy it if it can't be hardlinked.

def delete_any(path):

Delete a file or directory.

def has_symlinks():

Undocumented

def has_hardlinks():

Undocumented

def host_os_dereferences_symlinks():

Undocumented

def contains_whitespace(s):

True if there are any whitespace characters in s.

def contains_linebreaks(s):

True if there is any vertical whitespace in s.

def relpath(base, path):

Return path relative to base, or raise exception.

The path may be either an absolute path or a path relative to the current working directory.

os.path.commonprefix (python2.4) has a bad bug that it works just on string prefixes, assuming that '/u' is a prefix of '/u2'. This avoids that problem.

def safe_unicode(unicode_or_utf8_string):

Coerce unicode_or_utf8_string into unicode.

If it is unicode, it is returned. Otherwise it is decoded from utf-8. If a decoding error occurs, it is wrapped as a If the decoding fails, the exception is wrapped as a BzrBadParameter exception.

def safe_utf8(unicode_or_utf8_string):

Coerce unicode_or_utf8_string to a utf8 string.

If it is a str, it is returned. If it is Unicode, it is encoded into a utf-8 string.

def safe_revision_id(unicode_or_utf8_string, warn=True):

Revision ids should now be utf8, but at one point they were unicode.

Parameters	unicode_or_utf8_string	A possibly Unicode revision_id. (can also be utf8 or None).
	warn	Functions that are sanitizing user data can set warn=False
Returns	None or a utf8 revision id.

def safe_file_id(unicode_or_utf8_string, warn=True):

File ids should now be utf8, but at one point they were unicode.

This is the same as safe_utf8, except it uses the cached encode functions to save a little bit of performance.

Parameters	unicode_or_utf8_string	A possibly Unicode file_id. (can also be utf8 or None).
	warn	Functions that are sanitizing user data can set warn=False
Returns	None or a utf8 file id.

def normalizes_filenames():

Return True if this platform normalizes unicode filenames.

Mac OSX does, Windows/Linux do not.

def _accessible_normalized_filename(path):

Get the unicode normalized path, and if you can access the file.

On platforms where the system normalizes filenames (Mac OSX), you can access a file by any path which will normalize correctly. On platforms where the system does not normalize filenames (Windows, Linux), you have to access a file by its exact path.

Internally, bzr only supports NFC normalization, since that is the standard for XML documents.

So return the normalized path, and a flag indicating if the file can be accessed by that path.

def _inaccessible_normalized_filename(path):

Undocumented

def terminal_width():

Return estimated terminal width.

def supports_executable():

Undocumented

def supports_posix_readonly():

Return True if 'readonly' has POSIX semantics, False otherwise.

Notably, a win32 readonly file cannot be deleted, unlike POSIX where the directory controls creation/deletion, etc.

And under win32, readonly means that the directory itself cannot be deleted. The contents of a readonly directory can be changed, unlike POSIX where files in readonly directories cannot be added, deleted or renamed.

def set_or_unset_env(env_variable, value):

Modify the environment, setting or removing the env_variable.

Parameters	env_variable	The environment variable in question
	value	The value to set the environment to. If None, then the variable will be removed.
Returns	The original value of the environment variable.

def check_legal_path(path):

Check whether the supplied path is legal. This is only required on Windows, so we don't test on other platforms right now.

def _is_error_enotdir(e):

Check if this exception represents ENOTDIR.

Unfortunately, python is very inconsistent about the exception
here. The cases are:
  1) Linux, Mac OSX all versions seem to set errno == ENOTDIR
  2) Windows, Python2.4, uses errno == ERROR_DIRECTORY (267)
     which is the windows error code.
  3) Windows, Python2.5 uses errno == EINVAL and
     winerror == ERROR_DIRECTORY

:param e: An Exception object (expected to be OSError with an errno
    attribute, but we should be able to cope with anything)
:return: True if this represents an ENOTDIR error. False otherwise.

def walkdirs(top, prefix=''):

Yield data about all the directories in a tree.

This yields all the data about the contents of a directory at a time.
After each directory has been yielded, if the caller has mutated the list
to exclude some directories, they are then not descended into.

The data yielded is of the form:
((directory-relpath, directory-path-from-top),
[(relpath, basename, kind, lstat, path-from-top), ...]),
 - directory-relpath is the relative path of the directory being returned
   with respect to top. prefix is prepended to this.
 - directory-path-from-root is the path including top for this directory. 
   It is suitable for use with os functions.
 - relpath is the relative path within the subtree being walked.
 - basename is the basename of the path
 - kind is the kind of the file now. If unknown then the file is not
   present within the tree - but it may be recorded as versioned. See
   versioned_kind.
 - lstat is the stat data *if* the file was statted.
 - planned, not implemented: 
   path_from_tree_root is the path from the root of the tree.

:param prefix: Prefix the relpaths that are yielded with 'prefix'. This 
    allows one to walk a subtree but get paths that are relative to a tree
    rooted higher up.
:return: an iterator over the dirs.

def _walkdirs_utf8(top, prefix=''):

Yield data about all the directories in a tree.

This yields the same information as walkdirs() only each entry is yielded in utf-8. On platforms which have a filesystem encoding of utf8 the paths are returned as exact byte-strings.

Returns yields a tuple of (dir_info, [file_info]) dir_info is (utf8_relpath, path-from-top) file_info is (utf8_relpath, utf8_name, kind, lstat, path-from-top) if top is an absolute path, path-from-top is also an absolute path. path-from-top might be unicode or utf8, but it is the correct path to pass to os functions to affect the file in question. (such as os.lstat)

def copy_tree(from_path, to_path, handlers={}):

Copy all of the entries in from_path into to_path.

Parameters	from_path	The base directory to copy.
	to_path	The target directory. If it does not exist, it will be created.
	handlers	A dictionary of functions, which takes a source and destinations for files, directories, etc. It is keyed on the file kind, such as 'directory', 'symlink', or 'file' 'file', 'directory', and 'symlink' should always exist. If they are missing, they will be replaced with 'os.mkdir()', 'os.readlink() + os.symlink()', and 'shutil.copy2()', respectively.

def path_prefix_key(path):

Generate a prefix-order path key for path.

This can be used to sort paths in the same way that walkdirs does.

def compare_paths_prefix_order(path_a, path_b):

Compare path_a and path_b to generate the same order walkdirs uses.

def get_user_encoding(use_cache=True):

Find out what the preferred user encoding is.

This is generally the encoding that is used for command line parameters and file contents. This may be different from the terminal encoding or the filesystem encoding.

Parameters	use_cache	Enable cache for detected encoding. (This parameter is turned on by default, and required only for selftesting)
Returns	A string defining the preferred user encoding

def get_host_name():

Return the current unicode host name.

This is meant to be used in place of socket.gethostname() because that behaves inconsistently on different platforms.

def recv_all(socket, bytes):

Receive an exact number of bytes.

Regular Socket.recv() may return less than the requested number of bytes, dependning on what's in the OS buffer. MSG_WAITALL is not available on all platforms, but this should work everywhere. This will return less than the requested amount if the remote end closes.

This isn't optimized and is intended mostly for use in testing.

def send_all(socket, bytes):

Send all bytes on a socket.

Regular socket.sendall() can give socket error 10053 on Windows. This implementation sends no more than 64k at a time, which avoids this problem.

def dereference_path(path):

Determine the real path to a file.

All parent elements are dereferenced. But the file itself is not dereferenced. :param path: The original path. May be absolute or relative. :return: the real path to the file

def supports_mapi():

Return True if we can use MAPI to launch a mail client.

def resource_string(package, resource_name):

Load a resource from a package and return it as a string.

Note: Only packages that start with bzrlib are currently supported.

This is designed to be a lightweight implementation of resource loading in a way which is API compatible with the same API from pkg_resources. See http://peak.telecommunity.com/DevCenter/PkgResources#basic-resource-access. If and when pkg_resources becomes a standard library, this routine can delegate to it.

def file_kind_from_stat_mode_thunk(mode):

Undocumented

def file_kind(f, _lstat=os.lstat):

Undocumented

def getchar 0():

Undocumented

def getchar():

Undocumented

Module b.osutils