ftplib — FTP-Protokoll-Client

Quellcode: Lib/ftplib.py

Dieses Modul definiert die Klasse FTP und einige verwandte Elemente. Die Klasse FTP implementiert die Client-Seite des FTP-Protokolls. Sie können diese verwenden, um Python-Programme zu schreiben, die eine Vielzahl von automatisierten FTP-Aufgaben ausführen, wie z. B. das Spiegeln anderer FTP-Server. Sie wird auch vom Modul urllib.request verwendet, um URLs zu verarbeiten, die FTP verwenden. Weitere Informationen zu FTP (File Transfer Protocol) finden Sie in der Internet- RFC 959.

Die Standardkodierung ist UTF-8, gemäß RFC 2640.

Verfügbarkeit: nicht WASI.

Dieses Modul funktioniert nicht oder ist nicht auf WebAssembly verfügbar. Weitere Informationen finden Sie unter WebAssembly-Plattformen.

Hier ist eine Beispielsitzung, die das Modul ftplib verwendet

>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
'250 Directory successfully changed.'
>>> ftp.retrlines('LIST')           # list directory contents
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()
'221 Goodbye.'

Referenz

FTP-Objekte

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

Gibt eine neue Instanz der Klasse FTP zurück.

Parameter:

  • host (str) – Der Hostname, zu dem eine Verbindung hergestellt werden soll. Wenn angegeben, wird connect(host) implizit vom Konstruktor aufgerufen.

  • user (str) – Der Benutzername, mit dem sich angemeldet werden soll (Standard: 'anonymous'). Wenn angegeben, wird login(host, passwd, acct) implizit vom Konstruktor aufgerufen.

  • passwd (str) – Das Kennwort, das bei der Anmeldung verwendet werden soll. Wenn nicht angegeben und wenn passwd der leere String ist oder "-" ist, wird automatisch ein Kennwort generiert.

  • acct (str) – Kontoinformationen, die für den FTP-Befehl ACCT verwendet werden sollen. Wenige Systeme implementieren dies. Weitere Einzelheiten finden Sie unter RFC-959.

  • timeout (float | None) – Ein Timeout in Sekunden für blockierende Operationen wie connect() (Standard: die globale Standard-Timeout-Einstellung).

  • source_address (tuple | None) – Ein 2-Tupel (host, port) für den Socket, an den er als Quelladresse gebunden werden soll, bevor eine Verbindung hergestellt wird.

  • encoding (str) – Die Kodierung für Verzeichnisse und Dateinamen (Standard: 'utf-8').

Die Klasse FTP unterstützt die with-Anweisung, z. B.

>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
...
'230 Anonymous login ok, restrictions apply.'
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
>>>

Geändert in Version 3.2: Die Unterstützung für die with-Anweisung wurde hinzugefügt.

Geändert in Version 3.3: Der Parameter source_address wurde hinzugefügt.

Geändert in Version 3.9: Wenn der Parameter timeout auf Null gesetzt wird, wird ein ValueError ausgelöst, um die Erstellung eines nicht blockierenden Sockets zu verhindern. Der Parameter encoding wurde hinzugefügt und der Standard wurde von Latin-1 auf UTF-8 geändert, um RFC 2640 zu folgen.

Mehrere Methoden der Klasse FTP sind in zwei Varianten verfügbar: eine für die Verarbeitung von Textdateien und eine andere für Binärdateien. Die Methoden sind nach dem verwendeten Befehl benannt, gefolgt von lines für die Textversion oder binary für die Binärversion.

FTP-Instanzen haben die folgenden Methoden

set_debuglevel(level)

Legt die Debugging-Stufe der Instanz als int fest. Dies steuert die Menge der ausgegebenen Debugging-Informationen. Die Debugging-Stufen sind

  • 0 (Standard): Keine Debug-Ausgabe.

  • 1: Erzeugt eine moderate Menge an Debug-Ausgabe, normalerweise eine Zeile pro Anfrage.

  • 2 oder höher: Erzeugt die maximale Menge an Debug-Ausgabe und protokolliert jede Zeile, die über die Steuerverbindung gesendet und empfangen wird.

connect(host='', port=0, timeout=None, source_address=None)

Stellt eine Verbindung zum angegebenen Host und Port her. Diese Funktion sollte nur einmal pro Instanz aufgerufen werden; sie sollte nicht aufgerufen werden, wenn beim Erstellen der FTP-Instanz ein host-Argument angegeben wurde. Alle anderen FTP-Methoden können nur nach erfolgreicher Verbindung aufgerufen werden.

