czbenchmarks.file_utils
=======================

.. py:module:: czbenchmarks.file_utils


Attributes
----------

.. autoapisummary::

   czbenchmarks.file_utils.log
   czbenchmarks.file_utils.DEFAULT_CACHE_DIR
   czbenchmarks.file_utils.DEFAULT_CACHE_EXPIRATION_DAYS


Classes
-------

.. autoapisummary::

   czbenchmarks.file_utils.CacheManager


Functions
---------

.. autoapisummary::

   czbenchmarks.file_utils.download_file_from_remote


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

.. py:data:: log

.. py:data:: DEFAULT_CACHE_DIR

.. py:data:: DEFAULT_CACHE_EXPIRATION_DAYS

.. py:class:: CacheManager(cache_dir: str | pathlib.Path = DEFAULT_CACHE_DIR, expiration_days: int = DEFAULT_CACHE_EXPIRATION_DAYS)

   Centralized cache management for remote files.


   .. py:attribute:: cache_dir


   .. py:attribute:: expiration_days


   .. py:method:: ensure_directory_exists(directory: pathlib.Path) -> None

      Ensure the given directory exists.



   .. py:method:: get_cache_path(remote_url: str) -> pathlib.Path

      Generate a local cache path for a remote file.



   .. py:method:: is_expired(file_path: pathlib.Path) -> bool

      Check if a cached file is expired.



   .. py:method:: clean_expired_cache() -> None

      Clean up expired cache files.



.. py:function:: download_file_from_remote(remote_url: str, cache_dir: str | pathlib.Path = None, make_unsigned_request: bool = True) -> str

   Download a remote file to a local cache directory.

   :param remote_url: Remote URL of the file (e.g., S3 path).
   :type remote_url: str
   :param cache_dir: Local directory to save the file. Defaults to the global cache manager's directory.
   :type cache_dir: str | Path, optional
   :param make_unsigned_request: Whether to use unsigned requests for S3 (default: True).
   :type make_unsigned_request: bool, optional

   :returns: Local path to the downloaded file.
   :rtype: str

   :raises ValueError: If the remote URL is invalid.
   :raises RemoteStorageError: If the file download fails due to S3 errors.

   .. rubric:: Notes

   - If the file already exists in the cache and is not expired, it will not be downloaded again.
   - Unsigned requests are tried first, followed by signed requests if the former fails.