archive
=======

.. py:module:: archive

.. autoapi-nested-parse::

   Support for reading and writing tar and zip archives.



Attributes
----------

.. autoapisummary::

   archive.UnpackAutoRemoveDirType
   archive.logger


Classes
-------

.. autoapisummary::

   archive.E3ZipInfo
   archive.E3ZipFile
   archive.ArchiveError


Functions
---------

.. autoapisummary::

   archive.is_known_archive_format
   archive.check_type
   archive.unpack_archive
   archive.create_archive


Module Contents
---------------

.. py:data:: UnpackAutoRemoveDirType

.. py:data:: logger

.. py:class:: E3ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

   Bases: :py:obj:`zipfile.ZipInfo`


   Class with attributes describing each file in the ZIP archive.


   .. py:method:: from_file(*args, **kwargs)
      :classmethod:


      Construct an appropriate ZipInfo for a file on the filesystem.

      filename should be the path to a file or directory on the filesystem.

      arcname is the name which it will have within the archive (by default,
      this will be the same as filename, but without a drive letter and with
      leading path separators removed).



.. 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: Text | zipfile.ZipInfo, path: str | os.PathLike[str] | None, pwd: bytes | None) -> str

      Extract the ZipInfo object 'member' to a physical
      file on the path targetpath.



.. py:class:: ArchiveError

   Bases: :py:obj:`e3.error.E3Error`


.. py:function:: is_known_archive_format(filename: str) -> 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, dest: str, 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 | 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, dest: str | 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


