ftptui/README.md

ftptui

Interaktiver FTP- und SFTP-Client als Terminal-User-Interface in Python.

ftptui ist ein schlanker, aber vollwertiger Dateibrowser für die Kommandozeile. Er unterstützt klassisches FTP (RFC 959, über die Python-Standardbibliothek ftplib) sowie SFTP (SSH File Transfer Protocol, über paramiko). Damit deckt das Tool den überwiegenden Teil der realen Dateiübertragungs-Szenarien ab – einschließlich SSH-basiertem FTP.

Das Interface ist zweispaltig aufgebaut:

• links das lokale Dateisystem,
• rechts das entfernte System,

mit Dateiübertragung in beide Richtungen, rekursivem Hoch-/Herunterladen von Verzeichnissen, Anlegen, Umbenennen und Löschen sowie speicherbaren Verbindungsprofilen.

---

Inhaltsverzeichnis

• Funktionen
• Unterstützte Protokolle
• Installation
• Verwendung
• Tastaturkürzel
• Projektstruktur
• Architektur
• Konfiguration & Profile
• Entwicklung
• Testen
• Lizenz

---

Funktionen

• Dual-Pane-Dateibrowser – Layout und Bedienung im Stil von Total Commander / Midnight Commander: zwei benachbarte Panele (lokal & entfernt) mit den Spalten Name, Größe, Datum, einer Pfadleiste oben, einer Statusleiste unten und grün markiertem aktivem Panel.
• Klassisches Terminal-Thema – schlanker Dark-Look angelehnt an den Dateimanager ranger: schwarzer Hintergrund, Verzeichnisse grün/fett, Auswahl per inverser (hellblauer) Markierung.
• FTP über die Standardbibliothek, SFTP über paramiko (SSH-FTP).
• Herunterladen (l) und Hochladen (u) einzelner Dateien.
• Rekursive Übertragung kompletter Verzeichnisbäume.
• Verzeichnisse anlegen (n), umbenennen (r), löschen (d), rekursives Löschen nicht-leerer Ordner.
• Navigation mit Maus/Tastatur, „eine Ebene hoch“ (←/⌫), Enter öffnet.
• Verbindungsprofile werden als JSON unter ~/.config/ftptui/profiles.json gespeichert und können wieder geladen werden.
• Passwortfelder sind abgedunkelt (password=True).
• Gebaut mit dem terminalfreundlichen TUI-Framework Textual, ohne fancy Material-Design – ein „echtes“ Konsolenprogramm.

---

Unterstützte Protokolle

Protokoll	Beschreibung	Bibliothek / Quelle
ftp	Klassisches File Transfer Protocol (RFC 959)	Standard (kein Drittpaket nötig)
sftp	SSH File Transfer Protocol (SSH-FTP)	paramiko

Hinweis: „SSH-FTP“ kann zweierlei bedeuten – das SFTP-Subsystem über eine SSH-Schicht (hier umgesetzt) oder FTP über einen SSH-Tunnel (sog. „FTP over SSH“). In ftptui wird SFTP über SSH unterstützt, der heute übliche und sichere Weg.

---

Installation

Voraussetzungen

• Python ≥ 3.10
• pip und idealerweise eine virtuelle Umgebung

Aus dem Quellverzeichnis

# virtuelle Umgebung anlegen und aktivieren
python3 -m venv .venv
source .venv/bin/activate

# Abhängigkeiten installieren
pip install -e .

# Abhängigkeiten (nur Laufzeit):
#   textual  - TUI-Framework
#   paramiko - SFTP/SSH

Installations- & Deinstallations-Skripte (systemweit)

Im Projektverzeichnis liegen zwei Scripts für eine systemweite Installation auf Debian/Ubuntu (PEP 668 „externally managed“ wird berücksichtigt: es wird eine eigene Umgebung unter /opt/ftptui/venv angelegt und nach /usr/local/bin/ftptui verlinkt):

./install.sh            # systemweit installieren (fragt ggf. nach sudo)
./install.sh --force    # erneut installieren/aktualisieren

./uninstall.sh          # systemweite Installation entfernen (Nutzdaten bleiben)
./uninstall.sh --purge  # zusätzlich Konfigurationsdateien löschen

Nach ./install.sh steht das Kommando ftptui global im PATH bereit.

Als Paket

pip install .

Als installiertes Kommando

Nach pip install -e . steht das Kommando ftptui global in der Umgebung bereit:

ftptui

---

Verwendung

1. Starten: ftptui

2. Im Verbindungsbildschirm die Daten eingeben:

   • Verbindungsprofil – ein zuvor gespeichertes Profil auswählen, oder ein neues anlegen.
   • Protokoll – sftp (SSH) oder ftp.
   • Host, Port (SFTP-Vorgabe 22, FTP-Vorgabe 21), Benutzer, Passwort.
   • Auf Verbinden klicken. Der Port wird bei Protokollwechsel automatisch auf den jeweiligen Standard gesetzt.

