pelicun.tools.dlml

Methods for handling the Damage and Loss Model Library.

Functions

`_download_file`(url, local_path)	Download a file from a GitHub repository using a direct URL.
`check_dlml_data`()	Ensure DLML data is available for pelicun, downloading if necessary.
`check_dlml_version`()	Check if there's a newer version of DLML data available.
`dlml_update`([version, commit, use_cache])	Update DLML data files.
`download_data_files`([version, commit, use_cache])	Download model files from DLML based on the model_files.txt.
`get_file_hash`(file_path)	Calculate the SHA256 hash of a file.
`load_cache`(cache_file)	Load the cache from a file.
`save_cache`(cache_file, cache_data)	Save the cache to a file.
`validate_commit_sha`(commit)	Validate that the commit SHA is in the correct format.

pelicun.tools.dlml.check_dlml_data() → None[source]

Ensure DLML data is available for pelicun, downloading if necessary.

This function is called during pelicun import to check for DLML data availability. If data is not found, it downloads the latest version. If data exists, it performs a daily version check and warns if updates are available.

Raises:

RuntimeError: If the initial data download fails since pelicun cannot function without DLML data.

pelicun.tools.dlml.check_dlml_version() → Dict[str, bool | str | None][source]

Check if there’s a newer version of DLML data available.

This function checks daily for new releases and returns version information.

Returns:

dict: Dictionary containing: - ‘update_available’: bool, True if update is available - ‘current_version’: str, current local version or None - ‘latest_version’: str, latest available version or None - ‘last_check’: str, ISO timestamp of last check - ‘error’: str, error message if check failed

pelicun.tools.dlml.dlml_update(version: str | None = None, commit: str | None = None, use_cache: bool = True) → None[source]

Update DLML data files.

Parameters:

version: str, optional: Version tag (e.g., ‘v1.2.0’) or ‘latest’. Default is ‘latest’.
commit: str, optional: Commit SHA to download from. If provided, version is ignored.
use_cache: bool, optional: Whether to use caching to avoid re-downloading unchanged files. Default is True.

Raises:

RuntimeError: If the data download fails.

pelicun.tools.dlml.download_data_files(version: str = 'latest', commit: str | None = None, use_cache: bool = True) → None[source]

Download model files from DLML based on the model_files.txt.

Parameters:

version: string: The release tag name (e.g., “v1.0.0”, “beta”). Use “latest” to download from the latest published release. Ignored if commit is provided.
commit: string, optional: The commit SHA (7-digit identifier). Use “latest” to download from the latest commit. If provided, this takes precedence over the version parameter.
use_cache: bool, optional: Whether to use caching to avoid re-downloading unchanged files. Default is True.

Raises:

ValueError: If an invalid commit SHA format is provided
RuntimeError: If data download fails due to network issues, missing commits, or file errors

pelicun.tools.dlml.get_file_hash(file_path: str | Path) → str | None[source]

Calculate the SHA256 hash of a file.

Parameters:

file_path: string: Path to the file

Returns:

string: SHA256 hash of the file, or None if the file doesn’t exist

pelicun.tools.dlml.load_cache(cache_file: str | Path) → Dict[str, Any][source]

Load the cache from a file.

Parameters:

cache_file: string: Path to the cache file

Returns:

dict: The cache data, or an empty dict if the file doesn’t exist

pelicun.tools.dlml.save_cache(cache_file: str | Path, cache_data: Dict[str, Any]) → None[source]

Save the cache to a file.

Parameters:

cache_file: string: Path to the cache file
cache_data: dict: The cache data to save

pelicun.tools.dlml.validate_commit_sha(commit: str) → bool[source]

Validate that the commit SHA is in the correct format.

Parameters:

commit: string: The commit SHA to validate

Returns:

bool: True if the commit is valid, False otherwise