container

This module contains the following classes:

• Container is the main class, exposing functions like extracting all entries, extracting just one entry, listing the entries in the container, etc.;
• ContainerFormat is an enumeration of the supported container formats.

class aeneas.container.Container(file_path, container_format=None, rconf=None, logger=None)

An abstraction for different archive formats like ZIP or TAR, exposing common functions like extracting all entries or just a single entry, listing the entries, etc.

An (uncompressed) directory can be used in lieu of a compressed file.

Parameters:

• file_path (string) – the path to the container file (or directory)
• container_format (ContainerFormat) – the format of the container
• rconf (RuntimeConfiguration) – a runtime configuration
• logger (Logger) – the logger object

Raises:

TypeError: if file_path is None

Raises:

ValueError: if container_format is not None and is not an allowed value

compress(input_path)

Compress the contents of the given directory.

Parameters:input_path (string) – path of the input directory Raises:TypeError: if the container path has not been set Raises:ValueError: if input_path is not an existing directory Raises:OSError: if an error occurred compressing the given container (e.g., empty file, damaged file, etc.)

container_format

The format of this container.

Return type:ContainerFormat

decompress(output_path)

Decompress the entire container into the given directory.

Parameters:output_path (string) – path of the destination directory Raises:TypeError: if this container does not exist Raises:ValueError: if this container contains unsafe entries, or output_path is not an existing directory Raises:OSError: if an error occurred decompressing the given container (e.g., empty file, damaged file, etc.)

entries

Return the sorted list of entries in this container, each represented by its full path inside the container.

Return type:list of strings (path) Raises:TypeError: if this container does not exist Raises:OSError: if an error occurred reading the given container (e.g., empty file, damaged file, etc.)

entry_config_txt

Return the entry (path inside the container) of the TXT config file in this container, or None if not present.

Return type:string Raises:same as entries()

entry_config_xml

Return the entry (path inside the container) of the XML config file in this container, or None if not present.

Return type:string Raises:same as entries()

exists()

Return True if the container has its path set and it exists, False otherwise.

Return type:boolean

file_path

The path of this container.

Return type:string

find_entry(entry, exact=True)

Return the full path to the first entry whose file name equals the given entry path.

Return None if the entry cannot be found.

If exact is True, the path must be exact, otherwise the comparison is done only on the file name.

Example:

entry = "config.txt"

matches:

config.txt            (if exact == True or exact == False)
foo/config.txt        (if exact == False)
foo/bar/config.txt    (if exact == False)

Parameters:

• entry (string) – the entry name to be searched for
• exact (bool) – look for the exact entry path

Return type:

string

Raises:

same as entries()

has_config_txt

Return True if there is a TXT config file in this container, False otherwise.

Return type:bool Raises:same as entries()

has_config_xml

Return True if there is an XML config file in this container, False otherwise.

Return type:bool Raises:same as entries()

is_entry_safe(entry)

Return True if entry can be safely extracted, that is, if it does start with / or ../ after path normalization, False otherwise.

Return type:bool

is_safe

Return True if the container can be safely extracted, that is, if all its entries are safe, False otherwise.

Return type:bool Raises:same as entries()

read_entry(entry)

Read the contents of an entry in this container, and return them as a byte string.

Return None if the entry is not safe or it cannot be found.

Return type:byte string Raises:same as entries()

class aeneas.container.ContainerFormat

Enumeration of the supported container formats.

ALLOWED_FILE_VALUES = ['epub', 'tar', 'tar.gz', 'tar.bz2', 'zip']

List of all the allowed values for a container file

ALLOWED_VALUES = ['epub', 'tar', 'tar.gz', 'tar.bz2', 'unpacked', 'zip']

List of all the allowed values

EPUB = 'epub'

EPUB container

TAR = 'tar'

TAR container (without compression)

TAR_BZ2 = 'tar.bz2'

TAR container with BZ2 compression

TAR_GZ = 'tar.gz'

TAR container with GZ compression

UNPACKED = 'unpacked'

Unpacked container (i.e., a directory)

ZIP = 'zip'

ZIP container