wolfhece.pydownloader
=====================

.. py:module:: wolfhece.pydownloader

.. autoapi-nested-parse::

   Author: HECE - University of Liege, Pierre Archambeau
   Date: 2025

   Copyright (c) 2025 University of Liege. All rights reserved.

   This script and its content are protected by copyright law. Unauthorized
   copying or distribution of this file, via any medium, is strictly prohibited.









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

.. py:class:: DownloadType(*args, **kwds)

   Bases: :py:obj:`enum.Enum`

   .. autoapi-inheritance-diagram:: wolfhece.pydownloader.DownloadType
      :parts: 1
      :private-bases:


   Enum to define the type of download.


   .. py:attribute:: HTTP
      :value: 'http'



   .. py:attribute:: HTTPS
      :value: 'https'



   .. py:attribute:: FTP
      :value: 'ftp'



.. py:class:: DownloadFiles(*args, **kwds)

   Bases: :py:obj:`enum.Enum`

   .. autoapi-inheritance-diagram:: wolfhece.pydownloader.DownloadFiles
      :parts: 1
      :private-bases:


   Enum to define the files to download.


   .. py:attribute:: WOLFARRAYS
      :value: ('bin', 'bin.txt')



   .. py:attribute:: TIFARRAYS
      :value: ('tif',)



   .. py:attribute:: TIFFARRAYS
      :value: ('tiff',)



   .. py:attribute:: SHPFILES
      :value: ('shp', 'dbf', 'shx', 'prj', 'cpg', 'sbn', 'sbx')



   .. py:attribute:: GPKGFILES
      :value: ('gpkg',)



   .. py:attribute:: VECFILES
      :value: ('vec', 'vec.extra')



   .. py:attribute:: VECZFILES
      :value: ('vecz', 'vecz.extra')



   .. py:attribute:: PROJECTFILES
      :value: ('proj',)



   .. py:attribute:: NUMPYFILES
      :value: ('npy',)



   .. py:attribute:: NPZFILES
      :value: ('npz',)



   .. py:attribute:: JSONFILES
      :value: ('json',)



   .. py:attribute:: TXTFILES
      :value: ('txt',)



   .. py:attribute:: CSVFILES
      :value: ('csv',)



   .. py:attribute:: DXFFILES
      :value: ('dxf',)



   .. py:attribute:: ZIPFILES
      :value: ('zip',)



   .. py:attribute:: LAZFILES
      :value: ('laz',)



   .. py:attribute:: LISTFILES
      :value: ('lst',)



   .. py:attribute:: LAZBIN
      :value: ('bin',)



.. py:class:: DonwloadDirectories(*args, **kwds)

   Bases: :py:obj:`enum.Enum`

   .. autoapi-inheritance-diagram:: wolfhece.pydownloader.DonwloadDirectories
      :parts: 1
      :private-bases:


   Enum to define the directories for downloads.


   .. py:attribute:: GDBFILES
      :value: ('gdb',)



.. py:data:: GITLAB_EXAMPLE
   :value: 'https://gitlab.uliege.be/HECE/wolf_examples/-/raw/main'


.. py:data:: GITLAB_EXAMPLE_GPU
   :value: 'https://gitlab.uliege.be/HECE/wolfgpu_examples/-/raw/main'


.. py:data:: GITLAB_MODREC_DATA_VESDRE
   :value: 'https://gitlab.uliege.be/api/v4/projects/4933'


.. py:data:: GITLAB_MODREC_DATA_VESDRE_FILES
   :value: 'https://gitlab.uliege.be/api/v4/projects/4933/repository/files/'


.. py:data:: GITLAB_INJECTORS_GPU
   :value: 'https://gitlab.uliege.be/HECE/wolfgpu_injectors/-/raw/main/src/'


.. py:data:: DATADIR

.. py:function:: clean_url(url: str) -> str

   Clean the URL by removing any query parameters or fragments.

   :param url: The URL to clean.
   :type url: str
   :return: The cleaned URL.
   :rtype: str


.. py:function:: download_file(url: str, destination: Union[str, pathlib.Path] = None, download_type: DownloadType = DownloadType.HTTP, load_from_cache: bool = True, token: str = None, file_type: DownloadType = None) -> pathlib.Path

   Download a file from the specified URL to the destination path.

   :param url: The URL of the file to download.
   :param destination: The path where the file will be saved.
   :param download_type: The type of download (HTTP, HTTPS, FTP).
   :type url: str
   :type destination: Union[str, Path]
   :type download_type: DownloadType
   :return: None
   :raises requests.HTTPError: If the HTTP request fails.


.. py:function:: toys_dataset(dir: str, file: str, load_from_cache: bool = True)

   Download toy files from the WOLFHECE dataset.

   :param dir: The directory where the file will be saved.
   :param file: The name of the file to download.
   :type dir: str
   :type file: str
   :return: The path to the downloaded file.


.. py:function:: download_gpu_simulation(url: str, destination: str | pathlib.Path, load_from_cache: bool = True)

   Download a GPU simulation file from the WOLFHECE dataset.

   :param url: The URL of the GPU simulation file to download.
   :param destination: The path where the file will be saved.
   :param load_from_cache: If True, will not download the file if it already exists.
   :type url: str
   :type destination: str | Path
   :type load_from_cache: bool


.. py:function:: toys_gpu_dataset(dir: str, dirweb: str = None, load_from_cache: bool = True)

   Download toy simulatoin files from the WOLFHECE dataset for GPU.

   :param dir: The directory where the file will be saved.
   :param dirweb: The directory of the files to download.
   :type dir: str
   :type dirweb: str
   :return: The path to the downloaded file.


.. py:function:: toys_injector_gpu(file: str, load_from_cache: bool = True)

   Download toy GPU injector files from the WOLFHECE dataset.

   :param file: The name of the file to download.
   :type file: str
   :return: The path to the downloaded file.


.. py:function:: toys_laz_grid(dir: str, file: str, load_from_cache: bool = True)

   Download toy LAZ or GRIDWOLF files from the WOLFHECE dataset.

   :param dir: The directory where the file will be saved.
   :param file: The name of the file to download.
   :type dir: str
   :type file: str
   :return: The path to the downloaded directory.


.. py:function:: laz_grid_from_url(url: str, dir: str, file: str, load_from_cache: bool = True)

   Download toy LAZ or GRIDWOLF files from an external URL.

   :param url: The base URL where the files are located.
   :param dir: The directory where the file will be saved.
   :param file: The name of the file to download.
   :type url: str
   :type dir: str
   :type file: str
   :return: The path to the downloaded directory.


.. py:function:: check_status(url: str, token: str = None) -> bool

   Check the status of a URL.

   :param url: The URL to check.
   :param token: The private token for authentication (if required).
   :type url: str
   :type token: str
   :return: True if the URL is accessible, False otherwise.
   :rtype: bool


.. py:function:: download_modrec_vesdre_file(directory: str, filename: str, token: str = None, load_from_cache: bool = True, file_type: DownloadFiles = None) -> pathlib.Path

   Download a file from the ModRec Vesdre dataset.

   :param directory: The directory where the file is located (relative to the repository root).
   :param filename: The name of the file to download.
   :param token: The private token for authentication (if required).
   :param load_from_cache: If True, will not download the file if it already exists.
   :type directory: str
   :type filename: str
   :type token: str
   :type load_from_cache: bool
   :return: The path to the downloaded file.
   :rtype: Path


.. py:data:: token
   :value: ''