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

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")

digitalhub/utils/uri_utils.py

@@ -13,7 +13,7 @@ from digitalhub.utils.generic_utils import list_enum
 
 class S3Schemes(Enum):
     """
-    S3 schemes.
+    S3 URI schemes.
     """
 
     S3 = "s3"
@@ -24,7 +24,7 @@ class S3Schemes(Enum):
 
 class LocalSchemes(Enum):
     """
-    Local schemes.
+    Local URI schemes.
     """
 
     LOCAL = ""
@@ -32,7 +32,7 @@ class LocalSchemes(Enum):
 
 class InvalidLocalSchemes(Enum):
     """
-    Local schemes.
+    Invalid local URI schemes.
     """
 
     FILE = "file"
@@ -41,7 +41,7 @@ class InvalidLocalSchemes(Enum):
 
 class RemoteSchemes(Enum):
     """
-    Remote schemes.
+    Remote URI schemes.
     """
 
     HTTP = "http"
@@ -52,7 +52,7 @@ class RemoteSchemes(Enum):
 
 class SqlSchemes(Enum):
     """
-    Sql schemes.
+    SQL URI schemes.
     """
 
     SQL = "sql"
@@ -61,7 +61,7 @@ class SqlSchemes(Enum):
 
 class GitSchemes(Enum):
     """
-    Git schemes.
+    Git URI schemes.
     """
 
     GIT = "git"
@@ -71,7 +71,7 @@ class GitSchemes(Enum):
 
 class SchemeCategory(Enum):
     """
-    Scheme types.
+    URI scheme categories.
     """
 
     S3 = "s3"
@@ -83,17 +83,17 @@ class SchemeCategory(Enum):
 
 def map_uri_scheme(uri: str) -> str:
     """
-    Map an URI scheme to a common scheme.
+    Map a URI scheme to a common scheme category.
 
     Parameters
     ----------
     uri : str
-        URI.
+        URI string.
 
     Returns
     -------
     str
-        Mapped scheme type.
+        Mapped scheme category (e.g., 'local', 'remote', 's3', 'sql', 'git').
 
     Raises
     ------
@@ -122,118 +122,118 @@ def map_uri_scheme(uri: str) -> str:
 
 def has_local_scheme(uri: str) -> bool:
     """
-    Check if uri is local.
+    Check if a URI has a local scheme.
 
     Parameters
     ----------
     uri : str
-        Uri of some source.
+        URI string.
 
     Returns
     -------
     bool
-        True if uri is local.
+        True if the URI is local, False otherwise.
     """
     return map_uri_scheme(uri) == SchemeCategory.LOCAL.value
 
 
 def has_remote_scheme(uri: str) -> bool:
     """
-    Check if uri is remote.
+    Check if a URI has a remote scheme.
 
     Parameters
     ----------
     uri : str
-        Uri of some source.
+        URI string.
 
     Returns
     -------
     bool
-        True if uri is remote.
+        True if the URI is remote, False otherwise.
     """
     return map_uri_scheme(uri) == SchemeCategory.REMOTE.value
 
 
 def has_s3_scheme(uri: str) -> bool:
     """
-    Check if uri is s3.
+    Check if a URI has an S3 scheme.
 
     Parameters
     ----------
     uri : str
-        Uri of some source.
+        URI string.
 
     Returns
     -------
     bool
-        True if uri is s3.
+        True if the URI is S3, False otherwise.
     """
     return map_uri_scheme(uri) == SchemeCategory.S3.value
 
 
 def has_sql_scheme(uri: str) -> bool:
     """
-    Check if uri is sql.
+    Check if a URI has an SQL scheme.
 
     Parameters
     ----------
     uri : str
-        Uri of some source.
+        URI string.
 
     Returns
     -------
     bool
-        True if uri is sql.
+        True if the URI is SQL, False otherwise.
     """
     return map_uri_scheme(uri) == SchemeCategory.SQL.value
 
 
 def has_git_scheme(uri: str) -> bool:
     """
-    Check if uri is git.
+    Check if a URI has a git scheme.
 
     Parameters
     ----------
     uri : str
-        Uri of some source.
+        URI string.
 
     Returns
     -------
     bool
-        True if uri is git.
+        True if the URI is git, False otherwise.
     """
     return map_uri_scheme(uri) == SchemeCategory.GIT.value
 
 
 def has_zip_scheme(uri: str) -> bool:
     """
-    Check if uri is zip.
+    Check if a URI has a zip scheme.
 
     Parameters
     ----------
     uri : str
-        Uri of some source.
+        URI string.
 
     Returns
     -------
     bool
-        True if uri is zip.
+        True if the URI is zip, False otherwise.
     """
     return uri.startswith("zip+")
 
 
 def get_filename_from_uri(uri: str) -> str:
     """
-    Get filename from uri.
+    Get the filename from a URI.
 
     Parameters
     ----------
     uri : str
-        Uri of some source.
+        URI string.
 
     Returns
     -------
     str
-        Filename.
+        Filename extracted from the URI.
     """
     return unquote(urlparse(uri).path).split("/")[-1]

{digitalhub-0.13.0b2.dist-info → digitalhub-0.13.0b3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalhub
-Version: 0.13.0b2
+Version: 0.13.0b3
 Summary: Python SDK for Digitalhub
 Project-URL: Homepage, https://github.com/scc-digitalhub/digitalhub-sdk
 Author-email: Fondazione Bruno Kessler <digitalhub@fbk.eu>, Matteo Martini <mmartini@fbk.eu>