Module utils

Convert the given filename into a name that should work on all platform. Remove non us-ascii characters, and drop invalid filename. Use the alternative filename if needed.

Parameters:

• filename (unicode or None) - the originale filename or None. Can be unicode.
• alt_name (str) - the alternative filename if filename is None or useless
• alt_ext (str) - the alternative filename extension (including the '.')

Returns: str

a valid filename.

>>> sanitize_filename('document.txt', 'file', '.txt')
'document.txt'
>>> sanitize_filename('number1.txt', 'file', '.txt')
'number1.txt'
>>> sanitize_filename(None, 'file', '.txt')
'file.txt'
>>> sanitize_filename(u'R\xe9pertoir.txt', 'file', '.txt')
'Rpertoir.txt'
>>> # the '\xe9' has been removed
>>> sanitize_filename(u'\xe9\xe6.html', 'file', '.txt')
'file.html'
>>> # all non us-ascii characters have been removed, the alternative name
>>> # has been used the replace empty string. The originale extention
>>> # is still valid  
>>> sanitize_filename(u'COM1.txt', 'file', '.txt')
'COM1A.txt'
>>> # if name match an invalid name or assimilated then a A is added

Avoid filename collision, add a sequence number to the name when required. 'file.txt' will be renamed into 'file-01.txt' then 'file-02.txt' ... until their is no more collision. The file is not added to the list.

Windows don't make the difference between lower and upper case. To avoid "case" collision, the function compare filename.lower() to the list. If you provide a list in lower case only, then any collisions will be avoided.

Parameters:

• filename (str) - the filename
• filenames (list or set) - a list of filenames.

Returns: str

the filename or the appropriately indexed filename

>>> handle_filename_collision('file.txt', [ ])
'file.txt'
>>> handle_filename_collision('file.txt', [ 'file.txt' ])
'file-01.txt'
>>> handle_filename_collision('file.txt', [ 'file.txt', 'file-01.txt',])
'file-02.txt'
>>> handle_filename_collision('foo', [ 'foo',])
'foo-01'
>>> handle_filename_collision('foo', [ 'foo', 'foo-01',])
'foo-02'
>>> handle_filename_collision('FOO', [ 'foo', 'foo-01',])
'FOO-02'

" test if string contains us-ascii characters only

>>> is_usascii('foo')
True
>>> is_usascii(u'foo')
True
>>> is_usascii(u'Français')
False
>>> is_usascii('bad')
False

invalid_chars_in_filename

Value:

'''\x00\x01\x02\x03\x04\x05\x06\x07\x08\t \x0b\x0c\r\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c \x1d\x1e\x1f<>:"/\\|?*\\%\''''

invalid_windows_name

Value:

['CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4', ...