:py:mod:`archive` ================= .. py:module:: archive .. autoapi-nested-parse:: Support for reading and writing tar and zip archives. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: archive.E3ZipInfo archive.E3ZipFile Functions ~~~~~~~~~ .. autoapisummary:: archive.is_known_archive_format archive.check_type archive.unpack_archive archive.create_archive Attributes ~~~~~~~~~~ .. autoapisummary:: archive.UnpackAutoRemoveDirType archive.logger .. py:data:: UnpackAutoRemoveDirType .. py:data:: logger .. py:class:: E3ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0)) Bases: :py:obj:`zipfile.ZipInfo` ZipInfo subclass for cross-platform compatibility. .. py:method:: from_file(*args: Any, **kwargs: Any) -> E3ZipInfo :classmethod: Create a ZipInfo from a file with adjusted executable permissions. Sets execute permissions (0o555) in external_attr for the file. .. py:class:: E3ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None) Bases: :py:obj:`zipfile.ZipFile` Override default ZipFile with attributes preservation. .. py:method:: _extract_member(member: str | zipfile.ZipInfo, path: str | os.PathLike[str] | None, pwd: bytes | None) -> str Extract a member from the archive with attribute preservation. :param member: member name or ZipInfo object :param path: directory to extract to :param pwd: password for encrypted files .. py:exception:: ArchiveError(message: str | list[str], origin: str | None = None) Bases: :py:obj:`e3.error.E3Error` Exception raised for archive operations errors. .. py:function:: is_known_archive_format(filename: str | pathlib.Path) -> bool Check if a given path is a supported archive format. :param filename: path :return: True if the path corresponding to a supported archive format .. py:function:: check_type(filename: str, force_extension: str | None = None) -> TAR_GZ | TAR_BZ2 | TAR_XZ | TAR | ZIP Return the archive extension. Internal function used by create_archive and unpack_archive. :param filename: the name of the archive to extract the extension :param force_extension: specify the archive extension if not in the filename :return: the file extension .. py:function:: unpack_archive(filename: str | pathlib.Path, dest: str | pathlib.Path, fileobj: IO[bytes] | None = None, selected_files: collections.abc.Sequence[str] | None = None, remove_root_dir: RemoveRootDirType = False, unpack_cmd: collections.abc.Callable[Ellipsis, None] | None = None, force_extension: str | None = None, delete: bool = False, ignore: list[str] | None = None, preserve_timestamps: bool = True, tmp_dir_root: str | pathlib.Path | None = None) -> None Unpack an archive file (.tgz, .tar.gz, .tar or .zip). :param filename: archive to unpack :param dest: destination directory (should exist) :param fileobj: if specified, the archive is read from this file object instead of opening a file. The file object must be opened in binary mode. In this case filename is the name of the archive contained in the file object. :param selected_files: list of files to unpack (partial extraction). If None all files are unpacked :param remove_root_dir: if True then the root dir of the archive is suppressed. if set to 'auto' then the root dir of the archive is suppressed only if it is possible. If not do not raise an exception in that case and fallback on the other method. :param unpack_cmd: command to run to unpack the archive, if None use default methods or raise ArchiveError if archive format is not supported. If unpack_cmd is not None, then remove_root_dir is ignored. The unpack_cmd must raise ArchiveError in case of failure. :param force_extension: specify the archive extension if not in the filename. If filename has no extension and force_extension is None unpack_archive will fail. :param delete: if True and remove_root_dir is also True, remove files from dest if they do not exist in the archive :param ignore: a list of files/folders to keep when synchronizing with the final destination directory. :param preserve_timestamps: if False and remove_root_dir is True, and the target directory exists, ensure that updated files get their timestamp updated to current time. :param tmp_dir_root: If not None the temporary directory used to extract the archive will be created in tmp_dir_root directory. If None the temporary directory is created in the destination directory. This argument only has an effect when remove_root_dir is True. :raise ArchiveError: in case of error cygpath (win32) utilities might be needed when using remove_root_dir option .. py:function:: create_archive(filename: str, from_dir: str | pathlib.Path, dest: str | pathlib.Path | None = None, fileobj: IO[bytes] | None = None, force_extension: str | None = None, from_dir_rename: str | None = None, no_root_dir: bool = False) -> None Create an archive file (.tgz, .tar.gz, .tar or .zip). The Python implementations (tarfile and zipfile) are used on all platforms. Spawning tar, gzip or zip on Linux could be faster, however it has the disadvantage of not using the same implementation across platforms, hence the choice to only use the Python implementations. :param filename: archive to create :param from_dir: directory to pack (full path) :param dest: destination directory (should exist). If not specified, the archive is written to the file object passed with fileobj. :param fileobj: if specified, the archive is written to this file object instead of opening a file. The file object must be opened in binary mode. In this case filename is the name of the archive contained in the file object. :param force_extension: specify the archive extension if not in the filename. If filename has no extension and force_extension is None create_archive will fail. :param from_dir_rename: name of root directory in the archive. :param no_root_dir: create archive without the root dir (zip only) :raise ValueError: neither dest nor fileobj is provided :raise ArchiveError: if an error occurs