Parameter:

  • host (str) – Der Host, zu dem die Verbindung hergestellt werden soll.

  • port (int) – Der TCP-Port, zu dem die Verbindung hergestellt werden soll (Standard: 21, wie in der FTP-Protokollspezifikation angegeben). Es ist selten notwendig, eine andere Portnummer anzugeben.

  • timeout (float | None) – Ein Timeout in Sekunden für den Verbindungsversuch (Standard: die globale Standard-Timeout-Einstellung).

  • source_address (tuple | None) – Ein 2-Tupel (host, port) für den Socket, an den er als Quelladresse gebunden werden soll, bevor eine Verbindung hergestellt wird.

Löst ein Audit-Ereignis ftplib.connect mit den Argumenten self, host, port aus.

Geändert in Version 3.3: Der Parameter source_address wurde hinzugefügt.

getwelcome()

Gibt die Willkommensnachricht zurück, die vom Server als Antwort auf die anfängliche Verbindung gesendet wurde. (Diese Nachricht enthält manchmal Haftungsausschlüsse oder Hilfeinformationen, die für den Benutzer relevant sein können.)

login(user='anonymous', passwd='', acct='')

Meldet sich am verbundenen FTP-Server an. Diese Funktion sollte nur einmal pro Instanz aufgerufen werden, nachdem eine Verbindung hergestellt wurde; sie sollte nicht aufgerufen werden, wenn beim Erstellen der FTP-Instanz host- und user-Argumente angegeben wurden. Die meisten FTP-Befehle sind nur erlaubt, nachdem sich der Client angemeldet hat.

Parameter:

  • user (str) – Der Benutzername, mit dem sich angemeldet werden soll (Standard: 'anonymous').

  • passwd (str) – Das Kennwort, das bei der Anmeldung verwendet werden soll. Wenn nicht angegeben und wenn passwd der leere String ist oder "-" ist, wird automatisch ein Kennwort generiert.

  • acct (str) – Kontoinformationen, die für den FTP-Befehl ACCT verwendet werden sollen. Wenige Systeme implementieren dies. Weitere Einzelheiten finden Sie unter RFC-959.

abort()

Bricht eine laufende Dateiübertragung ab. Die Verwendung dieser Methode funktioniert nicht immer, aber es ist einen Versuch wert.

sendcmd(cmd)

Sendet einen einfachen Befehlsstring an den Server und gibt den Antwortstring zurück.

Löst ein Audit-Ereignis ftplib.sendcmd mit den Argumenten self, cmd aus.

voidcmd(cmd)

Sendet einen einfachen Befehlsstring an den Server und verarbeitet die Antwort. Gibt den Antwortstring zurück, wenn der Antwortcode erfolgreich ist (Codes im Bereich 200–299). Löst andernfalls error_reply aus.

Löst ein Audit-Ereignis ftplib.sendcmd mit den Argumenten self, cmd aus.

retrbinary(cmd, callback, blocksize=8192, rest=None)

Ruft eine Datei im Binärübertragungsmodus ab.

Parameter:

  • cmd (str) – Ein geeigneter RETR-Befehl: "RETR filename".

  • callback (callable) – Ein einzelnes Argument tragende aufrufbare Funktion, die für jeden empfangenen Datenblock aufgerufen wird, wobei das einzelne Argument die Daten als bytes sind.

  • blocksize (int) – Die maximale Lese-Chunk-Größe für das Low-Level- socket-Objekt, das für die eigentliche Übertragung erstellt wird. Dies entspricht auch der größten Datengröße, die an callback übergeben wird. Standardwert ist 8192.

  • rest (int) – Ein REST-Befehl, der an den Server gesendet werden soll. Siehe die Dokumentation für den Parameter rest der Methode transfercmd().

retrlines(cmd, callback=None)

Ruft eine Datei oder eine Verzeichnisauflistung in der Kodierung ab, die beim Initialisieren durch den Parameter encoding angegeben wurde. cmd sollte ein geeigneter RETR-Befehl sein (siehe retrbinary()) oder ein Befehl wie LIST oder NLST (normalerweise nur der String 'LIST'). LIST ruft eine Liste von Dateien und Informationen über diese Dateien ab. NLST ruft eine Liste von Dateinamen ab. Die Funktion callback wird für jede Zeile mit einem String-Argument aufgerufen, das die Zeile mit dem abschließenden CRLF entfernt enthält. Der Standard-callback gibt die Zeile auf sys.stdout aus.

