FileHiker 0.3.9.2__py3-none-any.whl

filehiker/filehiker.py

@@ -0,0 +1,833 @@
+#! /usr/bin/env python
+#  file        : 20250406°0911 filehiker.py
+#  summary     : This finds a filesystem item's neighbour relative to a given path. Find
+#                 either the next or the previous neighbour, depending on the direction flag.
+#  license     : BSD 3-Clause | © 2025 – 2026 Norbert C. Maier
+#  status      : Applicable
+
+
+import bisect
+import fnmatch
+import itertools
+import os, sys
+import pathlib                                                          # Path
+import typing                                                           # Optional, Union
+
+
+## \register class 20260810°0911 FileHiker <del>20090725°0144 IrunFind</del>
+#  @brief    Class to find the neighbour of a given target inside a given base path
+#  @details  If the given path does not exist, then find the nearest existing target according the sort order
+#  \remark   Code implented after file 20260808°0811 probe_327_walk.py
+#  \remark   Delete <del>Rename</del> class IrunFind to FileHiker [chg 20260810°0811]
+class FileHiker :
+
+    ## \register Method 20260810°0915 <del>20090725°0147 constructor</del>
+    #  \brief    …
+    #  \param    verbose — Flag telling verbose mode on or off
+    def __init__ ( self
+                  , basepath = ''
+                   , direction = True
+                    , ignorewcs = None
+                     , verbose = False
+                      , selftest = False                                # Only use from __main__.py! Ugly flag, but easiest solution, see issue 20260811°1021 'Command `python.exe -m filehiker`'
+                       ) :
+
+        # (1) Complete properties [seq 20260811°0911]
+        #  This are instance level properties, they will override the class level attributed possibly defined on top of the class
+
+        ## \register prop 20260811°0913
+        ## \brief  Direction flag
+        self.__bDirection = direction
+
+        ## \register prop 20260811°0915
+        ## \brief  Direction flag
+        self.__bVerbose = verbose
+
+        ## \register prop 20250729°0911
+        #  \brief    The default ignore list
+        self.__lstIgnorePats = ignorewcs \
+                              if ignorewcs != None \
+                               else [ '.git'
+                                     , '.hg'
+                                      , '.svn'
+                                       , '.vs'                          # Visual Studio
+                                        , '.vscode'
+                                         , '__*__'                      # E.g. '__pycache__'
+                                          , '__*__.*'                   # This will unfortunately also hit '__init__.py' and '__main__.py' (see todo 20260811°0831 'Finetune ignore feature')
+                                           , '^^*^^'                    # Specific for self test
+                                            , '^^*^^.*'                 # Specific for self test
+                                             , 'Debug*'                 # Formerly 'Debug' plus 'Debug_TMP' and possibly 'ifonor'
+                                              , 'obj'
+                                               , 'tags'
+                                                , 'temp'
+                                                 , 'tmp'
+                                                  ]
+
+        ## \register prop 20260811°0917
+        #  \brief    The base path
+        self.__sBasePath = basepath
+
+        # (2) Notification [seq 20260811°0919]
+        if self.__bVerbose:
+            sMsg = '[Dbg_4111] *** Here comes a new FileHiker instance …'
+            print(sMsg)
+
+        # (3) Retrieve the decision aids [seq 20260811°0921]
+        # (3.1) Is given basepath a relative one? [seq 20260811°0923] When and why shall this happen?!
+        bRelativeBasePath = False if os.path.isabs(self.__sBasePath) else True
+
+        # (3.2) Is this a selftest run? [seq 20260811°0925]
+        bIsSelftest = selftest                                          # Testing for `os.path.basename(__file__) == '__main.py__'` won´t work here!
+
+        # (3.3) Provide the involved folders [seq 20260811°0927]
+        sCwd = FileHiker.normaleis(os.getcwd())
+        sModLoc = FileHiker.normaleis(os.path.abspath(os.path.dirname(__file__)))  # Full path of current module — Interposing abspath() is defensive
+
+        # (4.1) Notification [seq 20260811°0933]
+        sMsg = f'[Dbg_4113] Basepath is empty or relative' \
+              + f'\n            • Selftest flag   = {bIsSelftest}' \
+               + f'\n            • Relative flag   = {bRelativeBasePath}' \
+                + f'\n            • FileHiker home  = {sModLoc}' \
+                 + f'\n            • CWD             = {sCwd}' \
+                  + f'\n            • BasePath        = {self.__sBasePath}' \
+                   + f'\n            • Direction       = {'Forward' if self.__bDirection else 'Backward'}' \
+                    + f'\n            • Ignore list     = {self.__lstIgnorePats}'
+        print(sMsg)
+
+        # note 20260811°1011 'About BasePath determination' — Draft, possibly not really followed!
+        #  Selftest with parameter 'selftest' is just a proposal, not (yet?) implemented
+        # +——————————————————————+————————————————————+———————————————————————+————————————————————+
+        # |                      | Empty basepath     | Relative basepath     | Absolute basepath  |
+        # +——————————————————————+————————————————————+———————————————————————+————————————————————+
+        # | Regular call by some | CWD                | CWD plus              | Absolute path      |
+        # |  other script        |                    |  relative path        |  as is             |
+        # +——————————————————————+————————————————————+———————————————————————+————————————————————+
+        # | Selftest             | FileHiker folder   | FileHiker folder      | Absolute path      |
+        # |                      |  join 'cases'      |  join relative path   |  as is             |
+        # +——————————————————————+————————————————————+———————————————————————+————————————————————+
+        # | # Selftest with      | FileHiker folder   | FileHiker folder      | Absolute path      |
+        # | #  param 'selftest'  |  join CWD          |  join relative path   |  as is             |
+        # +——————————————————————+————————————————————+———————————————————————+————————————————————+
+
+        # (4) Determine base path [seq 20260811°0931]
+        # The determination shall go by the following rules:
+        #  1. If given basepath is relative, treat it like an empty basepath with the relative part attached
+        #  2. If given basepath is empty, make it the folder where from Python was called, means the CWD
+        #  3. If it is a selftest, make it the folder where the package resides (which is easy
+        #      to know in a development installation, harder to know in a PyPi installation)
+        if self.__sBasePath == '' or bRelativeBasePath:
+            pass
+
+        # (5) Implement just some simple first logic [seq 20260811°0941]
+        if self.__sBasePath == '':
+
+            if bIsSelftest:
+                sPth = os.path.join(sModLoc, 'cases')
+                sPth = FileHiker.normaleis(sPth)
+                self.__sBasePath = sPth
+            else:
+                self.__sBasePath = sCwd
+
+            FileHiker.normaleis(self.__sBasePath)
+            sMsg = f'[Dbg_4115] Set BasePath = {self.__sBasePath}'
+            print(sMsg)
+
+
+        return
+
+
+    ## \entry  Private method 20260806°1511 find_left_neighbour
+    #  \brief  Backward walking work horse …
+    #  \param  self — Mandatory object
+    #  \param  sTgt_FolderName — The target folder
+    #  \param  sTgt_ElementName — The target filename, if target is a folder, this is blank
+    #  \return The wanted left neighbour
+    def __find_left_neighbour ( self
+                               , sTgt_FolderName                        #
+                                , sTgt_ElementName                      #
+                                 ) :
+
+        """
+        Returns the left neighbour (previous item in global alphabetical order)
+        of the target file/directory, searching upward through the file system,
+        but not above base_path. If no left neighbour is found, wraps around to
+        the deepest last item of base_path.
+        """
+
+        # (L.4) Search the left neighbour [seq 20260806°1521]
+        while True :
+
+            # (L.4.1) Pessimistic predetermination [line 20260806°1522]
+            sNeighbour = None
+
+            # (L.4.2) Retrieve children of currently inspected folder [condi 20260806°1523]
+            try :
+                children = self.__get_listing(sTgt_FolderName)          # [line 20260808°1111]
+            except FileNotFoundError :
+                sMsg = f'[Err_4117] Fatal — Directory not found: "{sTgt_FolderName}"'
+                raise FileNotFoundError(sMsg)
+
+            # (L.4.3) … [condi 20260806°1525]
+            if sTgt_ElementName in children :
+
+                # (L.4.3.1) Target is in current folder [seq 20260806°1527]
+                # (L.4.3.1.1) … [seq 20260806°1531]
+                target_index = children.index(sTgt_ElementName)
+
+                # (L.4.3.1.2) Is the wanted neighbour in this directory? [condi 20260806°1533]
+                if target_index > 0 :
+
+                    # (L.4.3.1.2.1) Yes, left sibling is present [seq 20260806°1534]
+                    # (L.4.3.1.2.1.1) Retrieve the neighbour [seq 20260806°1535]
+                    left_sibling = children[target_index - 1]
+                    left_sibling_path = os.path.join(sTgt_FolderName, left_sibling)
+
+                    # (L.4.3.1.2.1.2) Is it a file or a folder? [condi 20260806°1537]
+                    if os.path.isdir(left_sibling_path) :
+                        sNeighbour = self.__get_deepest_last_item(left_sibling_path)  # 🚀 Found
+                        ###sNeighbour = left_sibling_path               # 🚀 Found — Deliver directory itself, not deepest child [chg 20260818°0821´01]
+                    else :
+                        sNeighbour = left_sibling_path                  # 🚀 Found
+
+                else :
+
+                    # (L.4.3.1.2.2) Neighbour is not in this directory [seq 20260806°1540]
+                    # Note : We don´t even need ask `if sTgt_FolderName == base_path`, the both cases are satisfied here
+                    #         Asking `if sTgt_FolderName == base_path` were only useful if we want skip outputting the base path
+                    #         and immediately wrap with get_deepest_last_item(base_path), as was the case in the initial versions
+                    # Remember : todo 20260808°0921 'Clean up the slash mess'
+                    sNeighbour = sTgt_FolderName                        # 🚀 Found — [line 20260806°1621] [chg 20260808°0913] Heureka! Just deliver the base folder itself.
+
+            else :
+
+                # (L.4.3.2) Target is not found in current folder, so move up [seq 20260806°1551]
+                # (L.4.3.2.1) Are we in the base folder? [condi 20260806°1552]
+                if sTgt_FolderName == self.__sBasePath :
+                    # (L.4.3.2.1.1) Yes, we are in base folder, thus wrap around — Find deepest last item of base_path [seq 20260806°1553]
+                    sNeighbour =  self.__get_deepest_last_item(self.__sBasePath)  # 🚀 Found
+                else :
+                    # (L.4.3.2.1.2) No, we are not in base folder — Continue searching [seq 20260806°1555]
+                    sTgt_ElementName = os.path.basename(sTgt_FolderName)
+                    sTgt_FolderName = os.path.dirname(sTgt_FolderName)
+
+            # (L.4.4) Finished? Deliver result or continue searching [condi 20260806°1557]
+            if sNeighbour :
+                return sNeighbour
+
+
+    ## \entry   Private method 20260806°1811 find_right_neighbour
+    #  \brief   Forward walking work horse — Shall be symmetric to find_left_neighbour but is not
+    #             — Discontinued in favour of method 20260818°0911 __find_right_neighbouur_4
+    #  \param   self — The mandatory object
+    #  \param   sTgt_FolderName — The root of the search area
+    #  \param   sTgt_ElementName — The item inside root for which the right neighbour is wanted
+    #  \return  The wanted right neighbour
+    #  \note    See issue 20260818°0811 'Process order forward not as wanted'
+    def __find_right_neighbour(self, sTgt_FolderName, sTgt_ElementName) :  # [chg 20260818°0831´05] Formerly `__find_right_neighbour(self, s_target_path)`
+
+        """
+        Returns the right neighbour (next item in global alphabetical order)
+        of the target file/directory, searching upward through the file system,
+        but not above base_path. If no right neighbour is found, wraps around to
+        the deepest first item of base_path.
+        """
+
+        # (R.4) Search the right neighbour [seq 20260806°1821]
+        while True :
+
+            # (R.4.1) Pessimistic predetermination [line 20260806°1822]
+            sNeighbour = None
+
+            # (R.4.2) Retrieve children of the currently inspected folder [condi 20260806°1823]
+            try :
+                children = self.__get_listing(sTgt_FolderName)          # [line 20260808°1113]
+            except FileNotFoundError :
+                sMsg = f'[Err_4119] Fatal — Directory not found: "{sTgt_FolderName}"'
+                raise FileNotFoundError(sMsg)
+
+            # (R.4.3) … [condi 20260806°1825]
+            if sTgt_ElementName in children :
+
+                # (R.4.3.1) Target is in current folder [seq 20260806°1827]
+                # (R.4.3.1.1) … [seq 20260806°1831]
+                target_index = children.index(sTgt_ElementName)
+
+                # (R.4.3.1.2) Is the wanted neighbour in this directory? [condi 20260806°1833]
+                if target_index < len(children) - 1 :
+
+                    # (R.4.3.1.2.1) Yes, right sibling present [seq 20260806°1834]
+                    # (R.4.3.1.2.1.1) Retrieve the neighbour [seq 20260806°1835]
+                    right_sibling = children[target_index + 1]
+                    right_sibling_path = os.path.join(sTgt_FolderName, right_sibling)
+
+                    # (R.4.3.1.2.1.2) Is it a file or a folder? [condi 20260806°1837]
+                    if os.path.isdir(right_sibling_path) :
+                        sNeighbour = self.__get_first_folder_item(right_sibling_path)  # 🚀 Found
+                        ###sNeighbour = right_sibling_path              # 🚀 Found — Deliver directory itself, not deepest child [chg 20260818°0821´02]
+                    else :
+                        sNeighbour = right_sibling_path                 # 🚀 Found
+
+                else :
+
+                    # (R.4.3.1.2.2) Neighbour is not in this directory [seq 20260806°1840]
+                    # Note : We don´t even need ask `if sTgt_FolderName == base_path`, the both cases are satisfied here
+                    #         Asking `if sTgt_FolderName == base_path` were only useful if we want skip outputting the base path
+                    #         and immediately wrap with get_deepest_last_item(base_path), as was the case in the initial versions
+                    # Remember : todo 20260808°0921 'Clean up the slash mess'
+                    sNeighbour = sTgt_FolderName                        # 🚀 Found — Empiric experiment [chg 20260808°0911] Heureka! Also deliver the base folder itself
+
+            else:
+
+                # (R.4.3.2) Target is not found in current folder, so move up [seq 20260806°1851]
+                # (R.4.3.2.1) Are we in the base folder? [condi 20260806°1552]
+                if sTgt_FolderName == self.__sBasePath :
+                    # (R.4.3.2.1.1) Yes, we are in base folder, thus wrap around — Find deepest first item of base_path [seq 20260806°1853]
+                    sNeighbour =  self.__get_first_folder_item(self.__sBasePath)  # 🚀 Found
+                else :
+                    # (R.4.3.2.1.2) No, we are not in base folder — Continue searching [seq 20260806°1855]
+                    sTgt_ElementName = os.path.basename(sTgt_FolderName)
+                    sTgt_FolderName = os.path.dirname(sTgt_FolderName)
+
+            # (R.4.4) Finished? Deliver result or continue searching [condi 20260806°1857]
+            if sNeighbour :
+                return sNeighbour
+
+
+    ## \entry   Private method 20260818°0911 __find_right_neighbouur_4 (replacing 20260806°1811)
+    #  \brief   Forward walking work horse — Outputs symmetric to find_left_neighbour
+    #  \details This is horrible code, just it seems to work as wanted. Has to be heavily refactored
+    #  \param   self — The mandarory objedt
+    #  \param   given_path — The target for which the right neighbour is wanted
+    #  \param   recursive — Flag telling whether it is the original call or a recursive one
+    #  \return  The wanted right neighbour
+    #  \note    See issue 20260818°0811 'Process order forward not as wanted'
+    #  \note    See issue 20260818°1131 'Refactor __find_right_neighbouur_4'
+    def __find_right_neighbouur_4 ( self
+                                   , given_path                        # Must be normalized
+                                    , recursive = False
+                                     ) :
+
+        # () Set pessibmistic default [line 20260818°0913]
+        neighbour = None
+
+        # () Breakpoint [line 20260818°0914]
+        if given_path.endswith('README.md') :
+            pass
+
+        # () Extract the directory and the base name of the given path [line 20260818°0915]
+        dir_name, base_name = os.path.split(given_path)
+
+        # (.) Is given_path a directory? [condi 20260818°0917]
+        if os.path.isdir(given_path) :
+
+            # (.1) Yes — Given path is a directory [seq 20260818°0919]
+            # (.1.1) Retrieve children of the given path [seq 20260818°0921]
+            items = self.__get_listing(given_path)                      # Alphabetically sorted list, cleaned from ignored items
+
+            # (.1.2) Has the given folder children? [condi 20260818°0923]
+            if len(items) > 0 :
+                # () Yes — Given folder has at least one child [seq 20260818°0925]
+                neighbour = os.path.join(given_path, items[0])
+                return neighbour                                        # 🚀
+            else :
+
+                # () No — The given folder has no children [seq 20260818°0927]
+                # (.1) … [seq 20260818°0929]
+                if recursive :                                          # Just a try — Happened to work
+                    return given_path                                   # 🚀
+
+                # (.2) Peek into it to see whether it has children, if no children then get next peer [seq 20260818°0931]
+                dirnam, basenam = os.path.split(dir_name)
+                childs = self.__get_listing(dirnam)
+                ndx = childs.index(basenam)
+
+                # (.3) … [condi 20260818°0933]
+                if len(childs) < ndx + 2 :                              # No more right neighbour? Then go back the parents until …
+                    dnam, bnam = os.path.split(dirnam)
+                    parents = self.__get_listing(dnam)
+                    ndx = parents.index(bnam)
+                    x1 = parents[ndx + 1]
+                    x2 = FileHiker.normaleis(os.path.join(dnam, x1))
+                    return x2                                           # 🚀
+
+                # (.4) … [seq 20260818°0935]
+                x1 = childs[ndx + 1]
+                x2 = os.path.join(dirnam, x1)
+                return x2                                               # 🚀
+
+        else :
+
+            # (.1) No — Get it´s peers [seq 20260818°0937]
+            # (.1.1) … [seq 20260818°0939]
+            items = self.__get_listing(dir_name)                        # The peers of current file
+            ndx = items.index(base_name)
+
+            # (.1.2) … [seq 20260818°0941]
+            if len(items) > ndx + 1 :
+
+                # (.1.2.1) Yes — … [seq 20260818°0943]
+                # (.1.2.1.1)  [seq 20260818°0945]
+                nbr1 = os.path.join(dir_name, items[ndx + 1])
+                nbr2 = FileHiker.normaleis(nbr1)
+
+                # (.1.2.1.2) … [condi 20260818°0947]
+                if os.path.isdir(nbr2) :                                # Is folder
+
+                    # (.1) Yes — … [seq 20260818°0949]
+                    # (.1.1) … [condi 20260818°0951]
+                    if not recursive :                                  # Empirical try
+                        return nbr2                                     # 🚀
+
+                    # (.1.2) … [condi 20260818°0953]
+                    nbr3 = self.__find_right_neighbouur_4(nbr2, True)
+                    if nbr3 :
+                        neighbour = nbr3
+                    else :
+                        neighbour = nbr2
+
+                else :
+
+                    # (.2) No — … [seq 20260818°0955]
+                    neighbour = nbr2
+
+                # () … [seq 20260818°0957]
+                return neighbour                                        # 🚀
+
+            else :
+
+                # (.1.2.2) No — … [seq 20260818°1011]
+                # () … [seq 20260818°1013]
+                sNext = None
+                currdir = dir_name
+
+                # () … [loop 20260818°1015]
+                while not sNext :
+
+                    # () Turn around? [condi 20260818°1017]
+                    if currdir + '/' == self.get_BasePath() :
+                        return self.get_BasePath()                      # 🚀
+
+                    # () Find next from the peers of parents (aunts) [seq 20260818°1021]
+                    dirnm, basenm = os.path.split(currdir)
+                    peers = self.__get_listing(dirnm)
+                    ndx = peers.index(basenm)
+
+                    # () … [seq 20260818°1023]
+                    if len(peers) > ndx + 1 :                           # No more right neighbour? Then go back the parents until …
+                        # ()  Found … [seq 20260818°1025]
+                        sNext = FileHiker.normaleis(os.path.join(dirnm, peers[ndx + 1]))
+                        return sNext                                    # 🚀
+                    else :
+                        # () Continue diving … [seq 20260818°1027]
+                        currdir = dirnm
+
+        # () Find the index of the given base name in the sorted list [seq 20260818°1031]
+        try:
+            current_index = sorted_items.index(base_name)
+        except ValueError:
+            raise ValueError(f"[Err_4129] The item {base_name} does not exist in the directory {dir_name}.")
+
+        # () Determine the next item [condi 20260818°1033]
+        if current_index + 1 < len(sorted_items):
+            # () Yes — Determine the next item [seq 20260818°1035]
+            # (.1) … [seq 20260818°1036]
+            next_item = sorted_items[current_index + 1]
+            next_path = os.path.join(dir_name, next_item)
+
+            # (.2) If the next item is a directory, dive into it [condi 20260818°1037]
+            if os.path.isdir(next_path):
+                return self.__find_right_neighbouur_3(next_path)        # 🚀
+            else:
+                return next_path                                        # 🚀
+        else:
+            # () No — … [condi 20260818°1041]
+            return None                                                 # 🚀 No next item available — Does this ever happen?!
+
+
+    ## \entry   Private method 20260806°1731 get_deepest_first_item
+    #  \brief   Helper method — Symmetric to get_deepest_last_item …
+    #  \param   directory — …
+    #  \return  The wanted first item
+    def __get_first_folder_item(self, directory) :                      # Formerly __get_deepest_first_item(self, directory)
+
+        """
+        Recursively finds the <del>deepest</del> first item (file or directory)
+        in a directory, traversed in a depth-first, alphabetically sorted manner.
+        """
+
+        # (R.1) Pessimistic predetermination [line 20260806°1733]
+        return_value = None
+
+        # (R.2) … [seq 20260806°1735]
+        items = self.__get_listing(directory)                           # Alphabetically sorted and cleaned from to-ignore items
+
+        # (R.3) Are items in the folder? [condi 20260806°1741]
+        if items :
+            # (R.3.1) Yes, the folder has items [seq 20260806°1745]
+            # (R.3.1.1) … [seq 20260806°1747]
+            first_item = items[0]
+            first_item_path = os.path.join(directory, first_item)
+
+            # (R.3.1.2) … [condi 20260806°1751]
+            if os.path.isdir(first_item_path):
+                x = self.__get_first_folder_item(first_item_path)
+                return_value = x                                        # 🚀 Found
+            else :
+                return_value = first_item_path                          # 🚀 Found
+        else :
+            # (R.3.2) No, the folder is empty [seq 20260806°1743]
+            return_value = directory                                    # 🚀 Found. Empty directory, return itself
+
+        # (R.4) Ready [line 20260806°1753]
+        return return_value
+
+
+    ## \entry   Private method 20260806°1431 get_deepest_last_item
+    #  \brief   Helper method …
+    #  \param   directory — …
+    #  \return  The wanted last item
+    def __get_deepest_last_item(self, directory) :
+
+        """
+        Recursively finds the deepest last item (file or directory) in a directory,
+        traversed in a depth-first, alphabetically sorted manner.
+        """
+
+        # (L.1) Pessimistic predetermination [line 20260806°1433]
+        return_value = None
+
+        # (L.2) … [seq 20260806°1435]
+        items = self.__get_listing(directory)                            # Alphabetically sorted and cleaned from to-ignore items
+
+        # (L.3) Are items in the folder? [condi 20260806°1441]
+        if items :
+            # (L.3.1) Yes, the folder has items [seq 20260806°1445]
+            # (L.3.1.1) … [seq 20260806°1447]
+            last_item = items[-1]
+            last_item_path = os.path.join(directory, last_item)
+
+            # (L.3.1.2) … [condi 20260806°1451]
+            if os.path.isdir(last_item_path) :
+                x = self.__get_deepest_last_item(last_item_path)
+                return_value = x                                        # 🚀 Found
+            else :
+                return_value = last_item_path                           # 🚀 Found
+        else :
+            # (L.3.2) No, the folder is empty [seq 20260806°1443]
+            return_value = directory                                    # 🚀 Found. Empty directory, return itself
+
+        # (L.4) Ready [line 20260806°1453]
+        return return_value
+
+
+    ## \entry   Private method 20260806°1341 get_listing
+    #  \brief   Sort method …
+    #  \param   sDirectory — String with directory of which the listing is wanted …
+    #  \return  Listing sorted and cleaned from ignored items or None, where None is fatal
+    #  \detail  Sorting is made a dedicated function, so we can consistently implement the ignore feature
+    #  \detail  Finding 20260806°1621 — `x = list.sort(key = str.casefold)` yields `x = None´. Explanation: list.sort() does
+    #            not return a value! Reference https://docs.python.org/3/library/stdtypes.html#list.sort [ref 20260807°1616]
+    #            says 'This method modifies the sequence in place for economy of space when sorting a large sequence …'
+    def __get_listing(self, sDirectory) :
+
+        # (1) Create sorted list [seq 20260806°1343]
+        try :
+            items1 = os.listdir(sDirectory)
+        except :
+            return None
+
+        items1.sort(key = str.casefold)                                 # Sorting is done 'in place', not returning a new list
+
+        # (2) Filter out ignored entries [var 20260808°0713]
+        items2 = [
+            sEntry for sEntry in items1
+            if not any(fnmatch.fnmatch(sEntry, pattern) for pattern in self.__lstIgnorePats)
+        ]
+
+        # (3) Finished [line 20260806°1345]
+        return items2
+
+
+    ## \entry   Private method 20260808°1011
+    #  \brief   Finds the next valid path for an invalid path one
+    #  \param   sPath — The invalid one …
+    #  \return  The next valid path …
+    #  \detail  Expects a string path so far, but might be extended to process a pathlib.Path as well
+    #  \remark  See todo 20260808°1131 'Consolidate invalid path algorithm'
+    def __guarantee_valid_pathes(self, s_target_path) :
+
+        # (1) Tweak input [seq 20260806°1513]
+        # (1.1) Make path absolute [seq 20260808°0931]
+        sBase_path = os.path.abspath(self.__sBasePath)
+        sTarget_path = os.path.abspath(s_target_path)
+
+        # (1.2) Normalize [seq 20260808°0933] Check — Not yet sure what shall come first, abspath or normalize
+        sBase_path = FileHiker.normaleis(sBase_path)
+        sTarget_path = FileHiker.normaleis(sTarget_path)
+
+        # (2) Valid base path is absolute requirement [seq 20260808°1013]
+        if not os.path.exists(sBase_path) :
+            sMsg = f'[Err_4121] Fatal — Invalid base path: "{sBase_path}"'
+            #raise ValueError(sMsg)
+            print(sMsg)
+            os.sys.exit(66)
+
+        # (R.2) Paranoia — Guarantee target_path is inside or equal to base_path [condi 20260806°1815]
+        if not (sTarget_path.startswith(self.__sBasePath)) :
+
+            # () Notification
+            ###raise ValueError(f"[Err_4133] Target path {sTarget_path} is not inside or equal to base path {self.__sBasePath}")
+            sMsg = f'[Wrn_4133] Warning — Target is not inside or equal to base path, it will be fixed to basepath:' \
+                  + f'           • Target given = "{sTarget_path}"' \
+                   + f'           • Target fixed = "{self.__sBasePath}"'
+            print(sMsg)
+
+            # () Brute force correction [line 20260818°0751]
+            sTarget_path = self.__sBasePath
+
+            return self.__sBasePath, sTarget_path                       # 🚀
+
+
+        # (3) Is it a symlink= [seq 20260808°1021] Space located for later implementation
+        # See e.g. https://bobbyhadz.com/blog/python-check-if-file-or-directory-path-is-symbolic-link [ref 20260807°1806]
+        if os.path.islink(sTarget_path) :
+
+            # (3.1) Process symlink= [seq 20260808°1023] Dummy code so far. Don´t know yet what exactly to do then
+            sMsg = f'[Msg_4123] Symlink = "{sTarget_path}"'
+            print(sMsg)
+
+        # (4) Fix any wrong target path [seq 20260808°1031] See todo 20260808°1131 'Consolidate invalid path algorithm'
+        # See e.g. https://chat.mistral.ai/chat/d5e31f0a-bf1f-404f-ad22-cce3c5757faa [ref 20260802°0920 👻]
+        # See e.g. https://www.perplexity.ai/search/0126d5ee-85f6-4758-bcd6-bef53601fcaf [ref 20260802°1312]
+        if not os.path.exists(sTarget_path) :
+
+            sValidPath = None
+
+            # (4.1) Process invalid parent folder(s) — Quick´n´dirty [seq 20260808°1033]
+            # This sequence comes into effect, if one of the parent folders of the target item is invalid.
+            #  Then it will simple-mindedly search the parents for the first valid folder, doing no
+            #  interpolation This could be much refined by doing interpolations, looking for existing
+            #  neighbours of the invalid path element, as does the algorithm below [todo 20260808°1131]
+            sSearchDir = os.path.dirname(sTarget_path)
+            if not os.path.exists(sSearchDir) :
+                while not os.path.exists(sSearchDir) :
+                    sSearchDir = os.path.dirname(sSearchDir)
+                return sBase_path, FileHiker.normaleis(sSearchDir)      # 🚀
+
+            # (4.2) Process invalid path last-element [seq 20260808°1035]
+            # Here we really look for the nearest replacement for the invalid item by bisecting the listing.
+            #  Just so far this is applied only for the 'path last-element', not for any deeper mishap,
+            #  which were already processed simple-minded above.
+            # Note : The 'path last-element' is what os.path.basename() delivers. Just the word 'basename' is
+            #         not so suited here, since we already talk about the 'base path', which is kind of opposite.
+            while True :
+
+                # (4.2.1) … [seq 20260808°1041]
+                sValidEntry = None
+                aunts = self.__get_listing(sSearchDir)                  # Aunts is short for 'aunts and uncles' or 'parent siblings'
+                if aunts == None :
+                    # Continue search in parent folder
+                    sSearchDir = os.path.dirname(sSearchDir)
+                    continue
+
+                # (4.2.2) Find the insertion point for the target_path [seq 20260808°1043]
+                sLastElement = os.path.basename(sTarget_path)           # basename is last element of path
+                #if b_Direction :
+                #    index = bisect.bisect_left(aunts, sLastElement)
+                #    index_compare = bisect.bisect_right(aunts, sLastElement)
+                #else :
+                #    index = bisect.bisect_right(aunts, sLastElement)   # basename is last element of path
+                index = bisect.bisect(aunts, sLastElement)              # basename is last element of path
+
+                # (4.2.3) Determine previous and next paths [seq 20260808°1045]
+                if index > 0 :
+                    sValidEntry = aunts[index - 1]
+                elif index < len(aunts) :
+                    sValidEntry = aunts[index]
+                else :
+                    sMsg = f'[Err_4125] Fatal — Invalid base path: "{sBase_path}"'
+                    #raise ValueError(sMsg)
+                    print(sMsg)
+                    os.sys.exit(66)
+
+                # (4.2.4) Searching done? [seq 20260808°1047]
+                if sValidEntry :
+                    sTarget_path = os.path.join(os.path.dirname(sTarget_path), sValidEntry)
+                    break
+
+        return sBase_path, sTarget_path                                 # 🚀
+
+
+    ## \register Public method 20260810°1131 find_neighbour
+    #  \brief    The two-way walking work horse API method …
+    #  \detail   Just a wrapper method to allow for the API one single method with a direction flag
+    #  \remark   The spelling 'neighbor' is American English, 'neighbour' is British English
+    #  \param    base_path — The root of the search area
+    #  \param    target_path — The item inside root for which the left neighbour is wanted
+    #  \param    b_forward — Flag telling whether to walk forward or backward
+    #  \return   The wanted right or left neighbour
+    def find_neighbour(self, s_target_path) :
+
+        # () Parameter sanitation [line 20260816°0811]
+        s_target_path = FileHiker.normaleis(s_target_path)
+
+        # () Paranoia — Guarantee target_path is inside or equal to base_path [condi 20260816°0751]
+        # This shall replace seq 20260806°1515 and seq 20260806°1815
+        if not (s_target_path.startswith(self.__sBasePath)) :
+
+            # () Notify problem [line 20260816°0753] Todo: Implement more graceful notification [todo 20260816°0755]
+            sMsg = f'\n\n[Err_4135] Given target path is not inside or equal to base path' \
+                  + f'\n            • BasePath     = "{self.__sBasePath}"' \
+                   + f'\n            • Given target = "{s_target_path}"' \
+                     + f'\n            • Fixed target = "{self.__sBasePath}"\n'
+            print(sMsg)
+    
+            s_target_path = self.__sBasePath
+
+        # ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
+        # () Preparations … [seq 20260818°0833] Shifted redundant sequence here from __find_left_neighbour() and __find_left_neighbour() [chg 20260818°0831´01]
+        # (L.1) Guarantee valid pathes [seq 20260808°0941]
+        sBase_path, sTarget_path = self.__guarantee_valid_pathes(s_target_path)
+
+        # (L.3) Is target the base path? [seq 20260806°1517]
+        if sTarget_path == self.__sBasePath :
+            sTgt_FolderName = self.__sBasePath
+            sTgt_ElementName = os.path.basename(self.__sBasePath)
+        else :
+            sTgt_FolderName = os.path.dirname(sTarget_path)
+            sTgt_ElementName = os.path.basename(sTarget_path)
+        # ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
+
+        # () Dispatch the call [seq 20260810°1133]
+        if self.__bDirection:
+            ###neighbour = self.__find_right_neighbour(sTgt_FolderName, sTgt_ElementName)  # [chg 20260818°0831´06]
+            x = FileHiker.normaleis(sTgt_FolderName + '/' + sTgt_ElementName)
+            neighbour = self.__find_right_neighbouur_4(x)
+        else:
+            neighbour = self.__find_left_neighbour(sTgt_FolderName, sTgt_ElementName)  # [chg 20260818°0831´07]
+
+        # () Streamline result — Should be superfluous if the callees return values are normalized [line 20260810°1135]
+        sNeighbour = FileHiker.normaleis(neighbour)
+
+        # () Ready
+        return sNeighbour
+
+
+    ## \entry   Method 20260811°1041 get_BasePath
+    #  \brief   Accessor method …
+    #  \return  The wanted value
+    def get_BasePath(self) :
+
+        return self.__sBasePath
+
+
+    ## \entry   Method 20260811°1051 get_Direction
+    #  \brief   Accessor
+    #  \return  The wanted value
+    def get_Direction(self) :
+
+        return self.__bDirection
+
+
+    ## \entry   Method 20260811°1121 get_Verbose
+    #  \brief   Accessor
+    #  \return  The wanted value
+    def get_Verbose(self) :
+
+        return self.__bVerbose
+
+
+    ## \entry   Method 20260811°1111 get_IgnoreList
+    #  \brief   Accessor
+    #  \return  The wanted value
+    def get_IgnoreList(self) :
+
+        return self.__lstIgnorePats
+
+
+    ## \entry   Static method 20260804°0701
+    #  \brief   Helper method …
+    #  \param   path — The path to be normalized, be it a string or pathlib.Path
+    #  \return  String with the normalized path
+    @staticmethod
+    def normaleis(path) :
+
+        sPath = str(path)                                               # Convert possible pathlib.Path object
+        sPath21 = os.path.normpath(sPath)                               # Get rid of intermittend dot folders
+        sPath22 = sPath21.replace('\\', '/')                            # Use slashes, not backslashes
+        bExists = os.path.exists(sPath)
+        sPath23 = sPath22                                               # Set default
+        if bExists and os.path.isdir(sPath22) :
+            sPath23 = sPath22 if sPath22.endswith('/') else sPath22 + '/'  # Guarantee folder´s trailing slash
+
+            sPath23 = sPath23[:-1] if sPath23.endswith('//') else sPath23  # Provisory patch against double slashes [line 20260818°1111]
+
+        return sPath23
+
+
+    ## \entry   Method 20260811°1043 set_BasePath
+    #  \brief   Accessor method to set the base path …
+    #  \param   The value to be set
+    def set_BasePath(self, sPath) :
+
+        sPth = FileHiker.normaleis(sPath)
+
+        self.__sBasePath = sPth
+
+
+    ## \entry   Method 20260811°1053 set_Direction
+    #  \brief   Set the direction flag
+    #  \param   bDir — The value wanted to be set
+    def set_Direction(self, bDir) :
+
+        self.__bDirection = bDir
+
+
+    ## \entry   Method 20260811°1113 set_IgnoreList
+    #  \brief   Set the ignore list
+    #  \param   The value to be set
+    def set_IgnoreList(self, lst) :
+
+        self.__lstIgnorePats = lst
+
+
+    ## \entry   Method 20260811°1123 set_Verbose
+    #  \brief   Set the verbose flag
+    #  \param   The value to be set
+    def get_Verbose(self, bVerbose) :
+
+        self.__bVerbose = bVerbose
+
+
+    ## \entry   Public?! method 20260808°0731 — So far only called from __main__.py, thus possibly not private. This method may be superfluous!
+    #  \brief   Strip base path prefix from full path string …
+    #  \param   s_BasePath — …
+    #  \param   s_FullPath — …
+    #  \return  Path string with the base path stripped
+    def strip_prefix(self, s_BasePath, s_FullPath) :
+
+        sBasePath = s_BasePath.replace('\\', '/')                       # Paranoia
+        sFullPath = s_FullPath.replace('\\', '/')
+        sReturn = sFullPath                                             # Pessimistic default
+
+        if sFullPath.startswith(sBasePath) :
+            sReturn = sFullPath[len(s_BasePath):]
+
+        return sReturn
+
+
+## = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+## Former functionality code shutdown in favour of class 20260810°0911 FileHiker [chg 20260810°1051 '💫 Breaking change']
+### = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+
+## = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+## Seftest functions shifted from here to module __main__.py [chg 20260811°0811]
+### = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+
+
+## \register seq 20250406°0731
+#  \brief    Main idiom — The plain `if __name__ == '__main__'` does not work as usual because the caller here is __main__.py
+if __name__ == "__main__" and __package__ not in (None, ''):
+
+    print('[Msg_4127] This package module shall not be started directly.')
+    sys.exit(123)                                                       # Runs without any ado in a commandline call, throws exception `SystemExit` in the debugger