mth5.utils.h5_tools
===================

.. py:module:: mth5.utils.h5_tools

.. autoapi-nested-parse::

   Utilities for HDF5 maintenance tasks.



Attributes
----------

.. autoapisummary::

   mth5.utils.h5_tools.PathLike


Functions
---------

.. autoapisummary::

   mth5.utils.h5_tools.repack_hdf5


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

.. py:data:: PathLike

.. py:function:: repack_hdf5(input_file: PathLike, output_file: PathLike, *, overwrite: bool = False) -> pathlib.Path

   Repack an HDF5 file by copying all objects into a new file.

   Repacking can reduce file size when metadata or datasets were repeatedly
   modified and the source file contains unused internal space.

   This mirrors the core idea of ``h5repack``: rewrite all objects into a new
   HDF5 container so only live content remains. It does *not* expose the full
   ``h5repack`` feature set (for example: filter/layout transformation,
   chunk-size retuning, and advanced option flags).

   :param input_file: Source HDF5 file to repack.
   :type input_file: str | pathlib.Path
   :param output_file: Destination path for the repacked HDF5 file.
   :type output_file: str | pathlib.Path
   :param overwrite: If ``True``, overwrite ``output_file`` when it exists.
   :type overwrite: bool, default=False

   :returns: The output path.
   :rtype: pathlib.Path

   :raises FileNotFoundError: If ``input_file`` does not exist.
   :raises FileExistsError: If ``output_file`` exists and ``overwrite`` is ``False``.

   .. rubric:: Examples

   >>> from mth5.utils.h5_tools import repack_hdf5
   >>> repacked = repack_hdf5("survey_original.h5", "survey_repacked.h5", overwrite=True)
   >>> print(repacked)
   survey_repacked.h5