set_pasv(val)

Aktiviert den „passiven“ Modus, wenn val wahr ist, andernfalls deaktiviert er den passiven Modus. Der passive Modus ist standardmäßig aktiviert.

storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

Speichert eine Datei im Binärübertragungsmodus.

Parameter:

  • cmd (str) – Ein geeigneter STOR-Befehl: "STOR filename".

  • fp (Datei-Objekt) – Ein Datei-Objekt (im Binärmodus geöffnet), das bis zum EOF gelesen wird, unter Verwendung seiner read()-Methode in Blöcken der Größe blocksize, um die zu speichernden Daten bereitzustellen.

  • blocksize (int) – Die Lese-Blockgröße. Standardwert ist 8192.

  • callback (callable) – Eine einzelnes Argument tragende aufrufbare Funktion, die für jeden gesendeten Datenblock aufgerufen wird, wobei das einzelne Argument die Daten als bytes sind.

  • rest (int) – Ein REST-Befehl, der an den Server gesendet werden soll. Siehe die Dokumentation für den Parameter rest der Methode transfercmd().

Geändert in Version 3.2: Der Parameter rest wurde hinzugefügt.

storlines(cmd, fp, callback=None)

Speichert eine Datei im Zeilenmodus. cmd sollte ein geeigneter STOR-Befehl sein (siehe storbinary()). Zeilen werden bis zum EOF aus dem Datei-Objekt fp (im Binärmodus geöffnet) gelesen, wobei seine readline()-Methode verwendet wird, um die zu speichernden Daten bereitzustellen. callback ist eine optionale einzelnes Argument tragende aufrufbare Funktion, die für jede gesendete Zeile aufgerufen wird.

transfercmd(cmd, rest=None)

Initiiert eine Übertragung über die Datenverbindung. Wenn die Übertragung aktiv ist, sendet es einen EPRT- oder PORT-Befehl und den durch cmd spezifizierten Übertragungsbefehl und nimmt die Verbindung an. Wenn der Server passiv ist, sendet es einen EPSV- oder PASV-Befehl, verbindet sich damit und startet den Übertragungsbefehl. In beiden Fällen wird der Socket für die Verbindung zurückgegeben.

Wenn optional rest angegeben ist, wird ein REST-Befehl an den Server gesendet, wobei rest als Argument übergeben wird. rest ist normalerweise ein Byte-Offset in der angeforderten Datei und teilt dem Server mit, die Bytes der angeforderten Datei ab dem angegebenen Offset erneut zu senden und die anfänglichen Bytes zu überspringen. Beachten Sie jedoch, dass die Methode transfercmd() rest in einen String mit der beim Initialisieren angegebenen encoding-Parameter konvertiert, aber keine Prüfung des Inhalts des Strings durchgeführt wird. Wenn der Server den Befehl REST nicht erkennt, wird eine Ausnahme error_reply ausgelöst. Wenn dies geschieht, rufen Sie einfach transfercmd() ohne rest-Argument auf.

ntransfercmd(cmd, rest=None)

Ähnlich wie transfercmd(), gibt aber ein Tupel aus der Datenverbindung und der erwarteten Größe der Daten zurück. Wenn die erwartete Größe nicht berechnet werden konnte, wird None als erwartete Größe zurückgegeben. cmd und rest haben die gleiche Bedeutung wie in transfercmd().

mlsd(path='', facts=[])

Listet ein Verzeichnis in einem standardisierten Format auf, indem der Befehl MLSD (RFC 3659) verwendet wird. Wenn path weggelassen wird, wird das aktuelle Verzeichnis angenommen. facts ist eine Liste von Strings, die die Art der gewünschten Informationen darstellen (z. B. ["type", "size", "perm"]). Gibt ein Generatorobjekt zurück, das für jede gefundene Datei im Pfad ein Tupel aus zwei Elementen liefert. Das erste Element ist der Dateiname, das zweite ist ein Dictionary, das Fakten über den Dateinamen enthält. Der Inhalt dieses Dictionaries kann durch das Argument facts eingeschränkt sein, aber der Server garantiert nicht, alle angeforderten Fakten zurückzugeben.

