Skip to main content

espnet2.main_funcs.pack_funcs.Archiver

About 4 min

espnet2.main_funcs.pack_funcs.Archiver

source

class espnet2.main_funcs.pack_funcs.Archiver(file, mode='r')

Bases: object

Archiver class for handling different types of archive files, including .tar,

.tgz, .tbz2, .txz, and .zip formats. This class provides methods for adding files, extracting files, and generating metadata for archived files.

type

The type of the archive (‘tar’ or ‘zip’).

  • Type: str

fopen

The opened archive file object.

  • Parameters:
    • file (Union *[*str , Path ]) – The path to the archive file.
    • mode (str) – The mode in which to open the archive. Default is ‘r’.
  • Raises:ValueError – If the archive format cannot be detected or is not supported.

################### Examples

Creating a new archive: : ```python

with Archiver('example.tar', mode='w') as archiver: ... archiver.add('file1.txt') ... archiver.add('file2.txt')


Extracting files from an archive:
: ```python
>>> with Archiver('example.tar', mode='r') as archiver:
...     for file_info in archiver:
...         archiver.extract(file_info, path='output_directory')

add(filename, arcname=None, recursive: bool = True)

Add a file or directory to the archive.

This method adds the specified file to the archive. If the provided filename is a directory and recursive addition is enabled, all files within that directory will be added to the archive.

  • Parameters:
    • filename (str) – The path to the file or directory to be added.
    • arcname (Optional *[*str ]) – The name to use for the file in the archive. If not specified, the original filename will be used.
    • recursive (bool) – Whether to add files recursively if the filename is a directory. Defaults to True.
  • Raises:ValueError – If the archive type is unsupported.

################### Examples

To add a single file to the archive:

>>> archiver.add("example.txt")

To add a directory and its contents:

>>> archiver.add("my_directory")

To specify an arcname:

>>> archiver.add("example.txt", arcname="new_name.txt")

addfile(info, fileobj)

Add a file to the archive with the specified information.

This method allows you to add a file to the archive using a provided info object that contains metadata about the file, as well as the actual file object to be added. The method handles both tar and zip archives, utilizing their respective APIs for adding files.

  • Parameters:
    • info (TarInfo or ZipInfo) – An object containing metadata about the file to be added. For tar archives, this should be a tarfile.TarInfo instance. For zip archives, it should be a zipfile.ZipInfo instance.
    • fileobj (IO) – A file-like object that contains the content to be added to the archive. It should support the read() method.
  • Returns: None
  • Raises:ValueError – If the archive type is not supported.

################### Examples

>>> with Archiver('example.tar', 'w') as archive:
...     info = archive.generate_info('example.txt', 100)
...     with open('example.txt', 'rb') as f:
...         archive.addfile(info, f)
NOTE

Ensure that the info object is correctly populated with the necessary metadata, such as name and size, before calling this method.

close()

Close the opened archive file.

This method ensures that the archive file is properly closed, releasing any resources associated with it. It is recommended to use this method when you are done working with the archive to avoid potential data corruption or resource leaks.

################### Examples

with Archiver(“example.tar”, “w”) as archive: : # Add files to the archive archive.add(“file1.txt”) archive.add(“file2.txt”)

Automatically closes the archive upon exiting the block

If using close explicitly

archive = Archiver(“example.zip”, “w”) archive.add(“file1.txt”) archive.close() # Ensure to close the archive manually

extract(info, path=None)

Extract a member from the archive.

This method is used to extract a file or directory from the archive to a specified path. The method automatically handles both tar and zip archive formats.

  • Parameters:
    • info – The archive member to extract. This can be a TarInfo or ZipInfo object depending on the archive type.
    • path – The destination path to which the member should be extracted. If not specified, the member will be extracted to the current working directory.
  • Returns: The path to the extracted file or directory.
  • Raises:ValueError – If the archive type is not supported.

################### Examples

>>> with Archiver('example.tar') as archive:
...     archive.extract('file.txt', path='output_dir')
'output_dir/file.txt'
>>> with Archiver('example.zip') as archive:
...     archive.extract('file.txt', path='output_dir')
'output_dir/file.txt'

extractfile(info, mode='r')

Extract a file from the archive.

This method retrieves a file from the archive specified by the provided info argument. The mode argument can be used to specify how the file is opened.

  • Parameters:
    • info – The archive member to extract. This can be a TarInfo object for tar archives or a ZipInfo object for zip archives.
    • mode – The mode in which to open the file. This defaults to “r” for text mode. For zip files, “rb” will be automatically converted to “r”.
  • Returns: A file-like object corresponding to the extracted file. If the mode is “r”, a TextIOWrapper is returned, allowing for reading the file as text. Otherwise, a binary file-like object is returned.
  • Raises:ValueError – If the archive type is not supported.

################### Examples

>>> with Archiver("example.zip") as archive:
...     with archive.extractfile("file.txt") as f:
...         content = f.read()
...         print(content)
>>> with Archiver("example.tar") as archive:
...     with archive.extractfile(archive.get_name_from_info(info)) as f:
...         data = f.read()

generate_info(name, size) → TarInfo | ZipInfo

Generate TarInfo or ZipInfo for a file using system information.

This method creates metadata for files being added to an archive, including the file name, size, and system user/group IDs for tar archives. For zip archives, it captures the file size and timestamp.

  • Parameters:
    • name (str) – The name of the file to be added to the archive.
    • size (int) – The size of the file in bytes.
  • Returns: An instance of TarInfo or ZipInfo containing the file metadata.
  • Return type: Union[tarfile.TarInfo, zipfile.ZipInfo]
  • Raises:ValueError – If the archive type is not supported.

################### Examples

For a tar archive:

>>> info = archiver.generate_info("example.txt", 1234)

For a zip archive:

>>> info = archiver.generate_info("example.zip", 5678)
NOTE

The generated TarInfo or ZipInfo will include the current timestamp as the modification time and the file size as specified.

get_name_from_info(info)

Retrieve the name of the file or directory from the given info object.

This method extracts the name of the file or directory represented by the info parameter, which can be of type tarfile.TarInfo or zipfile.ZipInfo depending on the archive type. It raises a ValueError if the archive type is not supported.

  • Parameters:info (Union *[*tarfile.TarInfo , zipfile.ZipInfo ]) – The info object containing the metadata of the file or directory.
  • Returns: The name of the file or directory.
  • Return type: str
  • Raises:ValueError – If the archive type is not supported.

################### Examples

>>> import tarfile
>>> with tarfile.open('example.tar') as tar:
...     info = tar.gettarinfo('file.txt')
...     name = get_name_from_info(info)
...     print(name)
file.txt
>>> import zipfile
>>> with zipfile.ZipFile('example.zip') as zipf:
...     info = zipf.getinfo('file.txt')
...     name = get_name_from_info(info)
...     print(name)
file.txt
Copyright © 2024 ESPnet Community. All rights reserved.