Package logilab :: Package common :: Module fileutils
[show private | hide private]
[frames | no frames]

Module logilab.common.fileutils

Some file / file path manipulation utilities.

:version:   $Revision: 1.27 $  
:author:    Logilab
:copyright: 2003-2005 LOGILAB S.A. (Paris, FRANCE)
:contact:   http://www.logilab.fr/ -- mailto:python-projects@logilab.org

:group path manipulation: first_level_directory, relative_path, is_binary,files_by_ext, include_files_by_ext, exclude_files_by_ext, get_by_ext
:group file manipulation: norm_read, norm_open, lines, stream_lines, lines,write_open_mode, ensure_fs_mode, export
:sort: path manipulation, file manipulation



:type BASE_BLACKLIST: tuple
:var BASE_BLACKLIST:
  list files or directories ignored by default by the `export` function

:type IGNORED_EXTENSIONS: tuple
:var IGNORED_EXTENSIONS:
  list file extensions ignored by default by the `export` function

Classes
ProtectedFile a special file-object class that automatically that automatically does a 'chmod +w' when needed XXX: for now, the way it is done allows 'normal file-objects' to be created during the ProtectedFile object lifetime.

Exceptions
UnresolvableError exception raised by relative path when it's unable to compute relative...

Function Summary
  ensure_fs_mode(filepath, desired_mode)
check that the given file has the given mode(s) set, else try to set it :type filepath: str :param filepath: path of the file :type desired_mode: int :param desired_mode: ORed flags describing the desired mode.
  ensure_mode(filepath, desired_mode)
check that the given file has the given mode(s) set, else try to set it :type filepath: str :param filepath: path of the file :type desired_mode: int :param desired_mode: ORed flags describing the desired mode.
  exclude_files_by_ext(directory, exclude_exts, exclude_dirs)
return a list of files in a directory not matching some extensions...
  export(from_dir, to_dir, blacklist, ignore_ext, verbose)
make a mirror of `from_dir` in `to_dir`, omitting directories and...
  files_by_ext(directory, include_exts, exclude_exts, exclude_dirs)
return a list of files in a directory matching (or not) some extensions: you should either give the `include_exts` argument (and only files ending with one of the listed extensions will be considered) or the `exclude_exts` argument (and only files not ending by one of the listed extensions will be considered).
  first_level_directory(path)
return the first level directory of a path...
  get_by_ext(*args, **kwargs)
deprecated, use `files_by_ext` instead...
  get_mode(*args, **kwargs)
deprecated, use `files_by_ext` instead...
  include_files_by_ext(directory, include_exts, exclude_dirs)
return a list of files in a directory matching some extensions...
  is_binary(filename)
return true if filename may be a binary file, according to it's...
  lines(path, comments)
return a list of non empty lines in the file located at `path`...
  norm_open(path)
return a stream for a file with content with normalized line feeds...
  norm_read(path)
return the content of the file with normalized line feeds...
  relative_path(from_file, to_file)
try to get a relative path from from `from_file` to `to_file` (path will be absolute if to_file is an absolute file).
  stream_lines(stream, comments)
return a list of non empty lines in the given `stream`...
  write_open_mode(filename)
return the write mode that should used to open file...

