FileHikerDev Project ^v0.3.9.2

1. Summary ^🔗

FileHiker is a Python package to find a filesystem item's neighbour relative to a given target path inside a given 'base folder'. It finds either the next or the previous neighbour, depending on a direction flag. If the target does not exist, it tries to find a sensible 'neighbour' anyway.

Synopsis:

• Slogan : Directory crawler Python package. It finds any file system item´s neighbour, one by one, walking either forward or backward
• Particularities:
  • Walks forward and backward equally and symmetrically
  • Suited for huge file system hierarchies due to it´s memory saving behaviour using internally only one single-level directory listing at a time
• License : BSD 3-Clause
• Copyright : © 2025 – 2026 Norbert C. Maier
• System: Written and tested with Python 3.13 on Windows. Should work on Linux/Mac as well, what is yet to be tested
• Still missing features : Symlink handling
• Status : Applicable

2. Installation ^🔗

Install the package in your Python either via pip or as development installation

2.2. User Installation ^🔗

Since the package is is not (yet) on pypi.org, the user installation via pip is not yet available, only the development installation is possible (see below). If available, it looks like follows:

 > python.exe -m pip install filehiker

or

 > pip.exe install filehiker

2.1. Development Installation ^🔗

How to do so?

1. Somehow get the filehikerdev project folder on your local drive
2. In the console change directory to the project´s root folder filehikerdev
3. Issue one of the following commands — Don´t miss the trailing dot for 'current folder'!
   • filehikerdev> pip.exe install -e .
   • filehikerdev> python.exe -m pip install -e .

Install local FileHiker development version. Note the trailing dot in the first line! (txt)

3. UI (User Interface) ^🔗

After installation, FileHiker can immediately do some things from the console, as follows

• Perform some selftest:

   > python.exe -m filehiker
  

• Perform some selftest … :

   > python.exe -m filehiker selftest
  

Restriction, mentioned just for sake of completeness. python.exe -m filehiker must not be called from the folder, where the filehiker.py resides. When done so, nothing happens. This is due to the Python package handling, which makes it difficult to catch that case. The effort implementing this case is not worth the gain. As a user, you will never see this folder anyway, but as a developer you will work in it.

4. API (Application Programmers Interface) ^🔗

• Constructor filehiker.FileHiker(basepath, direction, ignorewcs, verbose) where
  • basepath — Optional string to tell to which folder the scanning is confined. Default is '' (empty), which shall translate to the folder from where python.exe was called
  • direction — Optional boolean telling whether to go forward or backward. Default is True, means forward
  • ignorewcs — Optional list with wildcard patterns for files and folder to ignore. Default is a list with patterns like .git, __*__, etc. See the list in the source filehiker.py at about line 50
  • verbose - Flag to tell whether to print some output or not. Default is False
• Method find_neighbour(target) where target is a string with a path pointing to the current item, from which it´s neighbour is wanted. Returns a string with the found neighbour.
• Method get_BasePath() — Returns the current base path
• Method get_Direction() — Returns the current direction flag
• Method get_Verbose() — Returns the current verbose flag
• Method get_IgnoreList() — Returns the current ignore list
• Static method normaleis() — Takes a path and returns it normalized, means with slashes and a trailing slash for directories
• Method set_BasePath(basepath) — Takes a string with the new base path to be set
• Method set_Direction(direction) — Takes a boolean with the new direction to be set
• Method set_Verbose(verbose) — Takes a boolean with the new verbose flag to be set
• Method set_IgnoreList(ignorelist) — Takes a list with the new ignore patterns to be set

5. Usage ^🔗

Here some exsample code how to use it

    # …

Todo: Provide some example code

6. Package Folder Structure ^🔗

The FileHiker package uses the 'Src-Layout' folder structure, one of three common package layout options. Find more about package folder structures in the ZanaFacils Notes file, subchapter About Python Package Layouts.

filehikerdev
├── docs
│   └── …
├── src
│   └── filehiker
│       ├── __init__.py
│       ├── filehiker.py
│       └── subpkg
│           ├── __init__.py
│           └── module2.py
├── README.md
└── pyproject.toml

This is the folder structure of the development installation. With a (not yet available) user installation, only the package folder will be seen.

Thorough information on Python packages folder structures is found on [Py-Pkgs.org](https://py-pkgs.org/) ^{[ref ◇]} chapter [4. Package structure and distribution](https://py-pkgs.org/04-package-structure.html) ^{[ref 20250816°0848]} Mistral quest [Python package documentation placement](https://chat.mistral.ai/chat/db251f65-bdb0-4cfe-b58a-3ddef93513b2) — Reasoning about where to place which documentation ^{[ref 20260726°0842 📡]}

7. Flowchart ^🔗

8. Credits ^🔗

The Orange Tree logo comes from [openclipart.org/detail/323926/orange-tree](https://openclipart.org/detail/323926/orange-tree) as a Public Domain dedication.

 

---

8. Fineprint ^🔗

   project 20250406°0711 FileHiker
   objtype     : Python package
   url         :
   title       : Filehiker
   summary     : Find filesystem item´s neighbour left or right
   status      : Applicable
   tags        :
   note        :
   ⬞

   repo 20260818°1414 FileHikerDev
   objtype     : Git repository
   canonical   : https://gitlab.com/normai/filehikerdev
   title       : FileHikerDev
   tags        :
   note        :
   ⬞

^{Page 20250406°0721 ⬞Ω}