file #

file provides functions to interact with the file system. The library is inspired by file helpers from Amoy.

Functions #

trim_bom(rd) string #

Removes the Byte Order Mark (BOM) from a byte literal string or bytes.

Parameters #

Examples #

basic

Removes the Byte Order Mark (BOM) from a string.

load("file", "trim_bom")
s = b'\xef\xbb\xbfhello'
print(trim_bom(s))
# Output: hello

count_lines(name) int #

Counts the total lines in a file located at the provided path.

Parameters #

Examples #

basic

Count the lines of a file.

load("file", "count_lines")
name = 'path/to/file.txt'
print(count_lines(name))
# Output: 10

head_lines(name, n) []string #

Returns the first ’n’ lines of a file.

Parameters #

Examples #

basic

Get the top 10 lines of a file.

load('file', 'head_lines')
print(head_lines('path/to/file.txt', 10))
# Output: ['line1', 'line2', ... 'line10']

tail_lines(name, n) []string #

Returns the last ’n’ lines of a file.

Parameters #

Examples #

basic

Get the bottom 10 lines of a file.

load('file', 'tail_lines')
print(tail_lines('path/to/file.txt', 10))
# Output: ['line91', 'line92', ... 'line100']

read_bytes(name) #

Reads a file and returns its contents as bytes.

Parameters #

Examples #

basic

Read a file in bytes.

load('file', 'read_bytes')
print(read_bytes('path/to/file.txt'))
# Output: b'file_content'

read_string(name) #

Reads a file and returns its contents as string.

Parameters #

Examples #

basic

Read a file in string.

load('file', 'read_string')
print(read_string('path/to/file.txt'))
# Output: 'file_content'

read_lines(name) #

Reads a file and returns its contents as a list of lines.

Parameters #

Examples #

basic

Get lines of a file in a list.

load('file', 'read_lines')
print(read_lines('path/to/file.txt'))
# Output: ['line1', 'line2', 'line3', ....]

write_bytes(name, data) #

Writes/overwrites bytes or a byte literal string to a file. If the file isn’t present, a new file would be created.

Parameters #

Examples #

basic

Write a byte string to a file.

load('file', 'write_bytes')
name = 'new_file.txt'
data = b'Hello, This is a new file.'
write_bytes(name, data)

write_string(name, data) #

Writes/overwrites a string to a file. If the file isn’t present, a new file would be created.

Parameters #

Examples #

basic

Write a string to a file.

load('file', 'write_string')
write_string('new_file.txt', 'Hello, This is a new file.')

write_lines(name, data) #

Writes/overwrites a list, tuple or set of lines to a file. If the file isn’t present, a new file would be created.

Parameters #

Examples #

List

Write a list of lines to a file.

load('file', 'write_lines')
lines = ['This is line1', 'This is line2', 'This is line3']
write_lines('new_file.txt', lines)

append_bytes(name, data) #

Appends bytes or a byte literal string to a file. If the file isn’t present, a new file would be created.

Parameters #

Examples #

basic

Append a byte string to a file.

load('file', 'append_bytes')
append_bytes('existing_file.txt', b'Hello, This is appended data.')

append_string(name, data) #

Appends a string to a file. If the file isn’t present, a new file would be created.

Parameters #

Examples #

basic

Append a string to a file.

load('file', 'append_string')
append_string('existing_file.txt', 'Hello, This is appended data.')

append_lines(name, data) #

Appends a list, tuple or set of lines to a file. If the file isn’t present, a new file would be created.

Parameters #

Examples #

basic

Append a list of lines to a file.

load('file', 'append_lines')
append_lines('existing_file.txt', ['This is line1', 'This is line2', 'This is line3'])

stat(name, follow=False) FileStat #

Returns a FileStat object representing information about the given file or directory.

Parameters #

Examples #

file information

Retrieve information about a file.

load('file', 'stat')
info = stat('path/to/file.txt')
print(info.name, info.size, info.type)
# Output: file.txt 3759 file

directory information

Retrieve information about a directory.

load('file', 'stat')
info = stat('path/to/folder', follow=True)
print(info.name, info.size, info.type)
# Output: folder 448 dir

copyfile(src, dst, overwrite=False) string #

Copies a file from source to destination, and returns the destination file path. If the destination exists and overwrite is set to False, an error is returned. If the destination is a directory, the file is copied into that directory with its original filename. Symbolic links are followed. Mode, access, and modification times are preserved.

Parameters #

Examples #

basic copy

Copy a file to a new location without overwrite.

load('file', 'copyfile')
src = 'path/to/source.txt'
dst = 'path/to/destination.txt'
copyfile(src, dst)
# The file at 'path/to/source.txt' is copied to 'path/to/destination.txt'

overwrite copy

Copy a file to a new location with overwrite enabled.

load('file', 'copyfile')
src = 'path/to/source.txt'
dst = 'path/to/existing_destination.txt'
copyfile(src, dst, overwrite=True)
# The file at 'path/to/source.txt' is copied to 'path/to/existing_destination.txt', overwriting it.

copy to directory

Copy a file into a directory.

load('file', 'copyfile')
src = 'path/to/source.txt'
dst = 'path/to/directory'
copyfile(src, dst)
# The file at 'path/to/source.txt' is copied into 'path/to/directory' with its original filename.

Types #

FileStat #

Represents information about a file.

Fields