x3
7a1bf948f1
- FileTable(DataTable): links/rechts fuer Datei-Manager-Navigation umgebunden (links = eine Ebene hoch, rechts = Ordner oeffnen); zuvor verschluckte das DataTable-Widget die Tasten - _selected(): liefert jetzt die Klartext-Zeichenkette statt rich.Text-Objekt (behob AttributeError beim Oeffnen/Enter) - action_focus_next(): Tab wechselt zuverlaessig zwischen lokalem und entferntem Paneel (statt unzuverlaessigem focus_next) - install.sh / uninstall.sh: systemweite Installation (PEP-668-konform via /opt/ftptui/venv + /usr/local/bin/ftptui)
362 lines
12 KiB
Markdown
362 lines
12 KiB
Markdown
# 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](#funktionen)
|
||
- [Unterstützte Protokolle](#unterstützte-protokolle)
|
||
- [Installation](#installation)
|
||
- [Verwendung](#verwendung)
|
||
- [Tastaturkürzel](#tastaturkürzel)
|
||
- [Projektstruktur](#projektstruktur)
|
||
- [Architektur](#architektur)
|
||
- [Konfiguration & Profile](#konfiguration--profile)
|
||
- [Entwicklung](#entwicklung)
|
||
- [Testen](#testen)
|
||
- [Lizenz](#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](https://textual.textualize.io/), 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
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```bash
|
||
./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
|
||
|
||
```bash
|
||
pip install .
|
||
```
|
||
|
||
### Als installiertes Kommando
|
||
|
||
Nach `pip install -e .` steht das Kommando `ftptui` global in der Umgebung bereit:
|
||
|
||
```bash
|
||
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
|
||
|
||
| Taste | Aktion |
|
||
|--------------|---------------------------------|
|
||
| `Tab` | Zwischen lokalem und entferntem Paneel wechseln |
|
||
| `↑` / `↓` | Zeilenauswahl bewegen |
|
||
| `→` | Markierten Ordner/Eintrag öffnen |
|
||
| `←` / `⌫` | Eine Verzeichnisebene höher |
|
||
| `Enter` | Ordner öffnen (aktiv: fokussiertes Paneel) |
|
||
| `↑ ..` | Eine Ebene höher (Tabellenzeile) |
|
||
| `l` | Auswahl **herunterladen** (entfernt → lokal) |
|
||
| `u` | Auswahl **hochladen** (lokal → entfernt) |
|
||
| `n` | Neues Verzeichnis anlegen |
|
||
| `d` | Auswahl löschen (rekursiv) |
|
||
| `r` | Auswahl umbenennen |
|
||
| `q` / `Esc` | Beenden |
|
||
|
||
> Hinweis: Hoch-/Herunterladen (`u`/`l`), Anlegen (`n`), 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.
|
||
|
||
---
|
||
|
||
## 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):
|
||
|
||
```python
|
||
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`:
|
||
|
||
```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
|
||
|
||
```bash
|
||
# 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.
|
||
|
||
```bash
|
||
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.*
|