Metadata-Version: 2.4
Name: FileHiker
Version: 0.4.1
Summary: File system walker — Find the right or the 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 :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Requires-Python: >=3.13
Description-Content-Type: text/markdown

<!-- title = 'FileHiker'; favicon = './docs/icos/20260819o0731.tree-view-logo-one.v3.svg'; -->

<svg xmlns="http://www.w3.org/2000/svg" style="float: right;" width="180" height="180" viewBox="-0.5 -0.5 330 330">
 <title>File System Hierarchy</title><defs><linearGradient id="a" x1="143.595" x2="143.595" y1="193.811" y2="253.552" gradientTransform="scale(1.38933 .71977)" gradientUnits="userSpaceOnUse"><stop offset="0%" style="stop-color:#ffcd28;stop-opacity:1"/><stop offset="100%" style="stop-color:orange;stop-opacity:1"/></linearGradient><linearGradient id="b" x1="71.617" x2="71.617" y1="388.317" y2="448.058" gradientTransform="scale(1.38933 .71977)" gradientUnits="userSpaceOnUse"><stop offset="0%" style="stop-color:#e6d0de;stop-opacity:1"/><stop offset="100%" style="stop-color:#d5739d;stop-opacity:1"/></linearGradient></defs><g transform="rotate(-4.9 159.078 -128.265)"><rect width="85" height="40" x="1" y="1" fill="#1ba1e2" stroke="#006eaf" stroke-width="3" pointer-events="all" rx="2.8" ry="2.8"/><rect width="80" height="40" x="101" y="71" fill="#fa6800" stroke="#c73500" stroke-width="3" pointer-events="all" rx="2.8" ry="2.8"/><path fill="none" stroke="#6c8ebf" stroke-miterlimit="10" stroke-width="6" d="M43.5 43 41 301h58M41 91h58" pointer-events="stroke"/><rect width="80" height="40" x="201" y="141" fill="url(#a)" stroke="#d79b00" stroke-width="3" pointer-events="all" rx="2.8" ry="2.8" style="fill:url(#a)"/><rect width="80" height="40" x="101" y="281" fill="url(#b)" stroke="#996185" stroke-width="3" pointer-events="all" rx="2.8" ry="2.8" style="fill:url(#b)"/><path fill="none" stroke="#6c8ebf" stroke-miterlimit="10" stroke-width="6" d="M141 113v48h58" pointer-events="stroke"/><rect width="80" height="40" x="201" y="211" fill="#60a917" stroke="#2d7600" stroke-width="3" pointer-events="all" rx="2.8" ry="2.8"/><path fill="none" stroke="#6c8ebf" stroke-miterlimit="10" stroke-width="6" d="M141 163v68h58" pointer-events="stroke"/></g>
</svg>

<!-- PyPi.org renders the Markdown links literally, means wrong (see v0.3.9.2). Now let´s try HTML. -->
<div markdown="1" class="lmp-breadcrumbs">
 <span class="CurrentPage">FileHikerDev</span> →
 <a href="./docs/changelog.md">Changelog</a> &nbsp;
 <a href="./docs/issues.md">Issues</a> &nbsp;
 <a href="./docs/notes.md">Notes</a>
</div>

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

<!-- PyPi.org renders the Markdown links literally, means wrong (see v0.3.9.2). So skip them for now -->
<!-- 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. Credits](#id20260816o0831)
 [8. Fineprint](#id20260725o1019)
</div -->

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

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

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

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

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

<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 FileHiker editable 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>

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

Here is a minimalistic example how to use FileHiker:

<pre>
 # 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
</pre>

## 6. Development 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.
<del>Find more about package folder structures in the ZanaFacils Notes file, subchapter
 [About Python Package Layouts](./../zanafacilsdev/zanafacils/docs/notes.md#id20260631o0723).</del>

<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>

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

&nbsp;

<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. Credits <sup><a href="#20260816o0831" id="id20260816o0831">🔗</a></sup>

<img class="lmp-reference-icon" src="./docs/icos/20260819o0731.tree-view-logo-one.v3.svg" width="64" height="64" alt=" Icon 20260819°0731">
 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

&nbsp;

<img class="lmp-reference-icon" src="./docs/icos/20210508o1044.choosealicense.v2.x0064y0064.png" width="48" height="48" alt=" Icon 20210508°1044">
 The license text was taken from 
 [choosealicense.com/licenses/bsd-3-clause/](https://choosealicense.com/licenses/bsd-3-clause/)

&nbsp;

---

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

<pre class="lmp-font-small">
   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 class="lmp-font-small">
   repo 20260818°1414 FileHikerDev
   objtype     : Git repository
   canonical   : https://gitlab.com/normai/filehikerdev
   title       : FileHikerDev
   tags        :
   note        :
   ⬞
</pre>

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