zip

The zip module contains classes and functions to make working with zip archives easy.

Fields

zip.ZIP_FILE_MAX ➝ number

The maximum size of a single file in a zip archive when zip64 is not used

zip.ZIP_FILE_COUNT_LIMIT ➝ number

The maximum number of files in a zip archive when zip64 is not used

zip.ZIP_MAX ➝ number

The maximum size of a zip archive when zip64 is not used

zip.ZIP_EXT ➝ string

The default zip file extension

Functions

zip.extract(file, destination, is_zip64)

Extracts the zip archive at the file path to the given destination directory. If destination is not given, the file will be extracted into the current working directory. This function returns true if the extraction was successful and false otherwise.

NOTE: Set is_zip64 to true if the size of the zip file exceeds ZIP_MAX.

• @params:

  • string file

  • string? destination Default value is os.cwd().

  • bool? is_zip64 Default value is false.

• @returns: bool

zip.compress(path, destination, use_zip64)

Compresses the given path (file or directory) into the destination zip archive.

When an exception is thrown because max size was exceeded, some files could have already been compressed. In this case, the zip archive will should still be usable but not all desired files will be contained in it.

NOTE: Set use_zip64 to true when compressing files exceeding ZIP_FILE_MAX or ZIP_FILE_COUNT_LIMIT

• @params:

  • string file

  • string? destination Default value is os.cwd().

  • bool? is_zip64 Default value is false.

• @returns: bool
• @raises:
  • Exception

Classes

class ZipItem

ZipItem represents a single file or directory in a zip archive.

.name ➝ string

Name of the file or directory

.directory ➝ string

The directory in which the file or subdirectory belongs

.compression_method ➝ string

The compression method for this file

.crc ➝ string

The crc32 checksum for the file

.last_modified ➝ Date

The last modified date for the file

.compressed_size ➝ number

The size of the file as compressed in the archive. You should note that this value is not often dependable

.uncompressed_size ➝ number

The size of the file when extracted from the archive

.is_encrypted ➝ bool

If this file is encrypted or not.

.error ➝ string

Error encountered when attempting to read/extract the file

.data ➝ bytes

The decompressed value of the zip item

static .from_dict(dict)

Creates a new ZipItem from a dictionary. The dictionary should contain the following keys:

• name: string

• dir: string — optional

• compress_method: number

• crc: number

• filemtime: number

• size_compressed: number

• size_uncompressed: number

• encrypted: boolean

• error: string — optional

• data: bytes

• @params:

  • dictionary dict

• @returns: ZipItem

.export(base_dir)

Exports the ZipItem to file. If base_dir is given, the file will be exported into the base_dir and all ZipItem directories will be created inside of base_dir to reflect the ZipItem's original structure.

This function returns true if the operation succeeds or false otherwise.

• @params:
  • string? base_dir Default value is os.cwd().

• @returns: bool

class ZipFile

ZipFile represents an instance of zip file.

.name ➝ string

The name of the zip file

.last_modified ➝ Date

The last modified date for the zip file

.time_created ➝ Date

The time when the zip file was created

.size ➝ number

The size of the zip file

.handle ➝ file

The file handle for this zip file

.files ➝ List

A list of the ZipItems in the zip file

.export(base_dir)

Exports the all files in the ZipFile to files on the machine. If base_dir is given, the files will be exported into the base_dir and all directories will be created inside of base_dir as is to reflect the ZipFile's original structure.

This function returns true if the operation succeeds or false otherwise.

• @params:
  • string? base_dir Default value is os.cwd().

• @returns: bool

class ZipArchive

ZipArchive provides a class for zip archive creation, manipulation and extraction.

.ZipArchive(path, use_zip_64) ➝ Constructor

zip.ZipArchive constructor

• @params:
  • string path
  • bool? use_zip_64 Default value is false.

.create_dir(name)

Adds a directory to the zip with the given name.

• @params:
  • string name

• @returns: bool

.create_file(path, data, stat)

Adds a file to the path specified with the contents given data.

• @params:
  • string path
  • bytes|string data

• @returns: bool

.add_file(path, destination)

Adds an existing file to the archive. If destination is given, the file will be written to the destination path in the archive.

• @params:
  • string path
  • string? destination

• @returns: bool

.add_directory(directory, file_blacklist, ext_blacklist)

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

• If file_blacklist is not empty, this function will ignore every file with a matching path.

• If ext_blacklist is not empty, this function will ignore every file with a matching.

• @params:

  • string directory

  • list file_blacklist Default value is []

  • list ext_blacklist Default value is []

• @returns: bool

.read()

Reads the zip file in the specified path and returns a list of ZipFile describing it's contents.

• @params:
  • string path

• @returns: ZipFile

.save()

Saves the current Zip archive to file.

• @params:
  • string filename

• @returns: bool