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.2 $

Author:

Logilab

Contact:

http://www.logilab.fr/ -- mailto:python-projects@logilab.org

Copyright:

2003-2005 LOGILAB S.A. (Paris, FRANCE)

Classes
ProtectedFile a special file-object class that automatically that automatically does a 'chmod +w' when needed

Exceptions
UnresolvableError exception raised by relative path when it's unable to compute relative path between two paths

Function Summary
  ensure_mode(filepath, desired_mode)
check that the given file has the given mode(s) set, else try to set it
  get_mode(*args, **kwargs)
deprecated, use files_by_ext instead
    path manipulation

str

first_level_directory(path)
return the first level directory of a path

str

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

bool

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

list

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

list

include_files_by_ext(directory, include_exts, exclude_dirs)
return a list of files in a directory matching some extensions

list

exclude_files_by_ext(directory, exclude_exts, exclude_dirs)
return a list of files in a directory not matching some extensions
  get_by_ext(*args, **kwargs)
deprecated, use files_by_ext instead
    file manipulation

str

norm_read(path)
return the content of the file with normalized line feeds

file or StringIO

norm_open(path)
return a stream for a file with content with normalized line feeds

list

lines(path, comments)
return a list of non empty lines in the file located at path

list

stream_lines(stream, comments)
return a list of non empty lines in the given stream

str

write_open_mode(filename)
return the write mode that should used to open file
  ensure_fs_mode(filepath, desired_mode)
check that the given file has the given mode(s) set, else try to set it
  export(from_dir, to_dir, blacklist, ignore_ext, verbose)
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

Variable Summary
str __revision__ = '$Id: fileutils.py,v 1.25 2005/02/25 10:0...

tuple

BASE_BLACKLIST: list files or directories ignored by default by the export function

tuple

IGNORED_EXTENSIONS: list file extensions ignored by default by the export function
bool _HAS_UNIV_OPEN = True

Function Details

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'
>>>
Parameters:
path -

the path for which we want the first level directory


           (type=

str

)
Returns:

the first level directory appearing in path


           (type=

str

)

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')
''
>>>
Parameters:
from_file -

source file (where links will be inserted)


           (type=

str

)
to_file -

target file (on which links point)


           (type=

str

)
Returns:

the relative path of to_file from from_file


           (type=

str

)
Raises:
UnresolvableError -

if it has been unable to guess a correct path

is_binary(filename)

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

Parameters:
filename -

the name of the file


           (type=

str

)
Returns:

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


           (type=

bool

)

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.

Parameters:
directory -

directory where files should be searched


           (type=

str

)
include_exts -

list of file extensions to consider


           (type=

list or tuple or None

)
exclude_exts -

list of file extensions to ignore


           (type=

list or tuple or None

)
exclude_dirs -

list of directory where we should not recurse


           (type=

list or tuple or None

)
Returns:

the list of files matching input criteria


           (type=

list

)

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

return a list of files in a directory matching some extensions

Parameters:
directory -

directory where files should be searched


           (type=

str

)
include_exts -

list of file extensions to consider


           (type=

list or tuple or None

)
exclude_dirs -

list of directory where we should not recurse


           (type=

list or tuple or None

)
Returns:

the list of files matching input criteria


           (type=

list

)

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

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

Parameters:
directory -

directory where files should be searched


           (type=

str

)
exclude_exts -

list of file extensions to ignore


           (type=

list or tuple or None

)
exclude_dirs -

list of directory where we should not recurse


           (type=

list or tuple or None

)
Returns:

the list of files matching input criteria


           (type=

list

)

get_by_ext(*args, **kwargs)

deprecated, use files_by_ext instead

norm_read(path)

return the content of the file with normalized line feeds

Parameters:
path -

path to the file to read


           (type=

str

)
Returns:

the content of the file with normalized line feeds


           (type=

str

)

norm_open(path)

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

Parameters:
path -

path to the file to open


           (type=

str

)
Returns:

the opened file with normalized line feeds


           (type=

file or StringIO

)

lines(path, comments=None)

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

Parameters:
path -

path to the file


           (type=

str

)
comments -

optional string which can be used to comment a line in the file (ie lines starting with this string won't be returned)


           (type=

str or None

)
Returns:

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


           (type=

list

)

Warning:

at some point this function will probably return an iterator

stream_lines(stream, comments=None)

return a list of non empty lines in the given stream

Parameters:
stream -

file like object


           (type=

object implementing 'xreadlines' or 'readlines'

)
comments -

optional string which can be used to comment a line in the file (ie lines starting with this string won't be returned)


           (type=

str or None

)
Returns:

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


           (type=

list

)

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

Parameters:
filename -

the name of the file


           (type=

str

)
Returns:

the mode that should be use to open the file ('w' or 'wb')


           (type=

str

)

ensure_fs_mode(filepath, desired_mode)

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

Parameters:
filepath -

path of the file


           (type=

str

)
desired_mode -

ORed flags describing the desired mode. Use constants from the stat module for file permission's modes


           (type=

int

)

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

Parameters:
from_dir -

directory to export


           (type=

str

)
to_dir -

destination directory


           (type=

str

)
blacklist -

list of files or directories to ignore, default to the content of BASE_BLACKLIST


           (type=

list or tuple

)
ignore_ext -

list of extensions to ignore, default to the content of IGNORED_EXTENSIONS


           (type=

list or tuple

)
verbose -

flag indicating wether information about exported files should be printed to stderr, default to True


           (type=

bool

)

ensure_mode(filepath, desired_mode)

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

Parameters:
filepath -

path of the file


           (type=

str

)
desired_mode -

ORed flags describing the desired mode. Use constants from the stat module for file permission's modes


           (type=

int

)

get_mode(*args, **kwargs)

deprecated, use files_by_ext instead


Variable Details

__revision__

Type:
str
Value:
'$Id: logilab.common.fileutils-module.html,v 1.2 2005/04/19 14:39:10 fabioz Exp $'              

BASE_BLACKLIST

list files or directories ignored by default by the export function

Type:

tuple

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

IGNORED_EXTENSIONS

list file extensions ignored by default by the export function

Type:

tuple

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

_HAS_UNIV_OPEN

Type:
bool
Value:
True                                                                   

Generated by Epydoc 2.1 on Thu Apr 14 11:37:32 2005 http://epydoc.sf.net