3. Nach erfolgreicher Verbindung erscheint der Browser-Bildschirm mit zwei Panelen:

   • links / des lokalen Rechners bzw. das Home-Verzeichnis,
   • rechts das Home-/Root-Verzeichnis des entfernten Systems.

4. Zwischen den Paneelen wechseln mit Tab. Die fokussierte Tabelle erhält die Aktionen (Hoch-/Herunterladen, Umbenennen, Löschen …).

Tipp: Die Aktionen u/l wirken auf das gerade in der fokussierten Tabelle angewählte Element und übertragen in die jeweils andere Seite.

---

Tastaturkürzel

Dateibrowser

Taste	Aktion
Tab	Zwischen lokalem und entferntem Paneel wechseln
↑ / ↓	Zeilenauswahl bewegen
→	Ordner öffnen / Datei ansehen
← / ⌫	Eine Verzeichnisebene höher
Enter	Ordner öffnen, Datei im Betrachter anzeigen
↑ ..	Eine Ebene höher (Tabellenzeile)
Leertaste	Eintrag markieren/abwählen (Cursor rückt weiter)
Strg+A	Alle Einträge markieren / Markierung aufheben
Esc	Markierung des aktiven Paneels aufheben
v	Datei im Betrachter anzeigen
l	Herunterladen (entfernt → lokal)
u	Hochladen (lokal → entfernt)
n	Neues Verzeichnis anlegen
d	Löschen (rekursiv)
r	Umbenennen
q	Beenden

Hinweis: Hoch-/Herunterladen (u/l), Löschen (d) und Umbenennen (r) wirken auf das aktive (grün markierte) Paneel. Wechsel der Seite mit Tab. Die Pfeiltasten →/← navigieren die Verzeichnisstruktur (öffnen / eine Ebene hoch), ↑/↓ bewegen die Zeilenauswahl.

Mehrfachauswahl

Mit der Leertaste markierte Einträge werden fett und gelb dargestellt; die Pfadleiste oben zeigt an, wie viele Einträge je Paneel markiert sind. Liegt eine Markierung vor, arbeiten l, u und d auf allen markierten Einträgen, sonst auf dem Eintrag unter dem Cursor. Nach dem Transfer bzw. beim Verzeichniswechsel wird die Markierung zurückgesetzt.

Datei-Betrachter

Enter oder v auf einer Datei öffnet sie mit Syntax-Hervorhebung; die Sprache wird über Pygments anhand der Endung erkannt (.txt, .md, .py, .cpp, .json, .yml, …). Entfernte Dateien werden dafür in eine Temporärdatei geladen und danach wieder entfernt. Binärdateien und Dateien über 2 MiB werden abgelehnt statt angezeigt.

Taste	Aktion
Esc / q	Betrachter schließen
↑ / ↓	Zeilenweise blättern
Bild↑ / Bild↓	Seitenweise blättern
Pos1 / Ende	Anfang / Ende
w	Zeilenumbruch umschalten
l	Zeilennummern umschalten

Verbindungsdialog

Taste	Aktion
↑ / ↓	Zwischen den Eingabefeldern wechseln
Tab	Nächstes Feld
Enter	In einem Eingabefeld: verbinden; in einer Auswahlliste: Liste öffnen
Strg+S	Profil speichern
Esc	Beenden

---

Projektstruktur

ftptui/
├── pyproject.toml          # Paketmetadaten, Abhängigkeiten, Einstiegspunkt
├── README.md               # diese Dokumentation
├── install.sh              # systemweite Installation (/opt/ftptui/venv)
├── uninstall.sh            # Deinstallation systemweiter Installation
├── .gitignore
└── ftptui/
    ├── __init__.py         # Versionsnummer
    ├── app.py              # Textual-TUI: Verbindungs- & Browser-Bildschirme
    ├── backend.py          # Fabrik: wählt FTP- oder SFTP-Transport
    ├── config.py           # Speicherung/Laden der Verbindungsprofile (JSON)
    ├── models.py           # Datentypen & Transport-Protokoll
    ├── ftp_backend.py      # FTP-Adapter (ftplib)
    └── sftp_backend.py     # SFTP-Adapter (paramiko)

---

Architektur

Die App trennt Oberfläche (Textual) von Transport (Netzwerkprotokolle) durch ein kleines Protokoll/Interface:

• FileTransferBackend (in models.py) definiert die gemeinsame API.
• FTPBackend und SFTPBackend implementieren sie.
• create_backend(protocol) in backend.py liefert den passenden Adapter.

Gemeinsame Schnittstelle (Auszug):

def connect(host, port, username, password) -> None
def listdir(path)            -> list[RemoteEntry]
def chdir(path) / pwd()      -> str
def download(remote, local)  -> None
def upload(local, remote)    -> None
def mkdir(path) / remove / rmdir / rename
def close()                  -> None

RemoteEntry beschreibt einen Eintrag mit name, kind (file/dir), size und modified. Dadurch kann die Oberfläche unabhängig vom Protokoll arbeiten – das Hinzufügen weiterer Backends (z. B. WebDAV) ist ohne Änderung der UI möglich.

Pfadbehandlung

