Package logilab :: Package common :: Module fileutils
[frames] | no frames]

Module fileutils

source code

File and file-path manipulation utilities.

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

Classes
  ProtectedFile
A special file-object class that automatically that automatically does a 'chmod +w' when needed.
  UnresolvableError
Exception raised by relative path when it's unable to compute relative path between two paths.
Functions
 
first_level_directory(path)
Return the first level directory of a path.
source code
 
abspath_listdir(path)
Lists path's content using absolute paths.
source code
 
is_binary(filename)
Return true if filename may be a binary file, according to it's extension.
source code
 
write_open_mode(filename)
Return the write mode that should used to open file.
source code
 
ensure_fs_mode(filepath, desired_mode=S_IWRITE)
Check that the given file has the given mode(s) set, else try to set it.
source code
 
relative_path(from_file, to_file)
Try to get a relative path from `from_file` to `to_file` (path will be absolute if to_file is an absolute file).
source code
 
norm_read(path)
Return the content of the file with normalized line feeds.
source code
 
norm_open(path)
Return a stream for a file with content with normalized line feeds.
source code
 
lines(path, comments=None)
Return a list of non empty lines in the file located at `path`.
source code
 
stream_lines(stream, comments=None)
Return a list of non empty lines in the given `stream`.
source code
 
export(from_dir, to_dir, blacklist=BASE_BLACKLIST, ignore_ext=IGNORED_EXTENSIONS, 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.
source code
 
remove_dead_links(directory, verbose=0)
Recursively traverse directory and remove all dead links.
source code
Function Details

first_level_directory(path)

source code 
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`

abspath_listdir(path)

source code 
Lists path's content using absolute paths.

>>> os.listdir('/home')
['adim', 'alf', 'arthur', 'auc']
>>> abspath_listdir('/home')
['/home/adim', '/home/alf', '/home/arthur', '/home/auc']

is_binary(filename)

source code 
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 beginning by text/)

write_open_mode(filename)

source code 
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')

ensure_fs_mode(filepath, desired_mode=S_IWRITE)

source code 
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

relative_path(from_file, to_file)

source code 
Try to get a relative path 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`

norm_read(path)

source code 
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

norm_open(path)

source code 
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

lines(path, comments=None)

source code 
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
  (i.e. 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

stream_lines(stream, comments=None)

source code 
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
  (i.e. 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

export(from_dir, to_dir, blacklist=BASE_BLACKLIST, ignore_ext=IGNORED_EXTENSIONS, verbose=0)

source code 
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 whether information about exported files should be
  printed to stderr, default to False

remove_dead_links(directory, verbose=0)

source code 
Recursively traverse directory and remove all dead links.

:type directory: str
:param directory: directory to cleanup

:type verbose: bool
:param verbose:
  flag indicating whether information about deleted links should be
  printed to stderr, default to False