Module files

File utilities.

If a file descriptor is given for the parameter file it will be closed after reading from/writing to the file.

For a list of supported encodings see Standard Encodings in module codecs. The default encoding is platform dependant.

For a list of error handlers see Error Handlers in module codecs. The default error handler is 'strict'.

Overview

append_all

Append the content to a file.

append_lines

Append the lines to a file.

copyfile

Copy a file.

on_same_dev

Return True if both files are on the same device/partition.

read_all

Read and return the content of the file.

read_lines

Read and return the content of the file as a list of lines.

touch

Change file timestamps.

write_all

Write the content to a file.

write_lines

Write the lines to a file.
salmagundi.files.append_all(file, content, binary=False, encoding=None, errors=None)[source]

Append the content to a file.

Parameters

  • file (path-like object or int) – path to file or file descriptor

  • content (bytes or str) – file content

  • binary (bool) – if True the content must be bytes else str

  • encoding (str) – name of the encoding (ignored if binary=True)

  • errors (str) – error handler (ignored if binary=True)

Returns

number of bytes or characters written

Return type

int

Raises

OSError – on I/O failure

Changed in version 0.6.0: Add parameter errors

salmagundi.files.append_lines(file, lines, encoding=None, errors=None)[source]

Append the lines to a file.

Parameters

  • file (path-like object or int) – path to file or file descriptor

  • lines (list(str)) – list of strings w/o newline

  • encoding (str) – name of the encoding

  • errors (str) – error handler

Returns

number of characters written

Return type

int

Raises

OSError – on I/O failure

Changed in version 0.6.0: Add parameter errors

salmagundi.files.copyfile(src, dst, callback, cancel_evt)[source]

Copy a file.

The progess of a long running copy process can be monitored and the process can be cancelled.

The callback must be a callable that takes two parameters:

  • number of the copied bytes

  • size of the source file

def cb(i, t):
    print('\r%d / %d (%.1f%%)' % (i, t, i / t * 100),
          end='', flush=True)

evt = threading.Event()
print('Start', end='', flush=True)
try:
    copyfile('/path/to/source/file',
             '/path/to/destination/file',
             cb, evt)
    print()
except KeyboardInterrupt:
    evt.set()
    print('\rAbbruch                           \n')
Parameters
Raises

OSError – if the file could not be copied

New in version 0.5.0.

salmagundi.files.on_same_dev(file1, file2)[source]

Return True if both files are on the same device/partition.

file1, file2 may also refer to directories.

Parameters
Returns

True if both files are on the same device/partition

Return type

bool

salmagundi.files.read_all(file, binary=False, encoding=None, errors=None)[source]

Read and return the content of the file.

Parameters

  • file (path-like object or int) – path to file or file descriptor

  • binary (bool) – if True the content will be returned as bytes else as str

  • encoding (str) – name of the encoding (ignored if binary=True)

  • errors (str) – error handler (ignored if binary=True)

Returns

the file content

Return type

bytes or str

Raises

OSError – on I/O failure

Changed in version 0.6.0: Add parameter errors

salmagundi.files.read_lines(file, predicate=None, encoding=None, errors=None)[source]

Read and return the content of the file as a list of lines.

Line breaks are not included in the resulting list.

If predicate is given, it must be a callable that takes a single line as its argument and returns a bool. Only the lines for which True is returned are included in the result.

Parameters

  • file (path-like object or int) – path to file or file descriptor

  • predicate (callable(str)) – predicate function

  • encoding (str) – name of the encoding

  • errors (str) – error handler

Returns

list of lines

Return type

list(str)

Raises

OSError – on I/O failure

Changed in version 0.6.0: Add parameter errors

salmagundi.files.touch(filepath, new_time=None, atime=True, mtime=True, create=True)[source]

Change file timestamps.

The new_time parameter may be:

None

the current time will be used

int or float

seconds since the epoch

datetime

from module datetime

struct_time

from module time

path-like object

path to a file which timestamps should be used
Parameters

  • filepath (path-like object) – the file for which the timestamps should be changed

  • new_time – the new time (see above for more details)

  • atime (bool) – if True change access time

  • mtime (bool) – if True change modification time

  • create (bool) – if True an empty file will be created if it does not exist

Raises

  • FileNotFoundError – if filepath does not exist and create=False or the reference file for new_time does not exist

  • TypeError – if new_time is of wrong type

New in version 0.5.0.

salmagundi.files.write_all(file, content, binary=False, encoding=None, errors=None)[source]

Write the content to a file.

Parameters

  • file (path-like object or int) – path to file or file descriptor

  • content (bytes or str) – file content

  • binary (bool) – if True the content must be bytes else str

  • encoding (str) – name of the encoding (ignored if binary=True)

  • errors (str) – error handler (ignored if binary=True)

Returns

number of bytes or characters written

Return type

int

Raises

OSError – on I/O failure

Changed in version 0.6.0: Add parameter errors

salmagundi.files.write_lines(file, lines, encoding=None, errors=None)[source]

Write the lines to a file.

Parameters

  • file (path-like object or int) – path to file or file descriptor

  • lines (list(str)) – list of strings w/o newline

  • encoding (str) – name of the encoding

  • errors (str) – error handler

Returns

number of characters written

Return type

int

Raises

OSError – on I/O failure

Changed in version 0.6.0: Add parameter errors