IMPORT TOOLS - Python Import-Handling
======================================

Stand: 2026-01-23
Pfad: docs/help/tools/imports.txt

BESCHREIBUNG
------------
Tools zur Diagnose und Organisation von Python-Imports:
  - Import-Probleme finden (fehlende, zirkulaere, ungenutzte)
  - Imports sortieren und bereinigen (PEP8-konform)

Haeufige Probleme die diese Tools loesen:
  - "ModuleNotFoundError" / "ImportError"
  - Zirkulaere Imports (A importiert B, B importiert A)
  - Chaotische Import-Reihenfolge
  - Doppelte Imports
  - Imports mitten im Code statt am Anfang

IMPORT DIAGNOSE: c_import_diagnose
==================================
Systematische Analyse von Import-Problemen.

FUNKTIONEN:
  - Einzelne Module isoliert importieren
  - Import-Reihenfolge variieren
  - Zirkulaere Imports erkennen
  - __init__.py analysieren
  - Timing-Tests mit Delays
  - Crash-Punkt lokalisieren

GRUNDBEFEHLE:

  # Projekt analysieren
  bach c_import_diagnose projekt/src/

  # Mit JSON-Ausgabe
  bach c_import_diagnose projekt/src/ --json

  # Bestimmte Module testen
  bach c_import_diagnose . --modules core.app:App,gui.main:MainWindow

OPTIONEN:
  --json                 JSON-Output (maschinenlesbar)
  --modules M1:C1,M2:C2  Spezifische Module:Klassen testen

AUSGABE-BEISPIEL:
  === IMPORT DIAGNOSE ===
  
  [1/5] Einzelne Module testen...
    [OK] core.app.App
    [FAIL] gui.main.MainWindow -> ImportError: No module named 'missing'
  
  [2/5] Zirkulaere Imports prüfen...
    [WARN] core.utils -> core.app -> core.utils (Zirkel!)
  
  [3/5] __init__.py Analyse...
    [OK] core/__init__.py
    [MISSING] gui/__init__.py
  
  === EMPFEHLUNGEN ===
  1. Fehlendes Modul 'missing' installieren
  2. Zirkulaeren Import core.utils <-> core.app aufloesen
  3. gui/__init__.py erstellen

IMPORT ORGANIZER: c_import_organizer
====================================
Sortiert und bereinigt Python-Imports nach PEP8.

FUNKTIONEN:
  - Alle Imports am Dateianfang sammeln
  - Duplikate entfernen
  - Alphabetisch sortieren (erst import, dann from)
  - Mehrfache Leerzeilen bereinigen

GRUNDBEFEHLE:

  # Datei organisieren
  bach c_import_organizer script.py

  # Nur prüfen ohne Änderung
  bach c_import_organizer script.py --dry-run

  # JSON-Ausgabe
  bach c_import_organizer script.py --json

  # Von stdin lesen
  cat script.py | bach c_import_organizer --stdin

OPTIONEN:
  --dry-run   Nur anzeigen, nicht ändern
  --json      JSON-Output
  --stdin     Code von stdin lesen

VORHER/NACHHER BEISPIEL:

  VORHER:
  ---------------------
  import os
  
  def foo():
      from pathlib import Path
      pass
  
  import sys
  from typing import List
  import os  # Duplikat!
  ---------------------

  NACHHER:
  ---------------------
  import os
  import sys
  from pathlib import Path
  from typing import List
  
  def foo():
      pass
  ---------------------

TYPISCHE WORKFLOWS
==================

1. "ImportError" DEBUGGEN
   Projekt analysieren um Crash-Punkt zu finden:
   
   bach c_import_diagnose projekt/src/ --json
   
   Dann Empfehlungen befolgen.

2. ZIRKULAERE IMPORTS FINDEN
   Wenn sich Module gegenseitig importieren:
   
   bach c_import_diagnose projekt/src/
   
   Ausgabe zeigt: A -> B -> A (Zirkel!)
   
   Lösung: Gemeinsame Abhängigkeiten in drittes Modul auslagern.

3. VOR CODE-REVIEW
   Imports aufraumen bevor Code reviewt wird:
   
   bach c_import_organizer script.py
   
   Oder für ganzes Projekt:
   for f in *.py; do bach c_import_organizer "$f"; done

4. NACH REFACTORING
   Nach grossem Umbau Imports prüfen:
   
   # Erst diagnostizieren
   bach c_import_diagnose src/
   
   # Dann aufraumen
   for f in src/*.py; do bach c_import_organizer "$f"; done

5. NEUES PROJEKT EINRICHTEN
   __init__.py Dateien prüfen:
   
   bach c_import_diagnose mein_paket/
   
   Zeigt fehlende __init__.py Dateien an.

PEP8 IMPORT-REIHENFOLGE
=======================
Der c_import_organizer sortiert nach PEP8-Standard:

  1. Standard-Library (import os, import sys)
  2. Third-Party (import requests, import numpy)
  3. Lokale Imports (from . import module)

Innerhalb jeder Gruppe: alphabetisch sortiert.

CONTEXT-INJEKTOR
----------------
Der ContextInjector erkennt Stichwörter und empfiehlt diese Tools:

  "imports sortieren"  -> bach c_import_organizer <datei>
  "import problem"     -> bach c_import_diagnose <projekt>
  "import fehlt"       -> bach c_import_diagnose <projekt>

INTEGRATION MIT ANDEREN TOOLS
=============================
Kombiniere mit python_cli_editor für vollständiges Bild:

  # Imports anzeigen (gruppiert)
  bach python_cli_editor script.py --imports
  
  # Dann organisieren
  bach c_import_organizer script.py

SIEHE AUCH
----------
  bach --help tools/python_editing   Python-Dateien bearbeiten
  bach --help tools/code_quality     Code-Qualität (Encoding etc.)
  bach python_cli_editor --help      Imports anzeigen mit --imports
