PYTHON EDITING TOOLS - Python-Dateien bearbeiten
=================================================

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

BESCHREIBUNG
------------
Tools zum Bearbeiten, Analysieren und Aufteilen von Python-Dateien.
Besonders nützlich für:
  - Grosse Python-Dateien (500+ Zeilen)
  - Code-Review und Refactoring
  - LLM-Kontextmanagement (Token sparen)
  - Strukturierte Code-Änderungen

WICHTIG: PYTHON_CLI_EDITOR
==========================
Das Haupt-Tool für Python-Bearbeitung hat eine eigene, ausführliche
Dokumentation wegen seiner Komplexitaet und Wichtigkeit:

  bach --help tools/python_cli_editor

Der python_cli_editor ist speziell für AI-Assistenten gebaut:
  - Struktur anzeigen statt ganze Datei lesen (Token sparen)
  - Gezielt Methoden/Klassen bearbeiten
  - Chirurgische Änderungen statt komplette Rewrites

Kurzübersicht python_cli_editor:
  bach python_cli_editor script.py --show-all      # Struktur anzeigen
  bach python_cli_editor script.py --show 50-80    # Zeilen 50-80
  bach python_cli_editor script.py --imports       # Nur Imports
  bach python_cli_editor script.py --classes       # Nur Klassen
  bach python_cli_editor script.py --add code.py --in-class MyClass --save

Für Details: bach --help tools/python_cli_editor

PYCUTTER: c_pycutter
====================
Zerlegt grosse Python-Dateien in separate Textdateien pro Klasse.

ANWENDUNGSFAELLE:
  - Code-Review: Jede Klasse einzeln betrachten
  - LLM-Kontext: Nur relevante Klasse laden
  - Dokumentation: Klassen-weise Doku erstellen
  - Refactoring: Übersicht bei grossen Dateien

GRUNDBEFEHLE:

  # Datei aufteilen (erstellt Unterordner)
  bach c_pycutter main.py

  # In bestimmten Ordner ausgeben
  bach c_pycutter main.py --output-dir ./extracted

  # JSON-Output (für Weiterverarbeitung)
  bach c_pycutter main.py --json

OPTIONEN:
  --output-dir DIR   Ausgabe-Verzeichnis
  --json             JSON-Output statt Dateien

AUSGABE-STRUKTUR:
  main_20260123_120000/
    Hilfsfunktionen.txt    # Imports, globale Funktionen
    KlasseA.txt            # Code von class KlasseA
    KlasseB.txt            # Code von class KlasseB
    ...

BEISPIEL-WORKFLOW:
  # 1. Grosse Datei aufteilen
  bach c_pycutter riesige_app.py --output-dir ./review
  
  # 2. Einzelne Klasse bearbeiten
  # (in separatem Editor oder mit python_cli_editor)
  
  # 3. Änderungen zurück übernehmen
  # (manuell oder mit Diff-Tool)

METHOD ANALYZER: c_method_analyzer
==================================
Tiefgehende Analyse von Python-Code auf Probleme und Struktur.

FUNKTIONEN:
  - Methoden-Inventar (alle Methoden mit Zeilennummern)
  - Aufruf-Analyse (welche Methode ruft welche auf)
  - Import-Prüfung (genutzt vs. ungenutzt)
  - Tippfehler-Erkennung (ähnliche Namen)
  - Signal-Connect-Prüfung (Qt/Tk)
  - Attribut-vor-Init Erkennung

GRUNDBEFEHLE:

  # Datei analysieren
  bach c_method_analyzer script.py

  # JSON-Output
  bach c_method_analyzer script.py --json

  # Nur Zusammenfassung
  bach c_method_analyzer script.py --summary

  # Bestimmte Klasse analysieren
  bach c_method_analyzer script.py --class MyClass

OPTIONEN:
  --json           JSON-Output (maschinenlesbar)
  --summary        Nur kompakte Zusammenfassung
  --class NAME     Nur bestimmte Klasse analysieren
  --verbose        Detaillierte Ausgabe

AUSGABE-BEISPIEL:
  === METHOD ANALYZER: script.py ===
  
  [KLASSEN]
    MyClass (Zeile 15-120)
      - __init__ (17)
      - process_data (35)
      - _helper (80)  <- nie aufgerufen!
  
  [POTENZIELLE PROBLEME]
    Zeile 42: self._hepler() - Tippfehler? Meinten Sie: _helper
    Zeile 67: self.button.connect(self.on_click) - on_click nicht gefunden
  
  [UNGENUTZTE IMPORTS]
    - import json (Zeile 3)
  
  [STATISTIK]
    Klassen: 2
    Methoden: 15
    Zeilen: 320

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

1. GROSSE DATEI VERSTEHEN
   Erst Struktur, dann Details:
   
   # Überblick bekommen
   bach python_cli_editor grosse_datei.py --show-all
   
   # Oder aufteilen für Review
   bach c_pycutter grosse_datei.py

2. PROBLEME VOR COMMIT FINDEN
   Code analysieren:
   
   bach c_method_analyzer script.py
   
   Zeigt: Tippfehler, ungenutzte Methoden, fehlende Referenzen

3. REFACTORING VORBEREITEN
   Abhängigkeiten verstehen:
   
   # Wer ruft wen auf?
   bach c_method_analyzer script.py --verbose
   
   # Klasse isoliert betrachten
   bach c_pycutter script.py

4. TOKEN SPAREN (AI-Kontext)
   Statt ganze Datei lesen:
   
   # Nur Struktur laden
   bach python_cli_editor script.py --show-all
   
   # Dann gezielt die relevante Methode
   bach python_cli_editor script.py --show 150-180

WANN WELCHES TOOL?
==================

| Aufgabe                      | Tool                |
|------------------------------|---------------------|
| Struktur anzeigen            | python_cli_editor   |
| Gezielt Code ändern         | python_cli_editor   |
| Datei in Teile zerlegen      | c_pycutter          |
| Probleme/Bugs finden         | c_method_analyzer   |
| Imports prüfen              | c_method_analyzer   |
| Tippfehler finden            | c_method_analyzer   |

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

  "python bearbeiten"  -> bach python_cli_editor <datei> --show-all
  "klasse bearbeiten"  -> bach python_cli_editor <datei> --show-all
  "methode bearbeiten" -> bach python_cli_editor <datei> --show-all
  "code struktur"      -> bach python_cli_editor <datei> --show-all
  "datei aufteilen"    -> bach c_pycutter <datei>
  "zu gross"           -> bach c_pycutter <datei>

SIEHE AUCH
----------
  bach --help tools/python_cli_editor  Ausführliche Editor-Doku (WICHTIG!)
  bach --help tools/imports            Import-Handling
  bach --help tools/code_quality       Code-Qualität (Encoding etc.)
  bach --help tools/analysis           Weitere Analyse-Tools
