digitalhub 0.13.0b2__py3-none-any.whl → 0.13.0b4__py3-none-any.whl

digitalhub/utils/file_utils.py

@@ -16,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
@@ -25,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
     ----------
@@ -41,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()
@@ -50,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
     ----------
@@ -60,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
     ----------
@@ -76,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
     ----------
@@ -101,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
     ----------
@@ -111,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
@@ -120,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
     ----------
@@ -130,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)
@@ -172,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"]
@@ -214,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"
@@ -233,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

@@ -24,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()
 
@@ -63,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
     ----------
@@ -87,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
     -------
@@ -109,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
     -------
@@ -128,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
         ----------
@@ -143,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
@@ -160,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
     ----------
@@ -187,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:
@@ -226,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
     ----------
@@ -235,7 +240,7 @@ def list_enum(enum: EnumMeta) -> list[Any]:
 
     Returns
     -------
-    list[Any]
+    list
         List of enum values.
     """
     vals: MappingProxyType[str, Enum] = enum.__members__
@@ -244,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
     ----------
@@ -256,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

@@ -21,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"
@@ -30,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
     ----------
@@ -53,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
     ----------
@@ -63,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
     -------
@@ -86,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
     ----------
@@ -101,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"):
@@ -111,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
     ----------
@@ -121,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)
 
@@ -142,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
     ----------
@@ -154,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)

digitalhub/utils/io_utils.py

@@ -15,14 +15,14 @@ import yaml
 
 def write_yaml(filepath: str | Path, obj: dict | list[dict]) -> None:
     """
-    Write a dict or a list of dict to a yaml file.
+    Write a dict or a list of dicts to a YAML file.
 
     Parameters
     ----------
-    filepath : str | Path
-        The yaml file path to write.
-    obj : dict
-        The dict to write.
+    filepath : str or Path
+        The YAML file path to write.
+    obj : dict or list of dict
+        The dict or list of dicts to write.
 
     Returns
     -------
@@ -61,7 +61,7 @@ def write_text(filepath: Path, text: str) -> None:
 
 class NoDatesSafeLoader(yaml.SafeLoader):
     """
-    Loader implementation to exclude implicit resolvers.
+    Loader implementation to exclude implicit resolvers for YAML timestamps.
 
     Taken from https://stackoverflow.com/a/37958106
     """
@@ -69,16 +69,17 @@ class NoDatesSafeLoader(yaml.SafeLoader):
     @classmethod
     def remove_implicit_resolver(cls, tag_to_remove: str) -> None:
         """
-        Remove implicit resolvers for a particular tag
+        Remove implicit resolvers for a particular tag.
+
         Takes care not to modify resolvers in super classes.
         We want to load datetimes as strings, not dates, because we
-        go on to serialise as json which doesn't have the advanced types
-        of yaml, and leads to incompatibilities down the track.
+        go on to serialize as JSON which doesn't have the advanced types
+        of YAML, and leads to incompatibilities down the track.
 
         Parameters
         ----------
         tag_to_remove : str
-            The tag to remove
+            The tag to remove.
 
         Returns
         -------
@@ -98,17 +99,17 @@ NoDatesSafeLoader.remove_implicit_resolver("tag:yaml.org,2002:timestamp")
 
 def read_yaml(filepath: str | Path) -> dict | list[dict]:
     """
-    Read a yaml file and return a dict or a list of dict.
+    Read a YAML file and return its content as a dict or a list of dicts.
 
     Parameters
     ----------
-    filepath : str | Path
-        The yaml file path to read.
+    filepath : str or Path
+        The YAML file path to read.
 
     Returns
     -------
-    dict | list[dict]
-        The yaml file content.
+    dict or list of dict
+        The YAML file content.
     """
     try:
         with open(filepath, "r", encoding="utf-8") as in_file:
@@ -123,16 +124,16 @@ def read_yaml(filepath: str | Path) -> dict | list[dict]:
 
 def read_text(filepath: str | Path) -> str:
     """
-    Read a file and return the text.
+    Read a file and return its text content.
 
     Parameters
     ----------
-    filepath : str | Path
+    filepath : str or Path
         The file path to read.
 
     Returns
     -------
     str
-        The file content.
+        The file content as a string.
     """
     return Path(filepath).read_text(encoding="utf-8")