fastdev.io
==========

.. py:module:: fastdev.io


Submodules
----------

.. toctree::
   :maxdepth: 1

   /api/fastdev/io/archive/index
   /api/fastdev/io/download/index
   /api/fastdev/io/handlers/index
   /api/fastdev/io/io/index






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

.. py:function:: extract_archive(filename: str, extract_dir: str, remove_top_dir: bool = False)

   Extract archive file to a directory.

   Currently only supports zip files.

   :param filename: Local path to the archive file.
   :type filename: str
   :param extract_dir: Directory to extract the archive file.
   :type extract_dir: str
   :param remove_top_dir: Whether to remove the top-level directory in the archive.
                          If True, the top-level common prefix directory will be removed. Defaults to False.
   :type remove_top_dir: bool, optional


.. py:function:: cached_local_path(url: str, rel_cache_path: Optional[str] = None, cache_root: str = FDEV_CACHE_ROOT) -> str

   Get the cached local path of the URL.

   :param url: Remote URL.
   :type url: str
   :param rel_cache_path: Relative local path in the cache root.
                          Use the URL relative path if None. Defaults to None.
   :type rel_cache_path: str, optional
   :param cache_root: Cache root. Defaults to FDEV_CACHE_ROOT.
   :type cache_root: str, optional


.. py:function:: download_url(url: str, local_path: str, verify: bool = True, force_redownload: bool = False) -> str

   Download url to local path.

   :param url: URL to download.
   :type url: str
   :param local_path: Local path to save the downloaded file.
                      If the local path is a directory, the file will be saved to the directory with the same name as the URL basename.
   :type local_path: str
   :param verify: Verify SSL certificate. Defaults to True.
   :type verify: bool, optional
   :param force_redownload: Whether to force redownload the file even if it exists. Defaults to False.
   :type force_redownload: bool, optional

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


.. py:data:: FILE_EXTENSIONS
   :type:  typing_extensions.TypeAlias

.. py:function:: dump(obj: Any, file: Union[str, pathlib.Path, IO], file_format: Optional[FILE_EXTENSIONS] = None, **kwargs)

   Dump obj to json/yaml file.

   :param obj: Python object to dump.
   :type obj: Any
   :param file: File path or IO object.
   :type file: Union[str, Path, IO]
   :param file_format: File format. Defaults to None.
   :type file_format: Optional[FILE_EXTENSIONS], optional

   .. rubric:: Examples

   >>> import tempfile
   >>> with tempfile.TemporaryDirectory() as tmpdir:
   ...     dump({"hello": "world"}, f"{tmpdir}/example.json")


.. py:function:: load(file: Union[str, pathlib.Path, IO], file_format: Optional[FILE_EXTENSIONS] = None, **kwargs) -> Any

   Load json/yaml/pickle file from file.

   :param file: file path or io object.
   :type file: Union[str, Path, IO]
   :param file_format: file extension. Defaults to None.
   :type file_format: Optional[FILE_EXTENSIONS], optional

   :returns: The loaded python object.
   :rtype: Any

   .. rubric:: Examples

   >>> load("assets/example.json")
   {'hello': 'world'}