<title>File System Hierarchy</title>

FileHikerDev Project ^v0.4.1

1. Overview ^🔗

Synopsis:

• Slogan : Directory crawler Python package. It finds any file system item´s neighbour, one by one, walking either forward or backward
• Description : FileHiker is a Python package to find the right or left neighbour for any filesystem item inside a given 'base folder'. It finds either the next or the previous neighbour, depending on a direction flag. If the given target does not exist, it tries to find a sensible neighbour anyway.
• Particularities:
  • It walks forward and backward equally and symmetrically
  • It is 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, see src/filehiker/license.txt
• Copyright : © 2025 – 2026 Norbert C. Maier
• System : Written and tested with Python 3.13 on Windows. Should also work on Linux/Mac, just this is yet to be tested
• Dependencies : None
• Missing features : Symlink handling
• Motivation : I wanted walk a drive file by file to build a database of the files. It takes about 20 hours for 2 million files, including some little payload per file, like calculating the file hash.
• Development Status : Applicable

2. Installation ^🔗

Install the package in your Python via pip (1) either as user installation from PyPi.org or (2) as editable development installation if you have the sources on your machine

2.1 User Installation ^🔗

Use one of the following commandline prompts (the .exe is Windows specific):

 > pip.exe install filehiker

 > pip.exe install -U filehiker

 > python.exe -m pip install filehiker

 > python.exe -m pip install -U filehiker

2.2 Development Installation ^🔗

How to do so?

1. Get the filehikerdev project folder on your local drive, possibly by cloning it from GitLab
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 .
4. You should see a console like in the following screenshot

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

3. UI (User Interface) ^🔗

Though FileHiker is a library to be used from other Python code, it nevertheless provides a bit interactivity from the console:

• Output some status info:

   > python.exe -m filehiker
  

• Perform a selftest on the built-in test-folder:

   > python.exe -m filehiker s
  

• Perform a selftest on your CWD, current working dir:

   > python.exe -m filehiker t
  

By the way. There is a curious restriction, mentioned just for sake of completeness. Command python.exe -m filehiker must not be issued from the folder, where the filehiker.py resides. If you do so, just nothing happens, which is due to Python´s package handling. The case is difficult to catch from the code. The effort implementing the case is not worth the gain. As a user, you will never see this folder anyway, and as a developer you can easily just avoid 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 to the right, False means backward to the left
  • ignorewcs — Optional list with wildcard patterns for files and folders 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 one 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 is a minimalistic example how to use FileHiker:

 # Since no base folder is defined, the CWD, current working dir, is used as such
 import filehiker
 fhk = filehiker.FileHiker()
 offset = ''                             # No offset means just the base folder itself
 neighbour = fhk.find_neighbour(offset)  # The right neighbour of the base folder is it´s first entry
 print(f'Right neighbour = {neighbour}'  # Shows the first entry in the base folder

6. Development 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

Detailled information on Python packages is found on site 'Python Packages' - Frontpage [Py-Pkgs.org](https://py-pkgs.org/) ^{[ref 20260817°1034]} - 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. Credits ^🔗

The 'File System Hierarchy One' logo is made by Norbert with DrawIO, Inkscape and [jakearchibald.github.io/svgomg](https://jakearchibald.github.io/svgomg/) under the [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) license

 

The license text was taken from [choosealicense.com/licenses/bsd-3-clause/](https://choosealicense.com/licenses/bsd-3-clause/)

 

---

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 ⬞Ω}