Hinzugefügt in Version 3.3.

nlst(argument[, ...])

Gibt eine Liste von Dateinamen zurück, wie sie vom Befehl NLST zurückgegeben werden. Das optionale argument ist ein Verzeichnis, das aufgelistet werden soll (Standard ist das aktuelle Serververzeichnis). Mehrere Argumente können verwendet werden, um Nicht-Standardoptionen an den Befehl NLST zu übergeben.

Hinweis

Wenn Ihr Server den Befehl unterstützt, bietet mlsd() eine bessere API.

dir(argument[, ...])

Erzeugt eine Verzeichnisauflistung, wie sie vom Befehl LIST zurückgegeben wird, und gibt sie auf der Standardausgabe aus. Das optionale argument ist ein Verzeichnis, das aufgelistet werden soll (Standard ist das aktuelle Serververzeichnis). Mehrere Argumente können verwendet werden, um Nicht-Standardoptionen an den Befehl LIST zu übergeben. Wenn das letzte Argument eine Funktion ist, wird es als callback-Funktion wie bei retrlines() verwendet; die Standardeinstellung gibt auf sys.stdout aus. Diese Methode gibt None zurück.

Hinweis

Wenn Ihr Server den Befehl unterstützt, bietet mlsd() eine bessere API.

rename(fromname, toname)

Benennt die Datei fromname auf dem Server in toname um.

delete(filename)

Löscht die Datei mit dem Namen filename vom Server. Bei Erfolg wird der Text der Antwort zurückgegeben, andernfalls wird bei Berechtigungsproblemen error_perm oder bei anderen Fehlern error_reply ausgelöst.

cwd(pathname)

Legt das aktuelle Verzeichnis auf dem Server fest.

mkd(pathname)

Erstellt ein neues Verzeichnis auf dem Server.

pwd()

Gibt den Pfad des aktuellen Verzeichnisses auf dem Server zurück.

rmd(dirname)

Entfernt das Verzeichnis mit dem Namen dirname auf dem Server.

size(filename)

Fordert die Größe der Datei mit dem Namen filename auf dem Server an. Bei Erfolg wird die Größe der Datei als Integer zurückgegeben, andernfalls wird None zurückgegeben. Beachten Sie, dass der Befehl SIZE nicht standardisiert ist, aber von vielen gängigen Serverimplementierungen unterstützt wird.

quit()

Sendet einen QUIT-Befehl an den Server und schließt die Verbindung. Dies ist der „höfliche“ Weg, eine Verbindung zu schließen, aber er kann eine Ausnahme auslösen, wenn der Server auf den Befehl QUIT mit einem Fehler antwortet. Dies beinhaltet einen Aufruf der Methode close(), die die FTP-Instanz für nachfolgende Aufrufe unbrauchbar macht (siehe unten).

close()

Schließt die Verbindung einseitig. Dies sollte nicht auf eine bereits geschlossene Verbindung angewendet werden, z. B. nach einem erfolgreichen Aufruf von quit(). Nach diesem Aufruf sollte die FTP-Instanz nicht mehr verwendet werden (nach einem Aufruf von close() oder quit() können Sie die Verbindung nicht durch Ausgeben einer weiteren login()-Methode wieder öffnen).

FTP_TLS Objekte

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyword-only-separator=None, context=None, timeout=None, source_address=None, encoding='utf-8')

Eine Unterklasse von FTP, die TLS-Unterstützung zu FTP hinzufügt, wie in RFC 4217 beschrieben. Verbindet sich mit Port 21 und sichert die FTP-Steuerverbindung implizit, bevor die Authentifizierung erfolgt.

Hinweis

Der Benutzer muss die Datenverbindung explizit sichern, indem er die Methode prot_p() aufruft.

