x

Author: xulbux

CHANGELOG.md

@@ -21,6 +21,8 @@
 * the methods `Json.update()` and `Data.set_value_by_path_id()` now intake a dictionary as `update_values` param, instead of a list of strings
 * added a new param to the methods `FormatCodes.remove_ansi()` and `FormatCodes.remove_formatting()`:<br>
   <code>_ignore_linebreaks: *bool* = False</code> whether to include linebreaks in the removal positions or not
+* renamed param `correct_path` in `Path.extend()` and param `correct_paths` in `File.extend_or_make_path()` to `use_closest_match`, since this name describes its functionality better
+* moved the method `extend_or_make_path()` from the `xx_file` module to the `xx_path` module and renamed it to `extend_or_make()`
 
 ## 18.03.2025 `v1.6.8`
 * made it possible to escape formatting codes by putting a slash (`/` *or* `\\`) at the beginning inside the brackets (*e.g.* `[/red]`)

README.md

@@ -55,7 +55,7 @@ from xulbux import rgba, hsla, hexa
 | <h3>[`xx_file`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_file)</h3>                 | advanced working with files (*create files, rename file-extensions, ...*)                          |
 | <h3>[`xx_format_codes`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_format_codes)</h3> | easy pretty printing with custom format codes (*print, inputs, custom format codes to ANSI, ...*)  |
 | <h3>[`xx_json`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_json)</h3>                 | advanced working with json files (*read, create, update, ...*)                                     |
-| <h3>`xx_path`</h3>                                                                               | advanced path operations (*get paths, smart-extend relative paths, delete paths, ...*)             |
+| <h3>[`xx_path`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_path)</h3>                 | advanced path operations (*get paths, smart-extend relative paths, delete paths, ...*)             |
 | <h3>`xx_regex`</h3>                                                                              | generated regex pattern-templates (*match bracket- and quote pairs, match colors, ...*)            |
 | <h3>[`xx_string`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_string)</h3>             | helpful actions when working with strings. (*normalize, escape, decompose, ...*)                   |
 | <h3>`xx_system`</h3>                                                                             | advanced system actions (*restart with message, check installed Python libs, ...*)                 |

src/xulbux/xx_file.py

@@ -4,8 +4,9 @@
 import os as _os
 
 
-class SameContentFileExistsError(FileExistsError):
-    pass
+# YAPF: disable
+class SameContentFileExistsError(FileExistsError): ...
+# YAPF: enable
 
 
 class File:
@@ -40,24 +41,3 @@ def create(file: str, content: str = "", force: bool = False) -> str:
             f.write(content)
         full_path = _os.path.abspath(file)
         return full_path
-
-    @staticmethod
-    def extend_or_make_path(
-        file: str,
-        search_in: str | list[str] = None,
-        prefer_base_dir: bool = True,
-        correct_paths: bool = False,
-    ) -> str:
-        """Tries to find the file and extend the path to be absolute and if the file was not found:\n
-        Generate the absolute path to the file in the CWD or the running program's base-directory.\n
-        ----------------------------------------------------------------------------------------------
-        If the `file` is not found in predefined directories, it will be searched in the `search_in`
-        directory/directories. If the file is still not found, it will return the path to the file in
-        the base-dir per default or to the file in the CWD if `prefer_base_dir` is set to `False`.\n
-        ----------------------------------------------------------------------------------------------
-        If `correct_paths` is true, it is possible to have typos in the `search_in` path/s and it
-        will still find the file if it is under one of those paths."""
-        try:
-            return Path.extend(file, search_in, raise_error=True, correct_path=correct_paths)
-        except FileNotFoundError:
-            return _os.path.join(Path.script_dir, file) if prefer_base_dir else _os.path.join(_os.getcwd(), file)

src/xulbux/xx_json.py

@@ -1,5 +1,6 @@
 from .xx_data import Data
 from .xx_file import File
+from .xx_path import Path
 
 from typing import Any
 import json as _json
