digitalhub 0.11.0b7__py3-none-any.whl → 0.13.0__py3-none-any.whl

digitalhub/utils/file_utils.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 from datetime import datetime
@@ -12,6 +16,21 @@ from pydantic import BaseModel
 class FileInfo(BaseModel):
     """
     File info class.
+
+    Attributes
+    ----------
+    path : str or None
+        Path to the file.
+    name : str or None
+        Name of the file.
+    content_type : str or None
+        MIME type of the file.
+    size : int or None
+        Size of the file in bytes.
+    hash : str or None
+        Hash of the file contents.
+    last_modified : str or None
+        Last modified date/time in ISO format.
     """
 
     path: Optional[str] = None
@@ -21,13 +40,21 @@ class FileInfo(BaseModel):
     hash: Optional[str] = None
     last_modified: Optional[str] = None
 
-    def to_dict(self):
+    def to_dict(self) -> dict:
+        """
+        Convert FileInfo to dictionary.
+
+        Returns
+        -------
+        dict
+            Dictionary representation of the FileInfo object.
+        """
         return self.model_dump()
 
 
 def calculate_blob_hash(data_path: str) -> str:
     """
-    Calculate the hash of a file.
+    Calculate the SHA-256 hash of a file.
 
     Parameters
     ----------
@@ -37,7 +64,7 @@ def calculate_blob_hash(data_path: str) -> str:
     Returns
     -------
     str
-        The hash of the file.
+        The SHA-256 hash of the file, prefixed with 'sha256:'.
     """
     with open(data_path, "rb") as f:
         data = f.read()
@@ -46,7 +73,7 @@ def calculate_blob_hash(data_path: str) -> str:
 
 def get_file_size(data_path: str) -> int:
     """
-    Get the size of a file.
+    Get the size of a file in bytes.
 
     Parameters
     ----------
@@ -56,14 +83,14 @@ def get_file_size(data_path: str) -> int:
     Returns
     -------
     int
-        The size of the file.
+        Size of the file in bytes.
     """
     return Path(data_path).stat().st_size
 
 
 def get_file_mime_type(data_path: str) -> str | None:
     """
-    Get the mime type of a file.
+    Get the MIME type of a file.
 
     Parameters
     ----------
@@ -72,15 +99,15 @@ def get_file_mime_type(data_path: str) -> str | None:
 
     Returns
     -------
-    str
-        The mime type of the file.
+    str or None
+        The MIME type of the file, or None if unknown.
     """
     return guess_type(data_path)[0]
 
 
 def get_path_name(data_path: str) -> str:
     """
-    Get the name of a file.
+    Get the name of a file from its path.
 
     Parameters
     ----------
@@ -97,7 +124,7 @@ def get_path_name(data_path: str) -> str:
 
 def get_last_modified(data_path: str) -> str:
     """
-    Get the last modified date of a file.
+    Get the last modified date/time of a file in ISO format.
 
     Parameters
     ----------
@@ -107,7 +134,7 @@ def get_last_modified(data_path: str) -> str:
     Returns
     -------
     str
-        The last modified date of the file.
+        The last modified date/time in ISO format.
     """
     path = Path(data_path)
     timestamp = path.stat().st_mtime
@@ -116,7 +143,7 @@ def get_last_modified(data_path: str) -> str:
 
 def get_s3_path(src_path: str) -> str:
     """
-    Get the S3 path of a file.
+    Get the S3 URI of a file path.
 
     Parameters
     ----------
@@ -126,26 +153,26 @@ def get_s3_path(src_path: str) -> str:
     Returns
     -------
     str
-        The S3 path of the file.
+        The S3 URI of the file.
     """
     return Path(src_path).as_uri()
 
 
 def get_file_info_from_local(path: str, src_path: str) -> None | dict:
     """
-    Get file info from path.
+    Get file info from a local path.
 
     Parameters
     ----------
     path : str
         Target path of the object.
     src_path : str
-        Local path of some source.
+        Local path of the source file.
 
     Returns
     -------
-    dict
-        File info.
+    dict or None
+        File info dictionary, or None if an error occurs.
     """
     try:
         name = get_path_name(path)
@@ -168,19 +195,19 @@ def get_file_info_from_local(path: str, src_path: str) -> None | dict:
 
 def get_file_info_from_s3(path: str, metadata: dict) -> None | dict:
     """
-    Get file info from path.
+    Get file info from S3 metadata.
 
     Parameters
     ----------
     path : str
         Object source path.
     metadata : dict
-        Metadata of the object from S3.
+        Metadata dictionary of the object from S3.
 
     Returns
     -------
-    dict
-        File info.
+    dict or None
+        File info dictionary, or None if an error occurs.
     """
     try:
         size = metadata["ContentLength"]
@@ -210,17 +237,17 @@ def get_file_info_from_s3(path: str, metadata: dict) -> None | dict:
 
 def eval_zip_type(source: str) -> bool:
     """
-    Evaluate zip type.
+    Evaluate whether the source is a zip file.
 
     Parameters
     ----------
     source : str
-        Source.
+        Source file path.
 
     Returns
     -------
     bool
-        True if path is zip.
+        True if the path is a zip file, False otherwise.
     """
     extension = source.endswith(".zip")
     mime_zip = get_file_mime_type(source) == "application/zip"
@@ -229,34 +256,34 @@ def eval_zip_type(source: str) -> bool:
 
 def eval_text_type(source: str) -> bool:
     """
-    Evaluate text type.
+    Evaluate whether the source is a plain text file.
 
     Parameters
     ----------
     source : str
-        Source.
+        Source file path.
 
     Returns
     -------
     bool
-        True if path is text.
+        True if the path is a plain text file, False otherwise.
     """
     return get_file_mime_type(source) == "text/plain"
 
 
 def eval_py_type(source: str) -> bool:
     """
-    Evaluate python type.
+    Evaluate whether the source is a Python file.
 
     Parameters
     ----------
     source : str
-        Source.
+        Source file path.
 
     Returns
     -------
     bool
-        True if path is python.
+        True if the path is a Python file, False otherwise.
     """
     extension = source.endswith(".py")
     mime_py = get_file_mime_type(source) == "text/x-python"

digitalhub/utils/generic_utils.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import base64
@@ -20,29 +24,29 @@ from digitalhub.utils.io_utils import read_text
 
 def get_timestamp() -> str:
     """
-    Get the current timestamp timezoned.
+    Get the current timestamp in ISO format with timezone.
 
     Returns
     -------
     str
-        The current timestamp.
+        The current timestamp in ISO format with timezone.
     """
     return datetime.now().astimezone().isoformat()
 
 
 def decode_base64_string(string: str) -> str:
     """
-    Decode a string from base64.
+    Decode a string from base64 encoding.
 
     Parameters
     ----------
     string : str
-        The string to decode.
+        The base64-encoded string to decode.
 
     Returns
     -------
     str
-        The string decoded from base64.
+        The decoded string.
     """
     return base64.b64decode(string).decode()
 
@@ -59,14 +63,14 @@ def encode_string(string: str) -> str:
     Returns
     -------
     str
-        The string encoded in base64.
+        The base64-encoded string.
     """
     return base64.b64encode(string.encode()).decode()
 
 
 def encode_source(path: str) -> str:
     """
-    Read a file and encode in base64 the content.
+    Read a file and encode its content in base64.
 
     Parameters
     ----------
@@ -83,14 +87,14 @@ def encode_source(path: str) -> str:
 
 def requests_chunk_download(source: str, filename: Path) -> None:
     """
-    Download a file in chunks.
+    Download a file from a URL in chunks and save to disk.
 
     Parameters
     ----------
     source : str
-        URL to download the file.
+        URL to download the file from.
     filename : Path
-        Path where to save the file.
+        Path where to save the downloaded file.
 
     Returns
     -------
@@ -105,14 +109,14 @@ def requests_chunk_download(source: str, filename: Path) -> None:
 
 def extract_archive(path: Path, filename: Path) -> None:
     """
-    Extract a zip archive.
+    Extract a zip archive to a specified directory.
 
     Parameters
     ----------
     path : Path
-        Path where to extract the archive.
+        Directory where to extract the archive.
     filename : Path
-        Path to the archive.
+        Path to the zip archive file.
 
     Returns
     -------
@@ -124,12 +128,12 @@ def extract_archive(path: Path, filename: Path) -> None:
 
 class CustomJsonEncoder(json.JSONEncoder):
     """
-    Custom JSON encoder to handle json dumps.
+    Custom JSON encoder to handle serialization of special types.
     """
 
     def default(self, obj: Any) -> Any:
         """
-        Convert an object to json.
+        Convert an object to a JSON-serializable format.
 
         Parameters
         ----------
@@ -139,7 +143,7 @@ class CustomJsonEncoder(json.JSONEncoder):
         Returns
         -------
         Any
-            The object converted to json.
+            The object converted to a JSON-serializable format.
         """
         if isinstance(obj, (int, str, float, list, dict)):
             return obj
@@ -156,24 +160,24 @@ class CustomJsonEncoder(json.JSONEncoder):
 
 def dump_json(struct: Any) -> str:
     """
-    Convert a dict to json.
+    Convert a Python object to a JSON string using CustomJsonEncoder.
 
     Parameters
     ----------
-    struct : dict
-        The dict to convert.
+    struct : Any
+        The object to convert to JSON.
 
     Returns
     -------
     str
-        The json string.
+        The JSON string representation of the object.
     """
     return json.dumps(struct, cls=CustomJsonEncoder)
 
 
 def slugify_string(filename: str) -> str:
     """
-    Sanitize a filename.
+    Sanitize a filename using slugify.
 
     Parameters
     ----------
@@ -183,26 +187,31 @@ def slugify_string(filename: str) -> str:
     Returns
     -------
     str
-        The sanitized filename.
+        The sanitized filename (max length 255).
     """
     return slugify(filename, max_length=255)
 
 
 def import_function(path: Path, handler: str) -> Callable:
     """
-    Import a function from a module.
+    Import a function from a Python module file.
 
     Parameters
     ----------
     path : Path
-        Path where the function source is located.
+        Path to the Python module file.
     handler : str
-        Function name.
+        Name of the function to import.
 
     Returns
     -------
     Callable
-        Function.
+        The imported function.
+
+    Raises
+    ------
+    RuntimeError
+        If the module or function cannot be loaded or is not callable.
     """
     spec = imputil.spec_from_file_location(path.stem, path)
     if spec is None:
@@ -222,7 +231,7 @@ def import_function(path: Path, handler: str) -> Callable:
 
 def list_enum(enum: EnumMeta) -> list[Any]:
     """
-    Get all values of an enum.
+    Get all values of an enum class.
 
     Parameters
     ----------
@@ -231,7 +240,7 @@ def list_enum(enum: EnumMeta) -> list[Any]:
 
     Returns
     -------
-    list[Any]
+    list
         List of enum values.
     """
     vals: MappingProxyType[str, Enum] = enum.__members__
@@ -240,7 +249,8 @@ def list_enum(enum: EnumMeta) -> list[Any]:
 
 def carriage_return_warn(string: str) -> None:
     """
-    Print a warning message if string contains a carriage return (\r\n).
+    Print a warning message if the string contains
+    a carriage return (\r\n).
 
     Parameters
     ----------
@@ -252,22 +262,24 @@ def carriage_return_warn(string: str) -> None:
     None
     """
     if "\r\n" in string:
-        warn("String contains a carriage return. It may not be parsed correctly from remote runtimes.")
+        warn("String contains a carriage return. "
+             "It may not be parsed correctly from remote runtimes.")
 
 
 def read_source(path: str) -> str:
     """
-    Read a file.
+    Read a file and encode its content in base64,
+    warning if carriage returns are present.
 
     Parameters
     ----------
-    path : Path
+    path : str
         Path to the file.
 
     Returns
     -------
     str
-        File content.
+        Base64-encoded file content.
     """
     text = read_text(path)
     carriage_return_warn(text)

digitalhub/utils/git_utils.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: © 2025 DSLab - Fondazione Bruno Kessler
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from __future__ import annotations
 
 import os
@@ -17,6 +21,15 @@ except ImportError as e:
 class GitCredentialsType(Enum):
     """
     Supported git credentials types.
+
+    Attributes
+    ----------
+    USERNAME : str
+        Environment variable name for git username.
+    PASSWORD : str
+        Environment variable name for git password.
+    TOKEN : str
+        Environment variable name for git token.
     """
 
     USERNAME = "GIT_USERNAME"
@@ -26,7 +39,7 @@ class GitCredentialsType(Enum):
 
 def clone_repository(path: Path, url: str) -> None:
     """
-    Clone git repository.
+    Clone a git repository to a local path.
 
     Parameters
     ----------
@@ -49,7 +62,7 @@ def clone_repository(path: Path, url: str) -> None:
 
 def get_checkout_object(url: str) -> str:
     """
-    Get checkout object from url fragment.
+    Get checkout object (branch, tag, commit) from URL fragment.
 
     Parameters
     ----------
@@ -59,18 +72,19 @@ def get_checkout_object(url: str) -> str:
     Returns
     -------
     str
-        Checkout object (branch, tag, commit).
+        Checkout object (branch, tag, commit) or empty string if not present.
     """
     return urlparse(url).fragment
 
 
 def clean_path(path: Path) -> None:
     """
-    Clean path from any files.
+    Remove all files and directories at the given path.
 
     Parameters
     ----------
     path : Path
+        Path to clean.
 
     Returns
     -------
@@ -82,12 +96,12 @@ def clean_path(path: Path) -> None:
 
 def get_git_username_password_from_token(token: str) -> tuple[str, str]:
     """
-    Parse token to get username and password. The token
-    can be one of the following:
+    Parse a token to get username and password for git authentication.
 
-    - GitHub/GitLab personal access token (github_pat_.../glpat...)
-    - GitHub/GitLab access token
-    - Other generic token
+    The token can be one of the following:
+        - GitHub/GitLab personal access token (github_pat_.../glpat...)
+        - GitHub/GitLab access token
+        - Other generic token
 
     Parameters
     ----------
@@ -97,7 +111,7 @@ def get_git_username_password_from_token(token: str) -> tuple[str, str]:
     Returns
     -------
     tuple[str, str]
-        Username and password.
+        Username and password for git authentication.
     """
     # Mutued from mlrun
     if token.startswith("github_pat_") or token.startswith("glpat"):
@@ -107,7 +121,7 @@ def get_git_username_password_from_token(token: str) -> tuple[str, str]:
 
 def add_credentials_git_remote_url(url: str) -> str:
     """
-    Add credentials to git remote url.
+    Add credentials to a git remote URL using environment variables or token.
 
     Parameters
     ----------
@@ -117,7 +131,7 @@ def add_credentials_git_remote_url(url: str) -> str:
     Returns
     -------
     str
-        URL with credentials.
+        URL with credentials included if available.
     """
     url_obj = urlparse(url)
 
@@ -138,7 +152,7 @@ def add_credentials_git_remote_url(url: str) -> str:
 
 def clone_from_url(url: str, path: Path) -> Repo:
     """
-    Clone repository from url. Wraps git.Repo.clone_from.
+    Clone a git repository from a URL to a local path.
 
     Parameters
     ----------
@@ -150,6 +164,6 @@ def clone_from_url(url: str, path: Path) -> Repo:
     Returns
     -------
     Repo
-        Cloned repository.
+        The cloned git repository object.
     """
     return Repo.clone_from(url=url, to_path=path)