packio.zipping
==============

.. py:module:: packio.zipping

.. autoapi-nested-parse::

   Tools to simplify zipping and unzipping of files.



Attributes
----------

.. autoapisummary::

   packio.zipping.PathType


Functions
---------

.. autoapisummary::

   packio.zipping.zipflat
   packio.zipping.zip
   packio.zipping.unzip
   packio.zipping.unzipflat


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

.. py:type:: PathType
   :canonical: str | Path


.. py:function:: zipflat(*, files: list[PathType], outfile: PathType) -> None

   Zip files into a single archive with no directory structure.

   :param files: List of files to zip.
   :param outfile: Path to the resulting zip archive.

   :raises ValueError: If the names of the provided files are not unique.


.. py:function:: zip(directory: PathType, *, outfile: PathType, format: str = 'zip') -> None

   Zip a directory to create an archive.

   This preserves the directory structure within the zip file. Implemented as a thin wrapper around
   shutil.make_archive.

   :param directory: Directory containing files to zip.
   :param outfile: Full path to the resulting zip archive, including any extension. Users may choose not to add an
                   extension (overriding the behavior of `shutil.make_archive`, which adds an extension).
   :param format: Format of the archive, default is 'zip'. Other formats like 'tar', 'gztar', etc. can be used.


.. py:function:: unzip(*, file: PathType, dest_dir: PathType) -> None

   Unzip an archive into a destination directory.

   :param file: Path to the zip archive.
   :param dest_dir: Directory to unzip the archive into.


.. py:function:: unzipflat(*, file: PathType, dest_dir: PathType, overwrite: bool = False) -> None

   Unzip a file into a destination directory.

   :param file: Path to the zip archive.
   :param dest_dir: An existing directory to unzip the archive into.
   :param overwrite: If True, overwrite any existing files in the destination directory.

   :raises ValueError: If the input file is not a zip archive.
   :raises ValueError: If any contents of the input zip archive are directories -- expect a flat archive.
   :raises FileExistsError: If any files in the archive would overwrite existing files in the destination directory.