Searchex

searchex ist ein schneller, multithreaded Datei‑Scanner, findet Text‑ und Binär‑Treffer rekursiv und zeigt pro Datei Zeilennummern, Vorschau sowie Direkt‑Sprung zum ersten Treffer.

CLIAPIsFun Repo ↗
Featured

Dokumentation · v0.2.1 - alpha

searchex – Dokumentation

Version: 0.2.0
Plattform: Windows 10/11 (64‑bit)
Technik: PySide6 (Qt) UI, C++ Extension via pybind11, scikit‑build‑core, CMake

Inhalt

  1. 1. Überblick
  2. 2. Voraussetzungen
  3. 3. Verzeichnisstruktur
  4. 4. Build & Installation (Wheel)
  5. 5. Starten
  6. 6. Bedienung
  7. 7. Suchoptionen
  8. 8. Leistung & Responsivität
  9. 9. Logging & Fehlermeldungen
  10. 10. Binärdateien & Vorschau
  11. 11. Packen zu .exe (PyInstaller)
  12. 12. Troubleshooting
  13. 13. FAQ
  14. 14. Lizenz

1. Überblick

searchex ist ein schneller, multithreaded Datei‑Scanner mit moderner Qt‑Oberfläche (PySide6). Rechenintensive Arbeit (Datei lesen, Muster finden) passiert in einem C++‑Modul (searchex_native) via pybind11. Das Programm durchsucht rekursiv Dateien und kann sowohl Text‑ als auch Binärdateien prüfen. Funde werden pro Datei als Kacheln angezeigt – inklusive Zeilennummern, Dateigröße, Vorschau und Direkt‑Sprung zur ersten Fundstelle.

2. Voraussetzungen

  • Windows 10/11, 64‑bit
  • Python 3.13 (64‑bit)
  • Visual Studio 2022 Community mit „Desktopentwicklung mit C++“
  • Build‑Tools: CMake ≥ 3.27, Ninja, pybind11[global], scikit‑build‑core
python -m pip install -U pip build scikit-build-core pybind11[global] cmake ninja

3. Verzeichnisstruktur

searchex/
├─ pyproject.toml
├─ CMakeLists.txt
├─ README.md
├─ app.py
├─ resources/
│  ├─ logo.png
│  └─ logo.ico (optional für EXE)
├─ src/
│  ├─ cpp/
│  │  └─ cpp.cpp                (C++ Quelle für pybind11)
│  └─ searchex/
│     └─ __init__.py            (lädt searchex_native)
└─ logs/                        (wird zur Laufzeit angelegt)

4. Build & Installation (Wheel)

Das native Modul wird mit scikit‑build‑core und CMake gebaut.

# 1) Wheel bauen
python -m build --wheel .

# 2) Wheel installieren (überschreiben, keine Deps)
pip install --force-reinstall --no-deps dist\searchex-0.2.0-*.whl

Wichtig: CMakeLists.txt muss im Projekt‑Root liegen und eine install(TARGETS ...)‑Regel besitzen, damit die erzeugte .pyd im Wheel landet.

5. Starten

python app.py

Optional kannst du das Fenster‑Icon setzen (bereits vorbereitet):

app.setWindowIcon(QIcon("resources/logo.png"))

6. Bedienung

  1. Pfad wählen: Ordner oder Datei per Dialog wählen oder per Drag & Drop in das Pfadfeld ziehen.
  2. Suchmuster: Im Feld „Search patterns“ pro Zeile ein Muster eintragen (Plaintext oder Regex).
  3. Optionen: Case‑sensitive, Regex, Whole word, Name‑Matching, Hidden Files, Max. Dateigröße, Threads.
  4. Start: „Start“ klicken. Fortschritt und Anzahl verarbeiteter Dateien siehst du in der Statusleiste.
  5. Ergebnisse: Kacheln zeigen Dateiname, Pfad, Größe, „Text/Binary“, Trefferzahl und Zeilennummern.
  6. Aktionen pro Kachel: Open, Reveal in Explorer, Jump to first hit.
  7. Fehler: „Errors / skipped files“ ist einklappbar und listet Probleme (z. B. Zugriffsfehler).

7. Suchoptionen

  • Case sensitive: ASCII‑Groß/Klein beachten.
  • Regex: Muster als ECMAScript‑Regex interpretieren.
  • Whole word: Treffer nur an Wortgrenzen (Substring‑Modus).
  • Match file/folder names: Muster gegen Dateinamen/Ordnernamen prüfen (schnell, ohne Dateiinhalt zu öffnen).
  • Include hidden: Versteckte Dateien/Ordner einschließen.
  • Max MB: 0 = unbegrenzt; sonst werden größere Dateien übersprungen.
  • Threads: Maximale Parallelität (Task‑Threads für Dateien).