Beide Backends normalisieren Pfade zu absoluten Angaben relativ zum Root des entfernten Systems. FTP-Operationen setzen das Arbeitsverzeichnis vor einer Aktion auf /, sodass Dateiübertragungen unabhängig vom zuletzt betrachteten Ordner zuverlässig funktionieren. SFTP nutzt absolute Pfade direkt.

Profilwertung

Profile werden als JSON in ~/.config/ftptui/profiles.json (bzw. $XDG_CONFIG_HOME/ftptui/profiles.json) gespeichert. Das Passwort wird nur abgelegt, wenn es entsprechend markiert wurde (aktuell standardmäßig direkt gespeichert – Datenschutz-Hinweis siehe unten).

---

Konfiguration & Profile

Profile speichern: im Verbindungsbildschirm Daten eingeben und Profil speichern drücken. Gespeicherte Einträge erscheinen künftig im Dropdown Verbindungsprofil.

Beispieldatei ~/.config/ftptui/profiles.json:

[
  {
    "name": "git.sysdaemon.xyz",
    "protocol": "sftp",
    "host": "git.sysdaemon.xyz",
    "port": 22,
    "username": "user",
    "password": "",
    "save_password": false
  },
  {
    "name": "backup-server",
    "protocol": "ftp",
    "host": "backup.local",
    "port": 21,
    "username": "ftpuser",
    "password": "secret",
    "save_password": true
  }
]

Sicherheitshinweis: Speichern Sie Passwörter in Profilen nur auf vertrauenswürdigen Systemen. Die Datei liegt im Klartext im Benutzerverzeichnis.

---

Entwicklung

# Umgebung
python3 -m venv .venv && source .venv/bin/activate
pip install -e . "textual>=0.80.0" "paramiko>=3.4.0"

# Laufzeit prüfen
python -c "import ftptui; print(ftptui.__version__)"

# App booten (Konsolen-Test)
ftptui

Code-Stil & Qualität

• Typannotationen (from __future__ import annotations) durchgängig.
• Protokoll-/Interface-basierte Implementierung mit typing.Protocol.
• Keine Abhängigkeit auf Drittanbieter außer textual und paramiko.

---

Testen

Die Backends werden gegen lokale Testserver end-to-end getestet:

• FTP gegen pyftpdlib (nur für Tests; nicht Teil der Laufzeit-Abhängigkeiten),
• SFTP gegen eine eigene paramiko-SSH-Server-Implementierung.

Ablauf der Tests: Verbinden, Listings, Download, Upload, mkdir, rename, remove, rekursives rmdir, close – für beide Protokolle.

pip install pyftpdlib
python tests/test_backends.py   # Beispieldatei (siehe Entwicklung/Skripte)

Ein ausführbares Testskript kann ergänzt und an dieser Stelle dokumentiert werden; die Backends sind derart modular, dass sie ohne Terminal getestet werden können.

---

Lizenz

MIT – siehe Projektträger/Repositories. Keine gewerblichen Einschränkungen.

---

Changelog

v0.3.0

• Bugfix (Pfeil-Navigation): Im Dateibrowser navigieren die Pfeiltasten nun im File-Manager-Stil: ← wechselt eine Ebene nach oben, → öffnet den markierten Eintrag, ↑/↓ bewegen die Auswahl. Zuvor verschluckte das DataTable-Widget die Tasten (Widget-Bindings haben Vorrang). Dafür wird die neue FileTable-Klasse genutzt, die left/right passend umbindet.
• Bugfix (Tab-Panel-Wechsel): Tab wechselt jetzt zuverlässig zwischen dem lokalen und dem entfernten Paneel (explizite action_focus_next statt unzuverlässigem focus_next).
• Bugfix (_selected): Die Auswahlauswertung liefert jetzt die Klartext-Zeichenkette statt eines rich.Text-Objekts, wodurch Öffnen/Enter nicht mehr mit AttributeError abstürzte.
• Neu: install.sh / uninstall.sh für systemweite Installation (PEP-668-konform via /opt/ftptui/venv + /usr/local/bin/ftptui).

v0.2.0

• Bugfix: Wechsel in den Browser-Bildschirm korrigiert (set_screen → switch_screen). Vorher führte eine erfolgreiche Verbindung in einen AttributeError und der FTP/SFTP-Client beendete sich.
• Theme: Umstellung auf ein klassisches Terminal-Design im Stil von ranger (Dark-Look, grün/fette Verzeichnisse, inverse Auswahl).
• Layout: Neuaufbau als Total-Commander-artiger Dual-Pane-Browser mit Pfadleiste oben, Statusleiste unten und grün markiertem aktivem Panel.
• Datums-Spalte wird nun als lesbares Datum (YYYY-MM-DD HH:MM) angezeigt.

v0.1.0

• Erste Veröffentlichung: FTP- & SFTP-Backends, TUI, Verbindungsprofile.

---

Projekt wird innerhalb der sysdaemon.xyz-Instanz über Gitea verwaltet – https://git.sysdaemon.xyz/x3/ftptui.