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

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

Variables
| norm_read = `deprecated("use \"open(path, 'U').read()\"")(norm_`...``
| norm_open = `deprecated("use \"open(path, 'U')\"")(norm_open)`

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`

### 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

Variables Details

### norm_read

Value:

      deprecated("use \"open(path, 'U').read()\"")(norm_read)