Parameter:

  • host (str) – Der Hostname, zu dem eine Verbindung hergestellt werden soll. Wenn angegeben, wird connect(host) implizit vom Konstruktor aufgerufen.

  • user (str) – Der Benutzername, mit dem sich angemeldet werden soll (Standard: 'anonymous'). Wenn angegeben, wird login(host, passwd, acct) implizit vom Konstruktor aufgerufen.

  • passwd (str) – Das Kennwort, das bei der Anmeldung verwendet werden soll. Wenn nicht angegeben und wenn passwd der leere String ist oder "-" ist, wird automatisch ein Kennwort generiert.

  • acct (str) – Kontoinformationen, die für den FTP-Befehl ACCT verwendet werden sollen. Wenige Systeme implementieren dies. Weitere Einzelheiten finden Sie unter RFC-959.

  • context (ssl.SSLContext) – Ein SSL-Kontextobjekt, das die Bündelung von SSL-Konfigurationsoptionen, Zertifikaten und privaten Schlüsseln in eine einzige, potenziell langlebige Struktur ermöglicht. Lesen Sie bitte Sicherheitsüberlegungen für bewährte Praktiken.

  • timeout (float | None) – Ein Timeout in Sekunden für blockierende Operationen wie connect() (Standard: die globale Standard-Timeout-Einstellung).

  • source_address (tuple | None) – Ein 2-Tupel (host, port) für den Socket, an den er als Quelladresse gebunden werden soll, bevor eine Verbindung hergestellt wird.

  • encoding (str) – Die Kodierung für Verzeichnisse und Dateinamen (Standard: 'utf-8').

Hinzugefügt in Version 3.2.

Geändert in Version 3.3: Parameter source_address hinzugefügt.

Geändert in Version 3.4: Die Klasse unterstützt nun die Hostnamenprüfung mit ssl.SSLContext.check_hostname und Server Name Indication (siehe ssl.HAS_SNI).

Geändert in Version 3.9: Wenn der Parameter timeout auf Null gesetzt wird, wird ein ValueError ausgelöst, um die Erstellung eines nicht-blockierenden Sockets zu verhindern. Der Parameter encoding wurde hinzugefügt, und der Standardwert wurde von Latin-1 auf UTF-8 geändert, um RFC 2640 zu folgen.

Geändert in Version 3.12: Die veralteten Parameter keyfile und certfile wurden entfernt.

Hier ist eine Beispiel-Sitzung mit der Klasse FTP_TLS

>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Anonymous user logged in'
>>> ftps.prot_p()
'200 Data protection level set to "private"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']

Die Klasse FTP_TLS erbt von FTP und definiert die folgenden zusätzlichen Methoden und Attribute:

ssl_version

Die zu verwendende SSL-Version (Standard ist ssl.PROTOCOL_SSLv23).

auth()

Richtet eine sichere Steuerverbindung ein, indem TLS oder SSL verwendet wird, abhängig davon, was im Attribut ssl_version angegeben ist.

Geändert in Version 3.4: Die Methode unterstützt jetzt die Hostnamenprüfung mit ssl.SSLContext.check_hostname und Server Name Indication (siehe ssl.HAS_SNI).

ccc()

Gibt den Steuerkanal zurück zu Klartext. Dies kann nützlich sein, um Firewalls zu nutzen, die NAT mit unsicherem FTP kennen, ohne feste Ports zu öffnen.

Hinzugefügt in Version 3.3.

prot_p()

Richtet eine sichere Datenverbindung ein.

prot_c()

Richtet eine Klartext-Datenverbindung ein.

Modulvariablen

exception ftplib.error_reply

Ausnahme, die ausgelöst wird, wenn eine unerwartete Antwort vom Server empfangen wird.

exception ftplib.error_temp

Ausnahme, die ausgelöst wird, wenn ein Fehlercode empfangen wird, der einen temporären Fehler angibt (Antwortcodes im Bereich 400–499).

exception ftplib.error_perm

Ausnahme, die ausgelöst wird, wenn ein Fehlercode empfangen wird, der einen permanenten Fehler angibt (Antwortcodes im Bereich 500–599).

exception ftplib.error_proto

Ausnahme, die ausgelöst wird, wenn eine Antwort vom Server empfangen wird, die nicht den Spezifikationen für die Antwort des File Transfer Protocol entspricht, d. h. mit einer Ziffer im Bereich 1-5 beginnt.

ftplib.all_errors

Die Menge aller Ausnahmen (als Tupel), die Methoden von FTP-Instanzen aufgrund von Problemen mit der FTP-Verbindung (im Gegensatz zu Programmierfehlern des Aufrufers) auslösen können. Diese Menge enthält die oben aufgeführten vier Ausnahmen sowie OSError und EOFError.

Siehe auch

Modul netrc

Parser für das Dateiformat .netrc. Die Datei .netrc wird typischerweise von FTP-Clients verwendet, um Benutzerauthentifizierungsinformationen zu laden, bevor der Benutzer aufgefordert wird.