hfutils.archive

Overview:: Archive pack and unpack management.

Supported Formats:

Format

Extension Name

7z

.7z

bztar

.tar.bz2, .tbz2

gztar

.tar.gz, .tgz

rar

.rar

tar

.tar

xztar

.tar.xz, .txz

zip

.zip

Note

If you require support for 7z and RAR formats, simply install hfutils using the following code:

pip install hfutils[7z]
pip install hfutils[rar]

Warning

The creation of archive files in the RAR format is not supported, as we utilize the rarfile library, which does not offer functionality for creating RAR files.

register_archive_type

hfutils.archive.register_archive_type(name: str, exts: List[str], fn_pack: Callable, fn_unpack: Callable)[source]

Register a custom archive type with associated file extensions and packing/unpacking functions.

This function allows users to add support for new archive types by providing the necessary information and functions to handle the archive format.

Parameters:

name (str) – The name of the archive type (e.g., ‘zip’, ‘tar’).
exts (List[str]) – A list of file extensions associated with the archive type (e.g., [‘.zip’]).
fn_pack (Callable) – The packing function that takes a directory and an archive filename as input and creates an archive.
fn_unpack (Callable) – The unpacking function that takes an archive filename and a directory as input and extracts the archive.

Raises:

ValueError – If no file extensions are provided for the archive type.

Example:

>>> def custom_pack(directory, archive_file, **kwargs):
...     # Custom packing logic here
...     pass
>>> def custom_unpack(archive_file, directory, **kwargs):
...     # Custom unpacking logic here
...     pass
>>> register_archive_type('custom', ['.cst'], custom_pack, custom_unpack)

archive_pack

hfutils.archive.archive_pack(type_name: str, directory: str, archive_file: str, pattern: str | None = None, silent: bool = False, clear: bool = False)[source]

Pack a directory into an archive file using the specified archive type.

This function creates an archive of the specified type containing the contents of the given directory.

Parameters:

type_name (str) – The name of the archive type.
directory (str) – The directory to pack.
archive_file (str) – The filename of the resulting archive.
pattern (str, optional) – A pattern to filter files for inclusion in the archive (optional).
silent (bool) – If True, suppress warnings during the packing process.
clear (bool) – If True, remove existing files when packing.

Raises:

ValueError – If the archive type is not registered.

Example:

>>> archive_pack('zip', '/path/to/directory', '/path/to/archive.zip', pattern='*.txt')

archive_unpack

hfutils.archive.archive_unpack(archive_file: str, directory: str, silent: bool = False, password: str | None = None)[source]

Unpack an archive file into a directory using the specified archive type.

This function extracts the contents of the given archive file into the specified directory.

Parameters:

archive_file (str) – The filename of the archive.
directory (str) – The directory to unpack the contents into.
silent (bool) – If True, suppress warnings during the unpacking process.
password (str, optional) – The password to extract the archive file (optional).

Raises:

ValueError – If the archive type is not recognized.

Example:

>>> archive_unpack('/path/to/archive.zip', '/path/to/extract')

get_archive_type

hfutils.archive.get_archive_type(archive_file: str) → str[source]

Determine the archive type based on the file extension.

This function examines the file extension of the given archive file and returns the corresponding archive type name.

Parameters:: archive_file (str) – The filename of the archive.
Returns:: The name of the archive type.
Return type:: str
Raises:: ValueError – If the file extension is not associated with any registered archive type.

Example:

>>> get_archive_type('/path/to/archive.tar.gz')
'gztar'

get_archive_extname

hfutils.archive.get_archive_extname(type_name: str) → str[source]

Get the file extension associated with a registered archive type.

This function returns the first (primary) file extension associated with the given archive type.

Parameters:: type_name (str) – The name of the archive type.
Returns:: The file extension associated with the archive type.
Return type:: str
Raises:: ValueError – If the archive type is not registered.

Example:

>>> get_archive_extname('zip')
'.zip'