Variable Summary
str __revision__ = '$Id: fileutils.py,v 1.27 2005/11/22 13:1...
tuple BASE_BLACKLIST = ('CVS', '.svn', 'debian', 'dist', 'buil...
tuple IGNORED_EXTENSIONS = ('.pyc', '.pyo', '.elc', '~')
bool _HAS_UNIV_OPEN = True

Function Details

ensure_fs_mode(filepath, desired_mode)

check that the given file has the given mode(s) set, else try to
set it

:type filepath: str
:param filepath: path of the file

:type desired_mode: int
:param desired_mode:
  ORed flags describing the desired mode. Use constants from the
  `stat` module for file permission's modes

ensure_mode(filepath, desired_mode)

check that the given file has the given mode(s) set, else try to
set it

:type filepath: str
:param filepath: path of the file

:type desired_mode: int
:param desired_mode:
  ORed flags describing the desired mode. Use constants from the
  `stat` module for file permission's modes

exclude_files_by_ext(directory, exclude_exts, exclude_dirs=('CVS', '.svn'))

return a list of files in a directory not matching some extensions

:type directory: str
:param directory: directory where files should be searched

:type exclude_exts: list or tuple or None
:param exclude_exts: list of file extensions to ignore

:type exclude_dirs: list or tuple or None
:param exclude_dirs: list of directory where we should not recurse

:rtype: list
:return: the list of files matching input criteria

export(from_dir, to_dir, blacklist=('CVS', '.svn', 'debian', 'dist', 'build', '__buildlog'), ignore_ext=('.pyc', '.pyo', '.elc', '~'), verbose=0)

make a mirror of `from_dir` in `to_dir`, omitting directories and
files listed in the black list or ending with one of the given
extensions

:type from_dir: str
:param from_dir: directory to export

:type to_dir: str
:param to_dir: destination directory

:type blacklist: list or tuple
:param blacklist:
  list of files or directories to ignore, default to the content of
  `BASE_BLACKLIST`

:type ignore_ext: list or tuple
:param ignore_ext:
  list of extensions to ignore, default to  the content of
  `IGNORED_EXTENSIONS`

:type verbose: bool
:param verbose:
  flag indicating wether information about exported files should be
  printed to stderr, default to True

files_by_ext(directory, include_exts=None, exclude_exts=None, exclude_dirs=('CVS', '.svn'))

return a list of files in a directory matching (or not) some
extensions: you should either give the `include_exts` argument (and
only files ending with one of the listed extensions will be
considered) or the `exclude_exts` argument (and only files not
ending by one of the listed extensions will be considered).
Subdirectories are processed recursivly.

:type directory: str
:param directory: directory where files should be searched

:type include_exts: list or tuple or None
:param include_exts: list of file extensions to consider

:type exclude_exts: list or tuple or None
:param exclude_exts: list of file extensions to ignore

:type exclude_dirs: list or tuple or None
:param exclude_dirs: list of directory where we should not recurse

:rtype: list
:return: the list of files matching input criteria

first_level_directory(path)

return the first level directory of a path

>>> first_level_directory('home/syt/work')
'home'
>>> first_level_directory('/home/syt/work')
'/'
>>> first_level_directory('work')
'work'
>>>

:type path: str
:param path: the path for which we want the first level directory

:rtype: str
:return: the first level directory appearing in `path`

get_by_ext(*args, **kwargs)

deprecated, use `files_by_ext` instead

get_mode(*args, **kwargs)

deprecated, use `files_by_ext` instead

include_files_by_ext(directory, include_exts, exclude_dirs=('CVS', '.svn'))

return a list of files in a directory matching some extensions

:type directory: str
:param directory: directory where files should be searched

:type include_exts: list or tuple or None
:param include_exts: list of file extensions to consider

:type exclude_dirs: list or tuple or None
:param exclude_dirs: list of directory where we should not recurse

:rtype: list
:return: the list of files matching input criteria

is_binary(filename)

return true if filename may be a binary file, according to it's
extension

:type filename: str
:param filename: the name of the file

:rtype: bool
:return:
  true if the file is a binary file (actually if it's mime type
  isn't begining by text/)

lines(path, comments=None)

return a list of non empty lines in the file located at `path`

:type path: str
:param path: path to the file

:type comments: str or None
:param comments:
  optional string which can be used to comment a line in the file
  (ie lines starting with this string won't be returned)

:rtype: list
:return:
  a list of stripped line in the file, without empty and commented
  lines

:warning: at some point this function will probably return an iterator

norm_open(path)

return a stream for a file with content with normalized line feeds

:type path: str
:param path: path to the file to open

:rtype: file or StringIO
:return: the opened file with normalized line feeds

norm_read(path)

return the content of the file with normalized line feeds

:type path: str
:param path: path to the file to read

:rtype: str
:return: the content of the file with normalized line feeds

relative_path(from_file, to_file)

try to get a relative path from from `from_file` to `to_file`
(path will be absolute if to_file is an absolute file). This function
is useful to create link in `from_file` to `to_file`. This typical use
case is used in this function description.

If both files are relative, they're expected to be relative to the same
directory.

>>> relative_path( from_file='toto/index.html', to_file='index.html')
'../index.html'
>>> relative_path( from_file='index.html', to_file='toto/index.html')
'toto/index.html'
>>> relative_path( from_file='tutu/index.html', to_file='toto/index.html')
'../toto/index.html'
>>> relative_path( from_file='toto/index.html', to_file='/index.html')
'/index.html'
>>> relative_path( from_file='/toto/index.html', to_file='/index.html')
'../index.html'
>>> relative_path( from_file='/toto/index.html', to_file='/toto/summary.html')
'summary.html'
>>> relative_path( from_file='index.html', to_file='index.html')
''
>>> relative_path( from_file='/index.html', to_file='toto/index.html')
Traceback (most recent call last):
  File "<string>", line 1, in ?
  File "<stdin>", line 37, in relative_path
UnresolvableError
>>> relative_path( from_file='/index.html', to_file='/index.html')
''
>>>

:type from_file: str
:param from_file: source file (where links will be inserted)

:type to_file: str
:param to_file: target file (on which links point)

:raise UnresolvableError: if it has been unable to guess a correct path

:rtype: str
:return: the relative path of `to_file` from `from_file`

stream_lines(stream, comments=None)

return a list of non empty lines in the given `stream`

:type stream: object implementing 'xreadlines' or 'readlines'
:param stream: file like object

:type comments: str or None
:param comments:
  optional string which can be used to comment a line in the file
  (ie lines starting with this string won't be returned)

:rtype: list
:return:
  a list of stripped line in the file, without empty and commented
  lines

:warning: at some point this function will probably return an iterator

write_open_mode(filename)

return the write mode that should used to open file

:type filename: str
:param filename: the name of the file

:rtype: str
:return: the mode that should be use to open the file ('w' or 'wb')

Variable Details

__revision__

Type:
str
Value:
'$Id: fileutils.py,v 1.27 2005/11/22 13:13:01 syt Exp $'               

BASE_BLACKLIST

Type:
tuple
Value:
('CVS', '.svn', 'debian', 'dist', 'build', '__buildlog')               

IGNORED_EXTENSIONS

Type:
tuple
Value:
('.pyc', '.pyo', '.elc', '~')                                          

_HAS_UNIV_OPEN

Type:
bool
Value:
True                                                                   

Generated by Epydoc 2.1 on Fri Jan 6 10:52:59 2006 http://epydoc.sf.net