Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

compress.tar

import compress

compress exposes this as compress.tar, so import compress is enough and the names are called as compress.tar.*. import compress.tar reaches the same definitions directly.

This module adds support for creating and extracting TAR archives.

Important

The library exports two helper function compress() and extract() by that allows you to create and/or extract TAR archives.

This library supports the most popular extensions such as .tar.gz, .tar, .gz, .tgz, .tar.bz2, .bz2, and .tbz: the three archive shapes: uncompressed, gzip-compressed, and bzip2-compressed.

Extracting TAR archives

Use the helper function extract() for a quick way to extract TAR archives.

import tar

tar.extract('/path/to/archive.tar.gz', '/destination')

The destination can be omitted in which case the archive will be extracted into the same directory as the source with same name without the last extension. e.g. for /path/to/file.tar.gz will extract to /path/to/file.tar directory is the destination is not given.

See below for learn more about the extract() method

Creating a new TAR ball

To quickly create a new tarball, you can use the compress() helper function in the library like this,

import tar

tar.compress('/path/to/file/or/directory', '/destination.tar.gz')

The compress function can be used to compress a single file or an entire directory. Like the extract() function, you can choose to omit the destination parameter in which case compress will save the file to the current working directory with the same name as the file/directory with the extension .tar.gz.

See below for learn more about the compress() method

Constants

COMPRESS_AUTO

compress.tar.COMPRESS_AUTO

Automatically select and detect compression type (Default).

COMPRESS_NONE

compress.tar.COMPRESS_NONE = 0

Create and read archives without any compression.

COMPRESS_GZIP

compress.tar.COMPRESS_GZIP = 1

Create and read archives with the GZip compression method.

COMPRESS_BZIP

compress.tar.COMPRESS_BZIP = 2

Create and read archives with the BZip2 compression method.

Functions

compress()

compress.tar.compress(path: string, destination: string)

Create a new TAR ball from the file or directory in the given path and saves it to the destination path or ${NAME_OF_FILE}.tar.gz in the current directory if the destination is not given.

Parameters

  • path (string) — the file or directory that will be compressed.
  • destination (string) — the destination of the compressed TAR ball.

extract()

compress.tar.extract(file: string, destination: string) -> list

Extracts a TAR file to the given destination or to the same directory as the source file with the same name as the TAR file (without the last extension) if destination is not given.

Parameters

  • file (string) — the file to be extracted
  • destination (string) — the path to extract to (Optional).

Returns list — list of extracted items

Classes

TarCorruptedError

class compress.tar.TarCorruptedError < Error

Error thrown when a TAR archive is corrupted.

TarIOError

class compress.tar.TarIOError < Error

Error thrown when an I/O error occurs.

TarIllegalCompressionError

class compress.tar.TarIllegalCompressionError < Error

Error thrown when an illegal compression type is used.

Tar

class compress.tar.Tar

Tar.set_compression()

compress.tar.Tar.set_compression(level: ?int, type: ?int)

Set the compression level and type.

Parameters

  • level (int) — Compression level (0 to 9) - Default = 9
  • type (int) — Type of compression to use (use COMPRESS_* constants)
    • Default = COMPRESS_AUTO

Raises TarIllegalCompressionError

Tar.open()

compress.tar.Tar.open(path: string)

Open an existing Tar file for reading.

Parameters

  • file (string)

Raises TarIOError

Raises TarIllegalCompressionError

Tar.contents()

compress.tar.Tar.contents() -> list[dict]

Read the contents of a Tar archive

This function lists the files stored in the Tar, and returns an indexed array of FileInfo objects

The Tar is closed afer reading the contents, because rewinding is not possible in bzip2 streams. Reopen the file with open() again if you want to do additional operations

Returns list[dict]

Tar.extract()

compress.tar.Tar.extract(outdir: string, strip: ?int|string, exclude: ?string, include: ?string) -> list[string]

Extract an existing Tar archive

The strip parameter allows you to strip a certain number of path components from the filenames found in the Tar file, similar to the –strip-components feature of GNU tar. This is triggered when an integer is passed as strip. Alternatively a fixed string prefix may be passed in strip. If the filename matches this prefix, the prefix will be stripped. It is recommended to give prefixes with a trailing slash.

By default this will extract all files found in the Tar. You can restrict the output using the include and exclude parameter. Both expect a full regular expression (including delimiters and modifiers). If include is set, only files that match this expression will be extracted. Files that match the exclude expression will never be extracted. Both parameters can be used in combination. Expressions are matched against stripped filenames as described above.

The Tar is closed afterwards. Reopen the file with open() again if you want to do additional operations.

Parameters

  • outdir (string) — the target directory for extracting
  • strip (?int|string) — either the number of path components or a fixed prefix to strip
  • exclude (?string) — a regular expression of files to exclude
  • include (?string) — a regular expression of files to include

Returns list[string]

Raises TarIOError

Raises TarCorruptedError when an entry’s name would place it outside outdir, by being absolute or by climbing out through ... Nothing past that entry is extracted.

Tar.create()

compress.tar.Tar.create(path: ?string)

Create a new Tar file.

If file is empty, the Tar file will be created in memory.

Parameters

  • path (?string)

Tar.add_file()

compress.tar.Tar.add_file(path: string, header: ?string|dict)

Add a file to the current Tar using an existing file in the filesystem.

Parameters

  • path (string) — path to the original file
  • header (?string|dict) — either the name to use in Tar (string) or a dictionary oject with all meta data, empty to take from original.

Raises TarIOError

Tar.add_data()

compress.tar.Tar.add_data(data: bytes, header: ?string|dict)

Add a file to the current Tar using the given data as content.

If the header is set to nil or empty string, a file called Untitled-{CURRENT_TIMESTAMP} will be created.

Parameters

  • data (bytes) — binary content of the file to add
  • header (?string|dict) — either the name to use in Tar (string) or a dictionary oject with all meta data

Raises TarIOError

Tar.close()

compress.tar.Tar.close()

Add the closing footer to the archive if in write mode, close all file handles

After a call to this function no more data can be added to the archive, for read access no reading is allowed anymore

“Physically, an archive consists of a series of file entries terminated by an end-of-archive entry, which consists of two 512 blocks of zero bytes”

Raises TarIOError

Tar.get_archive()

compress.tar.Tar.get_archive() -> bytes

Returns the created in-memory Tar data.

This implicitly calls close() on the Tar.

Returns bytes

Raises TarIOError

Raises TarIllegalCompressionError

Tar.save()

compress.tar.Tar.save(path: string) -> bool

Save the created in-memory Tar data

Note: It is more memory effective to specify the filename in the create() function and let the library work on the new file directly.

Parameters

  • path (string)

Returns bool

Tar.add_directory()

compress.tar.Tar.add_directory(directory: string, file_blacklist: ?list, ext_blacklist: ?list)

Adds the specified directory recursively to the archive and set’s it path in the archive to dir.

Parameters

  • directory (string)
  • file_blacklist (list) — if not empty, this function will ignore every file with a matching path.
  • ext_blacklist (list) — if not empty, this function will ignore every file with a matching extension.

Raises TarIOError|Error

Tar.file_type()

compress.tar.Tar.file_type(f: string) -> int

Guesses the wanted compression from the given file.

Uses magic bytes for existing files, the file extension otherwise.

You don’t need to call this yourself. It’s used when you pass COMPRESS_AUTO somewhere.

Parameters

  • file (string)

Returns int — (one of COMPRESS_BZIP, COMPRESS_GZIP or COMPRESS_NONE)

2024, Richard Ore and The Zuri Contributors