FileHikerDev Project ^v0.4.3

1. Summary ^🔗

Slogan	Directory crawler Python package to find 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 inspecting only one directory single-level at a time
License	BSD 3-Clause, see 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
Canonical location	gitlab.com/normai/filehikerdev
Documentation	normai.gitlab.io/filehikerdev
Distribution	pypi.org/project/filehiker
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.
Missing features	Symlink handling
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 provides a bit interactivity from the console anyway:

• Output help screen:

   > python.exe -m filehiker
  

• Output some status info:

   > python.exe -m filehiker i
  

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

   > python.exe -m filehiker s
  

• Perform a selftest on your CWD, current working dir, from where ever you started python.exe:

   > 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) ^🔗

See documentation at …

5. Usage ^🔗

Here is a minimalistic example how to use FileHiker:

 import filehiker
 fhk = filehiker.FileHiker()             # Since no base folder is defined, the CWD is used as such
 offset = ''                             # No offset means the  target is 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 found 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
│       └── possible subpkgs
│           ├── __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 ⬞Ω}