@@ -24,7 +25,7 @@ def read(
         additionally. (returns: `[processed_json, original_json]`)"""
         if not json_file.endswith(".json"):
             json_file += ".json"
-        file_path = File.extend_or_make_path(json_file, prefer_base_dir=True)
+        file_path = Path.extend_or_make(json_file, prefer_script_dir=True)
         with open(file_path, "r") as f:
             content = f.read()
         try:
@@ -55,7 +56,7 @@ def create(
         To always overwrite the file, set the `force` parameter to `True`."""
         if not json_file.endswith(".json"):
             json_file += ".json"
-        file_path = File.extend_or_make_path(json_file, prefer_base_dir=True)
+        file_path = Path.extend_or_make(json_file, prefer_script_dir=True)
         File.create(
             file=file_path,
             content=Data.to_str(data, indent, compactness, as_json=True),

src/xulbux/xx_path.py

@@ -5,10 +5,11 @@
 import sys as _sys
 import os as _os
 
+from regex import P
+
 
 # YAPF: disable
-class ProcessNotFoundError(Exception):
-    pass
+class PathNotFoundError(FileNotFoundError): ...
 
 class _Cwd:
     def __get__(self, obj, owner=None):
@@ -39,9 +40,26 @@ class Path:
     """The path to the directory of the current script."""
 
     @staticmethod
-    def extend(path: str, search_in: str | list[str] = None, raise_error: bool = False, correct_path: bool = False) -> str:
-        if path in (None, ""):
-            return path
+    def extend(
+        rel_path: str,
+        search_in: str | list[str] = None,
+        raise_error: bool = False,
+        use_closest_match: bool = False,
+    ) -> Optional[str]:
+        """Tries to locate and extend a relative path to an absolute path.\n
+        --------------------------------------------------------------------------------
+        If the `rel_path` couldn't be located in predefined directories, it will be
+        searched in the `search_in` directory/s. If the `rel_path` is still not found,
+        it returns `None` or raises a `PathNotFoundError` if `raise_error` is true.\n
+        --------------------------------------------------------------------------------
+        If `use_closest_match` is true, it is possible to have typos in the `search_in`
+        path/s and it will still find the file if it is under one of those paths."""
+        if rel_path in (None, ""):
+            if raise_error:
+                raise PathNotFoundError("Path is empty.")
+            return None
+        elif _os.path.isabs(rel_path):
+            return rel_path
 
         def get_closest_match(dir: str, part: str) -> Optional[str]:
             try:
@@ -56,7 +74,7 @@ def find_path(start: str, parts: list[str]) -> Optional[str]:
             for part in parts:
                 if _os.path.isfile(current):
                     return current
-                closest_match = get_closest_match(current, part) if correct_path else part
+                closest_match = get_closest_match(current, part) if use_closest_match else part
                 current = _os.path.join(current, closest_match) if closest_match else None
                 if current is None:
                     return None
@@ -71,13 +89,13 @@ def expand_env_path(p: str) -> str:
                     parts[i] = _os.environ[parts[i].upper()]
             return "".join(parts)
 
-        path = _os.path.normpath(expand_env_path(path))
-        if _os.path.isabs(path):
-            drive, rel_path = _os.path.splitdrive(path)
+        rel_path = _os.path.normpath(expand_env_path(rel_path))
+        if _os.path.isabs(rel_path):
+            drive, rel_path = _os.path.splitdrive(rel_path)
             rel_path = rel_path.lstrip(_os.sep)
             search_dirs = (drive + _os.sep) if drive else [_os.sep]
         else:
-            rel_path = path.lstrip(_os.sep)
+            rel_path = rel_path.lstrip(_os.sep)
             base_dir = Path.script_dir
             search_dirs = (
                 _os.getcwd(),
@@ -92,15 +110,42 @@ def expand_env_path(p: str) -> str:
             full_path = _os.path.join(search_dir, rel_path)
             if _os.path.exists(full_path):
                 return full_path
-            match = find_path(search_dir, path_parts) if correct_path else None
+            match = find_path(search_dir, path_parts) if use_closest_match else None
             if match:
                 return match
         if raise_error:
-            raise FileNotFoundError(f"Path '{path}' not found in specified directories.")
-        return _os.path.join(search_dirs[0], rel_path)
+            raise PathNotFoundError(f"Path '{rel_path}' not found in specified directories.")
+        return None
+
+    @staticmethod
+    def extend_or_make(
+        rel_path: str,
+        search_in: str | list[str] = None,
+        prefer_script_dir: bool = True,
+        use_closest_match: bool = False,
+    ) -> str:
+        """Tries to locate and extend a relative path to an absolute path, and if the `rel_path`
+        couldn't be located, it generates a path, as if it was located.\n
+        -----------------------------------------------------------------------------------------
+        If the `rel_path` couldn't be located in predefined directories, it will be searched in
+        the `search_in` directory/s. If the `rel_path` is still not found, it will makes a path
+        that points to where the `rel_path` would be in the script directory, even though the
+        `rel_path` doesn't exist there. If `prefer_script_dir` is false, it will instead make a
+        path that points to where the `rel_path` would be in the CWD.\n
+        -----------------------------------------------------------------------------------------
+        If `use_closest_match` is true, it is possible to have typos in the `search_in` path/s
+        and it will still find the file if it is under one of those paths."""
+        try:
+            return Path.extend(rel_path, search_in, raise_error=True, use_closest_match=use_closest_match)
+        except PathNotFoundError:
+            return _os.path.join(Path.script_dir, rel_path) if prefer_script_dir else _os.path.join(_os.getcwd(), rel_path)
 
     @staticmethod
     def remove(path: str, only_content: bool = False) -> None:
+        """Removes the directory or the directory's content at the specified path.\n
+        -----------------------------------------------------------------------------
+        Normally it removes the directory and its content, but if `only_content` is
+        true, the directory is kept and only its contents are removed."""
         if not _os.path.exists(path):
             return None
         if not only_content:

src/xulbux/xx_system.py

@@ -8,9 +8,6 @@
 
 
 # YAPF: disable
-class ProcessNotFoundError(Exception):
-    pass
-
 class _IsElevated:
     def __get__(self, obj, owner=None):
         try: