2.2.0rc2 (#74)

Author: mikeqfu

docs/source/dirs.rst

@@ -33,6 +33,7 @@ Directory validation
     validate_filename
     get_file_pathnames
     check_files_exist
+    check_relative_pathname
 
 Directory/file management
 -------------------------

pyhelpers/_cache.py

@@ -194,59 +194,6 @@ def _confirmed(prompt=None, confirmation_required=True, resp=False):
         return True
 
 
-def _check_relative_pathname(pathname):
-    """
-    Checks if the pathname is relative to the current working directory.
-
-    This function returns a relative pathname of the input ``pathname`` to the current working
-    directory if ``pathname`` is within the current working directory;
-    otherwise, it returns a copy of the input.
-
-    :param pathname: Pathname (of a file or directory).
-    :type pathname: str | bytes | pathlib.Path
-    :return: A location relative to the current working directory
-        if ``pathname`` is within the current working directory; otherwise, a copy of ``pathname``.
-    :rtype: str
-
-    **Tests**::
-
-        >>> from pyhelpers._cache import _check_relative_pathname
-        >>> from pyhelpers.dirs import cd
-        >>> _check_relative_pathname(".")
-        '.'
-        >>> _check_relative_pathname(cd())
-        '.'
-        >>> _check_relative_pathname("C:\\Program Files")
-        'C:\\Program Files'
-        >>> _check_relative_pathname(pathname="C:/Windows")
-        'C:\\Windows'
-    """
-
-    if isinstance(pathname, (bytes, bytearray)):
-        pathname_ = str(pathname, encoding='utf-8')
-    else:
-        pathname_ = str(pathname)
-
-    abs_pathname = os.path.abspath(pathname_)
-    abs_cwd = os.getcwd()
-
-    if os.name == "nt":  # Handle different drive letters on Windows
-        if os.path.splitdrive(abs_pathname)[0] != os.path.splitdrive(abs_cwd)[0]:
-            return abs_pathname  # Return absolute path if drives differ
-
-    # Check if the pathname is inside the current working directory
-    if os.path.commonpath([abs_pathname, abs_cwd]) == abs_cwd:
-        try:
-            rel_path = os.path.relpath(pathname_)
-        except ValueError:
-            rel_path = copy.copy(pathname_)
-
-    else:
-        rel_path = abs_pathname  # Return original absolute path if outside CWD
-
-    return rel_path
-
-
 def _normalize_pathname(pathname, sep="/", add_slash=False, **kwargs):
     # noinspection PyShadowingNames
     """
@@ -339,6 +286,62 @@ def _add_slashes(pathname, normalized=True, surrounded_by='"'):
     return f'{s}{path}{s}'
 
 
+def _check_relative_pathname(pathname, normalized=True):
+    """
+    Checks if the pathname is relative to the current working directory.
+
+    This function returns a relative pathname of the input ``pathname`` to the current working
+    directory if ``pathname`` is within the current working directory;
+    otherwise, it returns a copy of the input.
+
+    :param pathname: Pathname (of a file or directory).
+    :type pathname: str | bytes | pathlib.Path
+    :param normalized: Whether to normalize the returned pathname; defaults to ``True``.
+    :type normalized: bool
+    :return: A location relative to the current working directory
+        if ``pathname`` is within the current working directory; otherwise, a copy of ``pathname``.
+    :rtype: str
+
+    **Tests**::
+
+        >>> from pyhelpers._cache import _check_relative_pathname
+        >>> from pyhelpers.dirs import cd
+        >>> _check_relative_pathname(pathname=".")
+        '.'
+        >>> _check_relative_pathname(pathname=cd())
+        '.'
+        >>> _check_relative_pathname(pathname="C:/Windows")
+        'C:/Windows'
+        >>> _check_relative_pathname(pathname="C:\\Program Files", normalized=False)
+        'C:\\Program Files'
+    """
+
+    if isinstance(pathname, (bytes, bytearray)):
+        pathname_ = str(pathname, encoding='utf-8')
+    else:
+        pathname_ = str(pathname)
+
+    abs_pathname = os.path.abspath(pathname_)
+    abs_cwd = os.getcwd()
+
+    if os.name == "nt":  # Handle different drive letters on Windows
+        if os.path.splitdrive(abs_pathname)[0] != os.path.splitdrive(abs_cwd)[0]:
+            # Return absolute path if drives differ
+            return _normalize_pathname(abs_pathname) if normalized else abs_pathname
+
+    # Check if the pathname is inside the current working directory
+    if os.path.commonpath([abs_pathname, abs_cwd]) == abs_cwd:
+        try:
+            rel_path = os.path.relpath(pathname_)
+        except ValueError:
+            rel_path = copy.copy(pathname_)
+
+    else:
+        rel_path = abs_pathname  # Return original absolute path if outside CWD
+
+    return _normalize_pathname(rel_path) if normalized else rel_path
+
+
 def _check_file_pathname(name, options=None, target=None):
     # noinspection PyShadowingNames
     """

pyhelpers/dirs/validation.py

@@ -88,7 +88,7 @@ def is_dir(path_to_dir):
 
         for i in range(len(dir_names)):
             try:
-                os.lstat(os.path.join(root_dirname, *dir_names[:i+1]))
+                os.lstat(os.path.join(root_dirname, *dir_names[:i + 1]))
             except OSError as exc:
                 if hasattr(exc, 'winerror'):
                     if exc.winerror == 123:  # ERROR_INVALID_NAME
@@ -365,3 +365,36 @@ def check_files_exist(filenames, path_to_dir, verbose=False, **kwargs):
         rslt = False
 
     return rslt
+
+
+def check_relative_pathname(pathname, normalized=True):
+    """
+    Checks if the pathname is relative to the current working directory.
+
+    This function returns a relative pathname of the input ``pathname`` to the current working
+    directory if ``pathname`` is within the current working directory;
+    otherwise, it returns a copy of the input.
+
+    :param pathname: Pathname (of a file or directory).
+    :type pathname: str | bytes | pathlib.Path
+    :param normalized: Whether to normalize the returned pathname; defaults to ``True``.
+    :type normalized: bool
+    :return: A location relative to the current working directory
+        if ``pathname`` is within the current working directory; otherwise, a copy of ``pathname``.
+    :rtype: str
+
+    **Tests**::
+
+        >>> from pyhelpers._cache import _check_relative_pathname
+        >>> from pyhelpers.dirs import cd
+        >>> _check_relative_pathname(pathname=".")
+        '.'
+        >>> _check_relative_pathname(pathname=cd())
+        '.'
+        >>> _check_relative_pathname(pathname="C:/Windows")
+        'C:/Windows'
+        >>> _check_relative_pathname(pathname="C:\\Program Files", normalized=False)
+        'C:\\Program Files'
+    """
+
+    return _check_relative_pathname(pathname=pathname, normalized=normalized)

pyhelpers/ops/downloads.py

@@ -60,7 +60,7 @@ def is_downloadable(url, request_field='content-type', **kwargs):
 
 
 def _download_file_from_url(response, path_to_file, chunk_multiplier=1, desc=None, bar_format=None,
-                            colour=None, validate=True, **kwargs):
+                            colour=None, validate=True, print_wrap_limit=None, **kwargs):
     # noinspection PyShadowingNames
     """
     Downloads a file from a given HTTP response and saves it to the specified location.
@@ -90,6 +90,11 @@ def _download_file_from_url(response, path_to_file, chunk_multiplier=1, desc=Non
     :param validate: Whether to validate if the downloaded file size matches the expected content
         length; defaults to ``True``.
     :type validate: bool
+    :param print_wrap_limit: Maximum length of the string before splitting into two lines;
+        defaults to ``None``, which disables splitting. If the string exceeds this value,
+        e.g. ``100``, it will be split at (before) ``state_prep`` to improve readability
+        when printed.
+    :type print_wrap_limit: int | None
     :param kwargs: [Optional] Additional parameters passed to `tqdm.tqdm()`_, allowing customisation
         of the progress bar (e.g. ``disable=True`` to hide the progress bar).
 
@@ -150,16 +155,20 @@ def _download_file_from_url(response, path_to_file, chunk_multiplier=1, desc=Non
     except (IOError, TypeError) as e:
         _print_failure_message(e, prefix="Download failed:", verbose=True, raise_error=True)
 
-    _check_saving_path(path_to_file, verbose=True, print_prefix="\t", belated=belated)
+    _check_saving_path(
+        path_to_file, verbose=True, print_prefix="\t", print_wrap_limit=print_wrap_limit,
+        belated=belated)
+
     if validate and (written != file_size) and (file_size > 0):
         raise ValueError(f"Download failed: expected {file_size} bytes, got {written} bytes.")
     else:
         print("Done.")
 
 
 def download_file_from_url(url, path_to_file, if_exists='replace', max_retries=5,
-                           requests_session_args=None, verbose=False, chunk_multiplier=1, desc=None,
-                           bar_format=None, colour=None, validate=True, **kwargs):
+                           requests_session_args=None, verbose=False, print_wrap_limit=None,
+                           chunk_multiplier=1, desc=None, bar_format=None, colour=None,
+                           validate=True, **kwargs):
     # noinspection PyShadowingNames
     """
     Downloads a file from a valid URL.
