1.3. archive

This module provides a generic means to combine data and files into a single archive file.

1.3.1. Functions

is_archive(file_path)

Check if the specified file appears to be a valid archive file that can be opened with ArchiveFile.

Parameters:file_path (str) – The path to the file to check. Returns:Whether or not the file looks like a compatible archive. Return type:bool

patch_zipfile(input_file, patches, output_file=None)

Patch content into the specified input Zip file. The input_file must be either an input path string to the file to patch or a zipfile.ZipFile instance. Patch data is supplied in the patch argument which is a dictionary keyed by the paths to modify, values are then used in place of the specified path. If the value of a path is None, then that file is removed from the archive. The output_file is either a string to the path of where to place the patched archive, a ZipFile instance or None. If None is specified then input_file is modified in place.

Note

If a ZipFile instance is specified as input_file then output_file can not be None.

Parameters:

• input_file (str, ZipFile) – The Zip file archive to modify.
• patches (dict) – The data to modify from the original archive.
• output_file (None, str, ZipFile) – The destination of the modified archive

1.3.2. Classes

class ArchiveFile(file_name, mode, encoding='utf-8')

An object representing a generic archive for storing information. The resulting archive file is a tarfile that can easily be opened and manipulated with external tools. This class also facilitates storing metadata with the archive. This metadata contains basic information such as the version of King Phisher that generated it, and a UTC timestamp of when it was created.

__init__(file_name, mode, encoding='utf-8')

Parameters:

• file_name (str) – The path to the file to open as an archive.
• mode (str) – The mode to open the file such as ‘r’ or ‘w’.
• encoding (str) – The encoding to use for strings.

add_data(name, data)

Add arbitrary data directly to the archive under the specified name. This allows data to be directly inserted into the archive without first writing it to a file or file like object.

Parameters:

• name (str) – The name of the destination file in the archive.
• data (bytes, str) – The data to place into the archive.

add_file(name, file_path, recursive=True)

Place a file or directory into the archive. If file_path is a directory, it’s contents will be added recursively if recursive is True.

Parameters:

• name (str) – The name of the destination file in the archive.
• file_path (str) – The path to the file to add to the archive.
• recursive (bool) – Whether or not to add directory contents.

close()

Close the handle to the archive.

file_names

This property is a generator which yields the names of all of the contained files. The metadata file is skipped.

Returns:A generator which yields all the contained file names. Return type:str

files

This property is a generator which yields tuples of two objects each where the first is the file name and the second is the file object. The metadata file is skipped.

Returns:A generator which yields all the contained file name and file objects. Return type:tuple

get_data(name)

Return the data contained within the specified archive file.

Parameters:name (str) – The name of the source file in the archive. Returns:The contents of the specified file. Return type:bytes

get_file(name)

Return the specified file object from the archive.

Parameters:name (str) – The name of the source file in the archive. Returns:The specified file. Return type:file

get_json(name)

Extract the specified file, deserialize it as JSON encoded content and return the result.

New in version 1.14.0.

Parameters:name (str) – The name of the source file in the archive. Returns:The deserialized contents of the specified file.

has_file(name)

Check if a file exists within archive.

Parameters:name (str) – Returns:Whether or not the file exists. Return type:bool

metadata_file_name = 'metadata.json'

mode

A read-only attribute representing the mode that the archive file was opened in.