ZipArchive

from panda3d.core import ZipArchive

class ZipArchive

Bases:

Bases: ReferenceCount

A file that contains a set of files.

Inheritance diagram

__init__()

add_jar_signature(certificate: Filename, pkey: Filename, password: str, alias: str) → bool

Adds a new JAR-style signature to the .zip file. The file must have been opened in read/write mode.

This implicitly causes a repack() operation if one is needed. Returns true on success, false on failure.

This flavor of add_jar_signature() reads the certificate and private key from a PEM-formatted file, for instance as generated by the openssl command. If the private key file is password-encrypted, the third parameter will be used as the password to decrypt it.

It’s possible to add multiple signatures, by providing multiple unique aliases. Note that aliases are considered case-insensitively and only the first 8 characters are considered.

There is no separate parameter to pass a certificate chain. Instead, any necessary certificates are expected to be in the certificate file.

add_subfile(subfile_name: str, filename: Filename, compression_level: int) → str

Adds a file on disk as a subfile to the ZipArchive. The file named by filename will be read and added to the ZipArchive immediately, but the index will not be updated until you call flush(). If there already exists a subfile with the indicated name, it is replaced without examining its contents (but see also update_subfile()).

Returns the subfile name on success (it might have been modified slightly), or empty string on failure.

add_subfile(subfile_name: str, subfile_data: istream, compression_level: int) → str

Adds a file from a stream as a subfile to the ZipArchive. The indicated istream will be read and its contents added to the end of the current ZIP file immediately.

Note that the istream must remain untouched and unused by any other code until flush() is called. At that time, the index of the ZIP archive will be rewritten to the end of the file.

Returns the subfile name on success (it might have been modified slightly), or empty string on failure.

close(): Closes the ZipArchive if it is open. All changes are flushed to disk, and the file becomes invalid for further operations until the next call to open().

static close_read_subfile(stream: istream): Closes a file opened by a previous call to open_read_subfile(). This really just deletes the istream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

compare_subfile(index: int, filename: Filename) → bool

Performs a byte-for-byte comparison of the indicated file on disk with the nth subfile. Returns true if the files are equivalent, or false if they are different (or the file is missing).

If Filename.set_binary() or set_text() has already been called, it specifies the nature of the source file. If this is different from the text flag of the subfile, the comparison will always return false. If this has not been specified, it will be set from the text flag of the subfile.

extract_subfile(index: int, filename: Filename) → bool: Extracts the nth subfile into a file with the given name.

extract_subfile_to(index: int, out: ostream) → bool: Extracts the nth subfile to the indicated ostream.

find_subfile(subfile_name: str) → int: Returns the index of the subfile with the indicated name, or -1 if the named subfile is not within the ZipArchive.

flush() → bool

Ensures that any changes made to the ZIP archive have been synchronized to disk. In particular, this causes the central directory to be rewritten at the end of the file.

This may result in a suboptimal packing in the ZIP file, especially if existing files were changed or files were removed. To guarantee that the file is as compact as it can be, call repack() instead of flush().

It is not necessary to call flush() explicitly unless you are concerned about reading the recently-added subfiles immediately.

Returns true on success, false on failure.

get_comment() → str: Returns the comment string that was at the end of the ZIP end-of-directory record, if any. See set_comment().

get_filename() → Filename: Returns the filename of the ZipArchive, if it is available.

get_num_subfiles() → int: Returns the number of subfiles within the ZipArchive. The subfiles may be accessed in alphabetical order by iterating through [0 .. get_num_subfiles()).

get_record_timestamp() → bool: Returns the flag indicating whether timestamps should be recorded within the ZipArchive or not. See set_record_timestamp().

get_subfile_internal_length(index: int) → int: Returns the number of bytes the indicated subfile consumes within the archive. For compressed subfiles, this will generally be smaller than get_subfile_length(); for encrypted (but noncompressed) subfiles, it may be slightly different, for noncompressed and nonencrypted subfiles, it will be equal.

get_subfile_internal_start(index: int) → int: Returns the starting byte position within the ZipArchive at which the indicated subfile begins. This may be used, with get_subfile_internal_length(), for low-level access to the subfile, but usually it is better to use open_read_subfile() instead (which automatically decrypts and/or uncompresses the subfile data).

get_subfile_length(index: int) → int: Returns the uncompressed data length of the nth subfile.

get_subfile_name(index: int) → str: Returns the name of the nth subfile.

get_subfile_names() → list

get_subfile_timestamp(index: int) → int: Returns the modification time of the nth subfile. If this is called on an older .zip file, which did not store individual timestamps in the file (or if get_record_timestamp() is false), this will return the modification time of the overall ZIP file.

has_directory(subfile_name: str) → bool: Returns true if the indicated subfile name is the directory prefix to one or more files within the ZipArchive. That is, the ZipArchive contains at least one file named “subfile_name/…”.

is_read_valid() → bool: Returns true if the ZipArchive has been opened for read mode and there have been no errors, and individual Subfile contents may be extracted.

is_subfile_compressed(index: int) → bool: Returns true if the indicated subfile has been compressed when stored within the archive, false otherwise.

is_subfile_encrypted(index: int) → bool: Returns true if the indicated subfile has been encrypted when stored within the archive, false otherwise.

is_write_valid() → bool: Returns true if the ZipArchive has been opened for write mode and there have been no errors, and Subfiles may be added or removed from the ZipArchive.

ls(out: ostream): Shows a list of all subfiles within the ZipArchive.