@@ -185,6 +194,11 @@ def download_file_from_url(url, path_to_file, if_exists='replace', max_retries=5
         the requests session; defaults to ``None``.
     :type requests_session_args: dict | None
     :type verbose: bool | int
+    :param print_wrap_limit: Maximum length of the string before splitting into two lines;
+        defaults to ``None``, which disables splitting. If the string exceeds this value,
+        e.g. ``100``, it will be split at (before) ``state_prep`` to improve readability
+        when printed.
+    :type print_wrap_limit: int | None
     :param chunk_multiplier: A factor by which the default chunk size (1MB) is multiplied;
         this can be adjusted to optimise download performance based on file size; defaults to ``1``.
     :type chunk_multiplier: int | float
@@ -243,7 +257,7 @@ def download_file_from_url(url, path_to_file, if_exists='replace', max_retries=5
 
     if os.path.isfile(path_to_file_) and if_exists != 'replace':
         if verbose:
-            print(f'File "{os.path.basename(path_to_file)}" already exists. Aborting download. '
+            print(f'File "{os.path.basename(path_to_file)}" already exists. Aborting download.\n'
                   f'Set `if_exists="replace"` to update the existing file.')
 
     else:
@@ -272,6 +286,7 @@ def download_file_from_url(url, path_to_file, if_exists='replace', max_retries=5
                     bar_format=bar_format,
                     colour=colour,
                     validate=validate,
+                    print_wrap_limit=print_wrap_limit,
                     **kwargs
                 )
 

pyhelpers/store/utils.py

@@ -10,9 +10,49 @@
 from .._cache import _add_slashes, _check_relative_pathname
 
 
+def _print_wrapped_string(message, filename, end, print_wrap_limit=100):
+    """
+    Prints a string, splitting it into two lines if it exceeds the threshold, with the second half
+    being indented based on the initial indentation level.
+
+    :param message: The string to print.
+    :type message: str
+    :param filename: The filename to be included in the string.
+    :type filename: str
+    :param end:
+    :param print_wrap_limit: The maximum length before splitting.
+    :type print_wrap_limit: int | None
+    """
+
+    if print_wrap_limit:
+        stripped_text = message.lstrip()  # Remove leading spaces for accurate tab count
+        leading_tabs = len(message) - len(stripped_text)
+
+        if len(stripped_text) <= print_wrap_limit:
+            print(message, end=end)
+
+        else:
+            # Find a suitable split point (preferably at a space)
+            split_index = message.find(f'"{filename}"') + len(f'"{filename}"')
+            if message[split_index] == " ":
+                split_index += 1  # Move to space if it exists
+
+            first_part = message[:split_index].rstrip()  # Trim trailing spaces
+            second_part = message[split_index:].lstrip()  # Trim leading spaces
+
+            # Print first part as is
+            print(first_part + " ... ")
+
+            # Print second part with increased indentation (original + 1 extra tab)
+            print("\t" * (leading_tabs + 1) + second_part, end=end)
+
+    else:
+        print(message, end=end)
+
+
 def _check_saving_path(path_to_file, verbose=False, print_prefix="", state_verb="Saving",
-                       state_prep="to", print_suffix="", print_end=" ... ", belated=False,
-                       ret_info=False):
+                       state_prep="to", print_suffix="", print_end=" ... ", print_wrap_limit=None,
+                       belated=False, ret_info=False):
     # noinspection PyShadowingNames
     """
     Verifies a specified file path before saving.
@@ -32,6 +72,11 @@ def _check_saving_path(path_to_file, verbose=False, print_prefix="", state_verb=
     :type print_suffix: str
     :param print_end: String passed to the ``end`` parameter of ``print``; defaults to ``" ... "``.
     :type print_end: str
+    :param print_wrap_limit: Maximum length of the string before splitting into two lines;
+        defaults to ``None``, which disables splitting. If the string exceeds this value,
+        e.g. ``100``, it will be split at (before) ``state_prep`` to improve readability
+        when printed.
+    :type print_wrap_limit: int | None
     :param ret_info: Whether to return file path information; defaults to ``False``.
     :type ret_info: bool
     :return: A tuple containing the relative path and, if ``ret_info=True``, the filename.
@@ -52,6 +97,9 @@ def _check_saving_path(path_to_file, verbose=False, print_prefix="", state_verb=
         >>> path_to_file = cd("tests", "documents", "pyhelpers.pdf")
         >>> _check_saving_path(path_to_file, verbose=True); print("Passed.")
         Saving "pyhelpers.pdf" in "./tests/documents/" ... Passed.
+        >>> _check_saving_path(path_to_file, verbose=True, print_wrap_limit=10); print("Passed.")
+        Updating "pyhelpers.pdf" ...
+            in "./tests/documents/" ... Passed.
         >>> path_to_file = "C:\\Windows\\pyhelpers.pdf"
         >>> _check_saving_path(path_to_file, verbose=True); print("Passed.")
         Saving "pyhelpers.pdf" to "C:/Windows/" ... Passed.
@@ -90,12 +138,15 @@ def _check_saving_path(path_to_file, verbose=False, print_prefix="", state_verb=
 
         if (rel_dir_path == rel_dir_path.parent or rel_dir_path == abs_path_to_file.parent) and (
                 rel_dir_path.absolute().drive == pathlib.Path.cwd().drive):
-            msg = f'{print_prefix}{state_verb} "{filename}"{print_suffix}'
-            print(msg, end=end)
+            message = f'{print_prefix}{state_verb} "{filename}"{print_suffix}'
+            print(message, end=end)
+
         else:
-            msg = (f'{print_prefix}{state_verb} "{filename}" '
-                   f'{state_prep} {_add_slashes(rel_dir_path)}{print_suffix}')
-            print(msg, end=end)
+            message = (f'{print_prefix}{state_verb} "{filename}" '
+                       f'{state_prep} {_add_slashes(rel_dir_path)}{print_suffix}')
+
+            _print_wrapped_string(
+                message=message, filename=filename, end=end, print_wrap_limit=print_wrap_limit)
 
     if ret_info:
         return rel_dir_path, filename