Metadata-Version: 2.4
Name: FileHiker
Version: 0.3.9.2
Summary: A file system walker — Find the right or left neighbour of a path inside a specified base folder
Author: Norbert C. Maier
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://gitlab.com/normai/filehiker
Keywords: directory crawler,directory walker,file system crawler,file system walker
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Requires-Python: >=3.13
Description-Content-Type: text/markdown

<!-- title = 'FileHiker'; favicon = './docs/icos/20260815o0743.orangetree.v1.x0256y0256.png'; -->

<img src="./docs/icos/20260815o0743.orangetree.v1.x0256y0256.png" align="right" width="160" height="160" alt="Logo 20220206°0933">

<div markdown="1" class="lmp-breadcrumbs">
 <span class="CurrentChapter">[Projects](./../../../blogdev/trunk/projects.md)</span> →
 <span class="CurrentPage">[FileHikerDev](./README.md)</span> →
 [Changes](./docs/changelog.md)
 [Issues](./docs/issues.md)
 [Notes](./docs/notes.md)
 [References](./docs/references.md)
</div>

# FileHikerDev <span class="lmp-title-type">Project</span> <sup>v0.3.9.2</sup>

<div markdown="1" class="lmp-box-page-sections">
Below:
 [1. Summary](#id20260725o1011)
 [2. Installation](#id20260725o1013)
 [3. UI](#id20260813o0911)
 [4. API](#id20260725o1015)
 [5. Usage](#id20260813o0913)
 [6. Folder Structure](#id20250816o0849)
 [7. Flowchart](#id20260725o1017)
 [8. Credits](#id20260816o0831)
 [9. Fineprint](#id20260725o1019)
</div>

## 1. Summary <sup><a href="#id20260725o1011" id="id20260725o1011">🔗</a></sup>

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 <sup><a href="#id20260725o1013" id="id20260725o1013">🔗</a></sup>

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

### 2.2. User Installation <sup><a href="#id20260725o1513" id="id20260725o1513">🔗</a></sup>

Since the package is is not (yet) on [pypi.org](https://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 <sup><a href="#id20260725o1511" id="id20260725o1511">🔗</a></sup>

How to do so?
1. Somehow get the `filehikerdev` project folder on your local drive
1. In the console change directory to the project´s root folder `filehikerdev`
1. 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 .`

<a href="./docs/imgs/20260814o0721.console--pip-exe--install--filehiker.png"><img src="./docs/imgs/20260814o0721.console--pip-exe--install--filehiker.png" class="lmp-img-centered" width="653" height="278" data-dims="x1452y0619" alt="Screenshot 20260814°0721"></a>
 <br>Install local FileHiker development version. Note the trailing dot in the first line! ([txt](./docs/imgs/20260814o0721.console--pip-exe--install--filehiker.png.txt))

## 3. UI (User Interface) <sup><a href="#id20260813o0911" id="id20260813o0911">🔗</a></sup>

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) <sup><a href="#id20260725o1015" id="id20260725o1015">🔗</a></sup>

- 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](./src/filehiker/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 <sup><a href="#id20260813o0913" id="id20260813o0913">🔗</a></sup>

Here some exsample code how to use it

```
    # …
```
<span class="lmp-font-todo">Todo: Provide some example code</span>

## 6. Package Folder Structure <sup><a href="#id20250816o0849" id="id20250816o0849">🔗</a></sup>

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](./../zanafacilsdev/zanafacils/docs/notes.md#id20260631o0723).

<pre style="font-size: 1.1em; line-height: 1.18em !important;">
<b>filehikerdev</b>
├── docs
│   └── …
├── <b>src</b>
│   └── <b>filehiker</b>
│       ├── <b>__init__.py</b>
│       ├── <b>filehiker.py</b>
│       └── <em>subpkg</em>
│           ├── <em>__init__.py</em>
│           └── <em>module2.py</em>
├── README.md
└── <b>pyproject.toml</b>
</pre>

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

<!-- img class="lmp-reference-icon" src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 48 48'><circle cx='24' cy='24' r='24' fill='LightSlateGray'/></svg>" width="32" height="32" alt=" Icon gray disk" -->

<img class="lmp-reference-icon" src="./docs/icos/20250816o0849.py-pkgs--org.v1.x0064y0064.png" width="48" height="48" alt=" Icon 20250816°0849">
 Thorough information on Python packages folder structures is found on
 [Py-Pkgs.org](https://py-pkgs.org/)
 <sup>[ref ◇]</sup>
 chapter
 [4. Package structure and distribution](https://py-pkgs.org/04-package-structure.html)
 <sup>[ref 20250816°0848]</sup>

<img class="lmp-reference-icon" src="./docs/icos/20250514o0821.mistral-ai.v2.x0064y0064.png" width="48" height="48" alt=" Icon 20250514°0821">
 Mistral quest
 [Python package documentation placement](https://chat.mistral.ai/chat/db251f65-bdb0-4cfe-b58a-3ddef93513b2)
 — Reasoning about where to place which documentation
 <sup>[ref 20260726°0842 📡]</sup>

## 7. Flowchart <sup><a href="#id20260725o1017" id="id20260725o1017">🔗</a></sup>

<a href="./docs/imgs/diagram_filehiker.20260725o0951.uxf.svg"><img src="./docs/imgs/diagram_filehiker.20260725o0951.uxf.svg" style="border:2px solid LightGray; border-radius:0.7rem;" width="400" alt="Diagram 20260725°0951"></a>

## 8. Credits <sup><a href="#20260816o0831" id="id20260816o0831">🔗</a></sup>

<img class="lmp-reference-icon" src="./docs/icos/20260815o0743.orangetree.v1.x0256y0256.png" width="48" height="48" alt=" Icon 20260815°0743">
 The Orange Tree logo comes from
 [openclipart.org/detail/323926/orange-tree](https://openclipart.org/detail/323926/orange-tree)
 as a Public Domain dedication.


&nbsp;

---

#### 8. Fineprint <sup><a href="#id20260725o1019" id="id20260725o1019">🔗</a></sup>

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

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

<sup>Page 20250406°0721 ⬞Ω</sup>
