FileHikerDev Project ^v0.4.5

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 is suited for huge file system hierarchies, due to it´s memory saving behaviour, by using only one single-level listing in memory at a time • It walks forward and backward equally and symmetrically • If you interrupt the walking, you can continue at the same spot later
Motivation	I want walk a drive, file by file. Doing it a directory listing is no option, due to the amount of files. So I wrote the FileHiker library. By the way — It takes about 20 hours for 2 million files on a SSD drive, including some payload task per file, like calculating the file hash.
License	BSD 3-Clause, see license.txt
Copyright	© 2025 – 2026 Norbert C. Maier
System	Written and tested with Python 3.13 on Windows. It should also work on Linux and Mac, just this is yet to be tested
Dependencies	None
Repository	gitlab.com/normai/filehikerdev
Documentation	normai.gitlab.io/filehikerdev
Distribution	pypi.org/project/filehiker
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()             # No base folder given, so use the CWD
neighbour = fhk.find_neighbour('')      # No offset given, so target is base folder
print(f'Right neighbour = {neighbour}'  # Right neighbour is base folder´s first entry

6. Development Folder Structure ^🔗

The FileHiker package uses the 'Src-Layout' folder structure, one of several common package layout options.

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