8. Leistung & Responsivität

  • Das C++‑Modul gibt während Datei‑I/O und Matching den Python‑GIL frei, damit die Qt‑Events weiterlaufen.
  • Ergebnis‑Rendering erfolgt in kleinen Batches über einen Timer; das UI bleibt flüssig.
  • Für sehr große Dateien empfiehlt sich ein Limit über „Max MB“.

9. Logging & Fehlermeldungen

Logs werden in logs/app.log geschrieben (Rolling‑File, UTF‑8). Bei Problemen erscheinen Einträge auch in der Liste „Errors / skipped files“.

10. Binärdateien & Vorschau

  • Binärdateien werden anhand einer Heuristik erkannt (z. B. Nullbytes, Steuerzeichenanteil).
  • Textvorschau zeigt Kontext um den ersten Treffer; bei Binärdateien erscheint ein Hex‑Snippet.

11. Packen zu .exe (PyInstaller)

  1. Icon konvertieren: resources\logo.ico (PNG bleibt für das Fenster‑Icon).
  2. Wheel lokal installieren, damit searchex_native verfügbar ist.
python -m build --wheel .
pip install --force-reinstall --no-deps dist\searchex-*.whl

pyinstaller app.py ^
  --name searchex ^
  --onedir ^
  --noconsole ^
  --icon resources\logo.ico ^
  --add-data "resources\logo.png;resources" ^
  --collect-all PySide6 ^
  --collect-binaries searchex

Ergebnis: dist\searchex\searchex.exe (ganzen Ordner verteilen). Für One‑file ersetze --onedir durch --onefile.

12. Troubleshooting

  • Mini‑Wheel (~1 KB): In CMakeLists.txt fehlt die install(TARGETS ...)‑Regel.
  • Backend‑Pfad falsch: build-backend = "scikit_build_core.build" (mit Unterstrichen).
  • README fehlt: readme = "README.md" erfordert eine Datei im Root.
  • CMakeLists nicht im Root: scikit‑build‑core erwartet sie im Projekt‑Root.
  • Interpreter‑Mismatch: Wheel immer mit genau dem Python bauen/verwenden (z. B. cp313 win_amd64).
  • pybind11 nicht gefunden: pip install pybind11[global].
  • Qt‑Plugins fehlen in EXE: PyInstaller mit --collect-all PySide6 bauen.
  • Button‑Callback gibt bool statt Pfad: beim clicked.connect ein Dummy‑Argument verwenden, z. B.:
    lambda checked=False, p=path, pos=first_pos, b=is_bin: self.open_preview(p, pos, b)

13. FAQ

Warum ist ein Treffer in Binärdateien manchmal schwer zu interpretieren?
Weil die Daten nicht textuell sind; nutze die Hex‑Vorschau oder grenze mit Dateifiltern ein.

Kann ich nur bestimmte Dateitypen durchsuchen?
Ja – Erweiterungsidee: einfache Pattern‑Filter (z. B. *.cpp;*.h) lassen sich leicht ergänzen.

Speichert searchex Einstellungen?
Aktuell nicht dauerhaft; QSettings ließe sich einfach hinzufügen.

14. Lizenz

MIT‑Lizenz (Projektinhaber eintragen).

searchex kombiniert eine reaktionsschnelle PySide6‑Oberfläche mit einer performanten C++‑Extension, um sehr große Ordnerbäume effizient zu durchsuchen. Benutzer geben mehrere Suchmuster (Plaintext oder Regex) zeilenweise ein und steuern die Suche über Optionen wie Groß‑/Kleinschreibung, Wortgrenzen, Namensabgleich, versteckte Dateien sowie ein Maximal‑Größenlimit. Während der Suche bleibt die UI flüssig: Das native Modul gibt den Python‑GIL frei und Ergebnisse werden in Batches gerendert. Jedes Ergebnis zeigt Dateiname, Pfad, Größe, Trefferanzahl, eindeutige Zeilennummern und eine Text‑ bzw. Hex‑Vorschau. Ein Klick auf „Jump to first hit“ öffnet die Datei direkt an der Fundstelle. Fehlerhafte oder übersprungene Dateien werden transparent gelistet und im Log protokolliert. Für die Distribution kann searchex als Wheel installiert oder mit PyInstaller zu einer portablen Windows‑EXE gebündelt werden.
🌐 Sprache