handy_archives

Some handy archive helpers for Python.

Classes:

TarFile([name, mode, fileobj, format, …])	Subclass of tarfile.TarFile with additional methods.
ZipFile(file[, mode, compression, …])	Subclass of zipfile.ZipFile with additional methods.

Functions:

is_tarfile(name)	Return True if name points to a tar archive that tarfile can handle, else return False.
unpack_archive(filename[, extract_dir, format])	Unpack an archive.

class TarFile(name=None, mode='r', fileobj=None, format=None, tarinfo=None, dereference=None, ignore_zeros=None, encoding=None, errors='surrogateescape', pax_headers=None, debug=None, errorlevel=None, copybufsize=None)

Subclass of tarfile.TarFile with additional methods.

Methods:

extract(member[, path, set_attrs, …])	Wrapper around tarfile.TarFile.extract() with compatibility shim for PEP 706 on unpatched Pythons.
extractall([path, members, numeric_owner, …])	Wrapper around tarfile.TarFile.extractall() with compatibility shim for PEP 706 on unpatched Pythons.
extractfile(member)	Extract a member from the archive as a file object.
read_bytes(member)	Returns the content of the given file as bytes.
read_text(member, *[, normalize_nl])	Returns the content of the given file as a string.
write_file(filename[, arcname, mtime])	Add the file filename to the archive under the name arcname.

extract(member, path='', set_attrs=True, *, numeric_owner=False, filter=None)

Wrapper around tarfile.TarFile.extract() with compatibility shim for PEP 706 on unpatched Pythons.

extractall(path='.', members=None, *, numeric_owner=False, filter=None)

Wrapper around tarfile.TarFile.extractall() with compatibility shim for PEP 706 on unpatched Pythons.

extractfile(member)

Extract a member from the archive as a file object.

Parameters

member (Union[str, TarInfo]) – A filename or a tarfile.TarInfo object.

If member is a regular file or a link, an io.BufferedReader object is returned. Otherwise FileNotFoundError is raised.

Return type

IO[bytes]

read_bytes(member)

Returns the content of the given file as bytes.

Parameters

member (Union[str, TarInfo])

Raises

FileNotFoundError – If the file is not found in the archive.

Return type

bytes

read_text(member, *, normalize_nl=False)

Returns the content of the given file as a string.

Parameters

• member (Union[str, TarInfo])

• normalize_nl (bool) – If True, line endings are normalized to \n (LF). Default False.

Raises

FileNotFoundError – If the file is not found in the archive.

Return type

str

New in version 0.2.0: Added the normalize_nl option.

write_file(filename, arcname=None, mtime=None)

Add the file filename to the archive under the name arcname.

Parameters

• filename (Union[str, Path, PathLike])

• arcname (Union[str, Path, PathLike, None]) – An alternative name for the file in the archive. Default None.

• mtime (Optional[datetime]) – The last modified time of the file. Defaults to the value obtained from os.stat().

class ZipFile(file, mode='r', compression=0, allowZip64=True, compresslevel=None, *, strict_timestamps=True)

Subclass of zipfile.ZipFile with additional methods.

Methods:

extractfile(member[, pwd])	Extract a member from the archive as a file object.
read_bytes(member[, pwd])	Returns the content of the given file as bytes.
read_text(member[, pwd, normalize_nl])	Returns the content of the given file as a string.
write_file(filename[, arcname, mtime])	Put the bytes from filename into the archive under the name arcname.

extractfile(member, pwd=None)

Extract a member from the archive as a file object.

Parameters

• member (Union[str, ZipInfo]) – A filename or a zipfile.ZipInfo object.

• pwd (Union[str, bytes, None]) – The password to decrypt files. Default None.

Raises

FileNotFoundError – If the file is not found in the archive.

Return type

IO[bytes]

read_bytes(member, pwd=None)

Returns the content of the given file as bytes.

Parameters

• member (Union[str, ZipInfo])

• pwd (Union[str, bytes, None]) – The password to decrypt files. Default None.

Raises

FileNotFoundError – If the file is not found in the archive.

Return type

bytes

read_text(member, pwd=None, *, normalize_nl=False)

Returns the content of the given file as a string.

Parameters

• member (Union[str, ZipInfo])

• pwd (Union[str, bytes, None]) – The password to decrypt files. Default None.

• normalize_nl (bool) – If True, line endings are normalized to \n (LF). Default False.

Raises

FileNotFoundError – If the file is not found in the archive.

Return type

str

New in version 0.2.0: Added the normalize_nl option.

write_file(filename, arcname=None, mtime=None)

Put the bytes from filename into the archive under the name arcname.

Parameters

• filename (Union[str, Path, PathLike])

• arcname (Union[str, Path, PathLike, None]) – An alternative name for the file in the archive. Default None.

• mtime (Optional[datetime]) – The last modified time of the file. Defaults to the value obtained from os.stat().

is_tarfile(name)

Return True if name points to a tar archive that tarfile can handle, else return False.

Parameters

name (Union[str, Path, PathLike, IO[bytes]]) – A string, file, or file-like object.

Return type

bool

unpack_archive(filename, extract_dir=None, format=None)

Unpack an archive.

Parameters

• filename (Union[str, Path, PathLike]) – The name of the archive.

• extract_dir (Union[str, Path, PathLike, None]) – The name of the target directory, where the archive is unpacked. If not provided, the current working directory is used. Default None.

• format (Optional[str]) – The archive format: one of 'zip', 'tar', 'gztar', 'bztar', or 'xztar', or any other format registered through shutil.register_unpack_format(). If not provided, unpack_archive will use the filename extension and see if an unpacker was registered for that extension. Default None.

If no unpacker is found, a ValueError is raised.