archive

Support for reading and writing tar and zip archives.

Module Contents

Classes

E3ZipInfo

Class with attributes describing each file in the ZIP archive.

E3ZipFile

Override default ZipFile with attributes preservation.

Functions

is_known_archive_format(→ bool)

Check if a given path is a supported archive format.

check_type(→ TAR_GZ | TAR_BZ2 | TAR_XZ | TAR | ZIP)

Return the archive extension.

unpack_archive(→ None)

Unpack an archive file (.tgz, .tar.gz, .tar or .zip).

create_archive(→ None)

Create an archive file (.tgz, .tar.gz, .tar or .zip).

Attributes

UnpackAutoRemoveDirType

logger

archive.UnpackAutoRemoveDirType
archive.logger
class archive.E3ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

Bases: zipfile.ZipInfo

Class with attributes describing each file in the ZIP archive.

classmethod from_file(*args, **kwargs)

Construct an appropriate ZipInfo for a file on the filesystem.

filename should be the path to a file or directory on the filesystem.

arcname is the name which it will have within the archive (by default, this will be the same as filename, but without a drive letter and with leading path separators removed).

class archive.E3ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

Bases: zipfile.ZipFile

Override default ZipFile with attributes preservation.

_extract_member(member: Text | zipfile.ZipInfo, path: str | os.PathLike[str] | None, pwd: bytes | None) → str

Extract the ZipInfo object ‘member’ to a physical file on the path targetpath.

exception archive.ArchiveError(message: str | list[str], origin: str | None = None)

Bases: e3.error.E3Error

Exception raised by functions defined in E3.

archive.is_known_archive_format(filename: str) → bool

Check if a given path is a supported archive format.

Parameters:

filename – path

Returns:

True if the path corresponding to a supported archive format

archive.check_type(filename: str, force_extension: str | None = None) → TAR_GZ | TAR_BZ2 | TAR_XZ | TAR | ZIP

Return the archive extension.

Internal function used by create_archive and unpack_archive.

Parameters:

  • filename – the name of the archive to extract the extension

  • force_extension – specify the archive extension if not in the filename

Returns:

the file extension

archive.unpack_archive(filename: str, dest: str, fileobj: IO[bytes] | None = None, selected_files: collections.abc.Sequence[str] | None = None, remove_root_dir: RemoveRootDirType = False, unpack_cmd: collections.abc.Callable[Ellipsis, None] | None = None, force_extension: str | None = None, delete: bool = False, ignore: list[str] | None = None, preserve_timestamps: bool = True, tmp_dir_root: str | None = None) → None

Unpack an archive file (.tgz, .tar.gz, .tar or .zip).

Parameters:

  • filename – archive to unpack

  • dest – destination directory (should exist)

  • fileobj – if specified, the archive is read from this file object instead of opening a file. The file object must be opened in binary mode. In this case filename is the name of the archive contained in the file object.

  • selected_files – list of files to unpack (partial extraction). If None all files are unpacked

  • remove_root_dir – if True then the root dir of the archive is suppressed. if set to ‘auto’ then the root dir of the archive is suppressed only if it is possible. If not do not raise an exception in that case and fallback on the other method.

  • unpack_cmd – command to run to unpack the archive, if None use default methods or raise ArchiveError if archive format is not supported. If unpack_cmd is not None, then remove_root_dir is ignored. The unpack_cmd must raise ArchiveError in case of failure.

  • force_extension – specify the archive extension if not in the filename. If filename has no extension and force_extension is None unpack_archive will fail.

  • delete – if True and remove_root_dir is also True, remove files from dest if they do not exist in the archive

  • ignore – a list of files/folders to keep when synchronizing with the final destination directory.

  • preserve_timestamps – if False and remove_root_dir is True, and the target directory exists, ensure that updated files get their timestamp updated to current time.

  • tmp_dir_root – If not None the temporary directory used to extract the archive will be created in tmp_dir_root directory. If None the temporary directory is created in the destination directory. This argument only has an effect when remove_root_dir is True.

Raises:

ArchiveError – in case of error

cygpath (win32) utilities might be needed when using remove_root_dir option

archive.create_archive(filename: str, from_dir: str, dest: str | None = None, fileobj: IO[bytes] | None = None, force_extension: str | None = None, from_dir_rename: str | None = None, no_root_dir: bool = False) → None

Create an archive file (.tgz, .tar.gz, .tar or .zip).

The Python implementations (tarfile and zipfile) are used on all platforms. Spawning tar, gzip or zip on Linux could be faster, however it has the disadvantage of not using the same implementation across platforms, hence the choice to only use the Python implementations.

Parameters:

  • filename – archive to create

  • from_dir – directory to pack (full path)

  • dest – destination directory (should exist). If not specified, the archive is written to the file object passed with fileobj.

  • fileobj – if specified, the archive is written to this file object instead of opening a file. The file object must be opened in binary mode. In this case filename is the name of the archive contained in the file object.

  • force_extension – specify the archive extension if not in the filename. If filename has no extension and force_extension is None create_archive will fail.

  • from_dir_rename – name of root directory in the archive.

  • no_root_dir – create archive without the root dir (zip only)

Raises:

  • ValueError – neither dest nor fileobj is provided

  • ArchiveError – if an error occurs