packio
======

.. py:module:: packio

.. autoapi-nested-parse::

   Public methods and classes for packio package.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/packio/io/index
   /autoapi/packio/zipping/index


Classes
-------

.. autoapisummary::

   packio.Reader
   packio.Writer


Functions
---------

.. autoapisummary::

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


Package Contents
----------------

.. py:class:: Reader(path: pathlib.Path)

   Context manager to read multiple objects from the same file.

   Initialize zipfile with a file path.


   .. py:attribute:: path


   .. py:method:: __enter__() -> Reader

      Create temporary directory and zip object, return callable.



   .. py:method:: file(filename: str) -> pathlib.Path

      Unzip the file to a temporary path and return that path.



   .. py:method:: __exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: types.TracebackType | None) -> None

      Exit the context manager.



.. py:class:: Writer(path: pathlib.Path)

   Context manager to write multiple objects to the same file.

   Initialize the reader with a file path.


   .. py:attribute:: path


   .. py:method:: __enter__() -> ArchiveWriter

      Create temporary directory and zip object, return callable.



   .. py:method:: __exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: types.TracebackType | None) -> None

      Exit the context manager.



.. 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.


.. 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:: 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.