needs_repack() → bool: Returns true if the ZipArchive index is suboptimal and should be repacked. Call repack() to achieve this. It is not done automatically.

open_read(filename: Filename) → bool

Opens the named ZipArchive on disk for reading. The ZipArchive index is read in, and the list of subfiles becomes available; individual subfiles may then be extracted or read, but the list of subfiles may not be modified.

Also see the version of open_read() which accepts an istream. Returns true on success, false on failure.

open_read(stream: IStreamWrapper, owns_pointer: bool) → bool

Opens an anonymous ZipArchive for reading using an istream. There must be seek functionality via seekg() and tellg() on the istream.

If owns_pointer is true, then the ZipArchive assumes ownership of the stream pointer and will delete it when the ZIP file is closed, including if this function returns false.

The given stream must be seekable.

open_read_subfile(index: int) → istream

Returns an istream that may be used to read the indicated subfile. You may seek() within this istream to your heart’s content; even though it will be a reference to the already-opened pfstream of the ZipArchive itself, byte 0 appears to be the beginning of the subfile and EOF appears to be the end of the subfile.

The returned istream will have been allocated via new; you should pass the pointer to close_read_subfile() when you are finished with it to delete it and release its resources.

Any future calls to repack() or close() (or the ZipArchive destructor) will invalidate all currently open subfile pointers.

The return value will be NULL if the stream cannot be opened for some reason.

open_read_write(filename: Filename) → bool

Opens the named ZipArchive on disk for reading and writing. If there already exists a file by that name, its index is read. Subfiles may be added or removed, and the resulting changes will be written to the named file.

Also see the version of open_read_write() which accepts an iostream. Returns true on success, false on failure.

open_read_write(stream: iostream, owns_pointer: bool) → bool

Opens an anonymous ZipArchive for reading and writing using an iostream. There must be seek functionality via seekg()/seekp() and tellg()/tellp() on the iostream.

If owns_pointer is true, then the ZipArchive assumes ownership of the stream pointer and will delete it when the ZIP file is closed, including if this function returns false.

open_write(filename: Filename) → bool

Opens the named ZipArchive on disk for writing. If there already exists a file by that name, it is truncated. The ZipArchive is then prepared for accepting a brand new set of subfiles, which will be written to the indicated filename. Individual subfiles may not be extracted or read.

Also see the version of open_write() which accepts an ostream. Returns true on success, false on failure.

open_write(stream: ostream, owns_pointer: bool) → bool

Opens an anonymous ZipArchive for writing using an ostream.

If owns_pointer is true, then the ZipArchive assumes ownership of the stream pointer and will delete it when the ZIP file is closed, including if this function returns false.

output(out: ostream)

read_subfile(index: int) → bytes: Returns a vector_uchar that contains the entire contents of the indicated subfile.

remove_subfile(index: int)

Removes the nth subfile from the ZipArchive. This will cause all subsequent index numbers to decrease by one. The file will not actually be removed from the disk until the next call to flush().

Note that this does not actually remove the data from the indicated subfile; it simply removes it from the index. The ZipArchive will not be reduced in size after this operation, until the next call to repack().

remove_subfile(subfile_name: str) → bool

Removes the named subfile from the ZipArchive, if it exists; returns true if successfully removed, or false if it did not exist in the first place. The file will not actually be removed from the disk until the next call to flush().

Note that this does not actually remove the data from the indicated subfile; it simply removes it from the index. The ZipArchive will not be reduced in size after this operation, until the next call to repack().

repack() → bool

Forces a complete rewrite of the ZipArchive and all of its contents, so that the files are tightly packed in the file without any gaps. This is useful to do after removing files, to ensure that the file size is minimized.

It is only valid to call this if the ZipArchive was opened using open_read_write() and an explicit filename, rather than an iostream. Also, we must have write permission to the directory containing the ZipArchive.

Returns true on success, false on failure.

scan_directory(contents: vector_string, subfile_name: str) → bool

Considers subfile_name to be the name of a subdirectory within the ZipArchive, but not a file itself; fills the given vector up with the sorted list of subdirectories or files within the named directory.

Note that directories do not exist explicitly within a ZipArchive; this just checks for the existence of files with the given initial prefix.

Returns true if successful, false otherwise.

set_comment(comment: str): Sets the string which is appended to the very end of the ZIP archive. This string may not be longer than 65535 characters.

set_filename(filename: Filename): Replaces the filename of the ZipArchive. This is primarily used for documentation purposes only; changing this name does not open the indicated file. See open_read() or open_write() for that.

set_record_timestamp(record_timestamp: bool)

Sets the flag indicating whether timestamps should be recorded within the ZipArchive or not. The default is true, indicating the ZipArchive will record timestamps for each subfile that is added.

If this is false, the ZipArchive will not record timestamps internally. In this case, the return value from get_subfile_timestamp() will be zero.

You may want to set this false to minimize the bitwise difference between independently-generated ZipArchives.

update_subfile(subfile_name: str, filename: Filename, compression_level: int) → str

Adds a file on disk to the subfile. If a subfile already exists with the same name, its contents are compared byte-for-byte to the disk file, and it is replaced only if it is different; otherwise, the ZIP file is left unchanged.

Either Filename:::set_binary() or set_text() must have been called previously to specify the nature of the source file. If set_text() was called, the text flag will be set on the subfile.

verify() → bool: Verifies the integrity of the contents of the ZIP archive.