ftplib — FTP-protokollklient

Källkod: Lib/ftplib.py

Denna modul definierar klassen FTP och några relaterade objekt. Klassen FTP implementerar klientsidan av FTP-protokollet. Du kan använda den för att skriva Python-program som utför en mängd olika automatiserade FTP-jobb, till exempel spegling av andra FTP-servrar. Den används också av modulen urllib.request för att hantera webbadresser som använder FTP. För mer information om FTP (File Transfer Protocol), se internet RFC 959.

Standardkodningen är UTF-8, i enlighet med RFC 2640.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Här är ett exempel på en session med ftplib-modulen:

>>> 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.'

Referens

FTP-objekt

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

Returnerar en ny instans av FTP-klassen.

Parametrar:

  • host (str) – Värdnamnet att ansluta till. Om det anges anropas connect(host) implicit av konstruktören.

  • user (str) – The username to log in with (default: 'anonymous'). Om den anges anropas login(host, passwd, acct) implicit av konstruktören.

  • passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

  • timeout (float | None) – En timeout i sekunder för blockerande operationer som connect() (standard: den globala standardinställningen för timeout).

  • source_address (tuple | None) – A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

  • encoding (str) – The encoding for directories and filenames (default: 'utf-8').

Klassen FTP har stöd för with, t.ex:

>>> 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
>>>

Ändrad i version 3.2: Stöd för with statement har lagts till.

Ändrad i version 3.3: parametern source_address har lagts till.

Ändrad i version 3.9: Om parametern timeout är noll kommer den att skapa ett ValueError för att förhindra att en icke-blockerande socket skapas. Parametern encoding har lagts till och standardvärdet har ändrats från Latin-1 till UTF-8 för att följa RFC 2640.

Flera FTP-metoder finns i två varianter: en för hantering av textfiler och en för binära filer. Metoderna namnges efter det kommando som används följt av lines för textversionen eller binary för den binära versionen.

FTP-instanser har följande metoder:

set_debuglevel(level)

Ställ in instansens felsökningsnivå som en int. Detta styr hur mycket felsökningsutdata som skrivs ut. Felsökningsnivåerna är:

  • 0 (standard): Ingen felsökning.

  • 1: Producerar en måttlig mängd felsökningsutdata, i allmänhet en enda rad per begäran.

  • 2 eller högre: Producerar den maximala mängden felsökningsutdata och loggar varje rad som skickas och tas emot på kontrollanslutningen.

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

Anslut till den angivna värden och porten. Den här funktionen ska bara anropas en gång för varje instans; den ska inte anropas om ett host-argument angavs när FTP-instansen skapades. Alla andra FTP-metoder kan endast anropas efter att en anslutning har upprättats.

Parametrar:

  • host (str) – Värd att ansluta till.

  • port (int) – TCP-porten att ansluta till (standard: 21, enligt specifikationen för FTP-protokollet). Det är sällan nödvändigt att ange ett annat portnummer.

  • timeout (float | None) – En timeout i sekunder för anslutningsförsöket (standard: den globala standardinställningen för timeout).

  • source_address (tuple | None) – A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

Utlöser en auditing event ftplib.connect med argumenten self, host, port.

Ändrad i version 3.3: parametern source_address har lagts till.

getwelcome()

Returnerar välkomstmeddelandet som skickas av servern som svar på den första anslutningen. (Meddelandet innehåller ibland friskrivningsklausuler eller hjälpinformation som kan vara relevant för användaren)

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

Logga in på den anslutna FTP-servern. Den här funktionen ska bara anropas en gång för varje instans, efter att en anslutning har upprättats; den ska inte anropas om argumenten host och user gavs när FTP-instansen skapades. De flesta FTP-kommandon är endast tillåtna efter att klienten har loggat in.

Parametrar:

  • user (str) – The username to log in with (default: 'anonymous').

  • passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

abort()

Avbryter en filöverföring som pågår. Det är inte alltid det fungerar, men det är värt ett försök.

sendcmd(cmd)

Skicka en enkel kommandosträng till servern och returnera svarssträngen.

Utlöser en auditing event ftplib.sendcmd med argumenten self, cmd.

voidcmd(cmd)

Skicka en enkel kommandosträng till servern och hantera svaret. Returnera svarssträngen om svarskoden motsvarar framgång (koder i intervallet 200–299). Annars visas error_reply.

Utlöser en auditing event ftplib.sendcmd med argumenten self, cmd.

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

Hämtar en fil i binärt överföringsläge.

Parametrar:

  • cmd (str) – Ett lämpligt RETR-kommando: "RETR filename".

  • callback (callable) – En anropsbar parameter med en enda parameter som anropas för varje block med data som tas emot, där det enda argumentet är data i form av bytes.

  • blocksize (int) – Den maximala bitstorleken som ska läsas på lågnivåobjektet socket som skapats för att göra den faktiska överföringen. Detta motsvarar också den största storleken på data som kommer att skickas till callback. Standardvärde är 8192.

  • rest (int) – Ett REST-kommando som ska skickas till servern. Se dokumentationen för parametern rest i metoden transfercmd().

retrlines(cmd, callback=None)

Hämtar en fil- eller kataloglista i den kodning som anges av parametern encoding vid initieringen. cmd bör vara ett lämpligt RETR-kommando (se retrbinary()) eller ett kommando som LIST eller NLST (vanligtvis bara strängen 'LIST'). LIST hämtar en lista med filer och information om dessa filer. NLST hämtar en lista med filnamn. Funktionen callback anropas för varje rad med ett strängargument som innehåller raden utan efterföljande CRLF. Standardvärdet för callback skriver ut raden till sys.stdout.

set_pasv(val)

Aktivera ”passivt” läge om val är true, annars inaktivera passivt läge. Passivt läge är aktiverat som standard.

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

Lagra en fil i binärt överföringsläge.

Parametrar:

  • cmd (str) – Ett lämpligt STOR-kommando: "STOR filename".

  • fp (file object) – Ett filobjekt (öppnat i binärt läge) som läses till EOF med hjälp av metoden read() i block av storleken blocksize för att tillhandahålla de data som ska lagras.

  • blocksize (int) – Storleken på läsblocket. Standardvärdet är 8192.

  • callback (callable) – En anropsbar parameter med en enda parameter som anropas för varje block med data som skickas, där det enda argumentet är data i form av bytes.

  • rest (int) – Ett REST-kommando som ska skickas till servern. Se dokumentationen för parametern rest i metoden transfercmd().

Ändrad i version 3.2: Parametern rest har lagts till.

storlines(cmd, fp, callback=None)

Lagra en fil i linjeläge. cmd bör vara ett lämpligt STOR-kommando (se storbinary()). Rader läses till EOF från file object fp (öppnat i binärt läge) med hjälp av dess readline()-metod för att tillhandahålla de data som ska lagras. callback är en valfri enparameters callable som anropas på varje rad efter att den har skickats.

transfercmd(cmd, rest=None)

Starta en överföring via dataanslutningen. Om överföringen är aktiv, skicka ett EPRT- eller PORT-kommando och det överföringskommando som anges av cmd, och acceptera anslutningen. Om servern är passiv, skicka ett EPSV eller PASV-kommando, anslut till den och starta överföringskommandot. Returnera i vilket fall som helst socket för anslutningen.

Om rest anges som tillval skickas ett REST-kommando till servern med rest som argument. rest är vanligtvis en byte-offset i den begärda filen, som talar om för servern att börja om med att skicka filens byte vid den begärda offseten, och hoppa över de första bytena. Observera dock att metoden transfercmd() konverterar rest till en sträng med parametern encoding som anges vid initialiseringen, men att ingen kontroll görs av strängens innehåll. Om servern inte känner igen kommandot REST, kommer ett error_reply undantag att uppstå. Om detta händer, anropa helt enkelt transfercmd() utan ett rest-argument.

ntransfercmd(cmd, rest=None)

Som transfercmd(), men returnerar en tupel av dataanslutningen och den förväntade storleken på data. Om den förväntade storleken inte kunde beräknas returneras None som den förväntade storleken. cmd och rest betyder samma sak som i transfercmd().

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

Lista en katalog i ett standardiserat format med hjälp av kommandot MLSD (RFC 3659). Om path utelämnas antas den aktuella katalogen. facts är en lista med strängar som representerar den typ av information som önskas (t.ex. ["type", "size", "perm"]). Returnerar ett generatorobjekt som ger en tupel med två element för varje fil som hittas i sökvägen. Det första elementet är filnamnet, det andra är en ordbok som innehåller fakta om filnamnet. Innehållet i denna ordbok kan begränsas av argumentet facts, men det är inte säkert att servern returnerar alla begärda fakta.

Tillagd i version 3.3.

nlst(argument[, ...])

Returnerar en lista med filnamn som returneras av kommandot NLST. Det valfria argument är en katalog som ska listas (standard är den aktuella serverkatalogen). Flera argument kan användas för att skicka icke-standardiserade alternativ till kommandot NLST.

Anteckning

Om din server har stöd för kommandot erbjuder mlsd() ett bättre API.

dir(argument[, ...])

Skapar en kataloglista som returneras av kommandot LIST och skriver ut den till standardutdata. Det valfria argument är en katalog som ska listas (standard är den aktuella serverkatalogen). Flera argument kan användas för att skicka icke-standardiserade alternativ till kommandot LIST. Om det sista argumentet är en funktion används den som en callback-funktion som för retrlines(); standardutskriften är till sys.stdout. Denna metod returnerar None.

Anteckning

Om din server har stöd för kommandot erbjuder mlsd() ett bättre API.

rename(fromname, toname)

Byt namn på filen fromname på servern till toname.

delete(filename)

Tar bort filen med namnet filnamn från servern. Om det lyckas returneras texten i svaret, annars visas error_perm vid behörighetsfel eller error_reply vid andra fel.

cwd(pathname)

Ange den aktuella katalogen på servern.

mkd(pathname)

Skapa en ny katalog på servern.

pwd()

Returnerar sökvägen till den aktuella katalogen på servern.

rmd(dirname)

Ta bort katalogen med namnet dirname på servern.

size(filename)

Begär storleken på filen med namnet filnamn på servern. Vid framgång returneras filens storlek som ett heltal, annars returneras None. Observera att kommandot SIZE inte är standardiserat, men stöds av många vanliga serverimplementationer.

quit()

Skicka ett QUIT-kommando till servern och stäng anslutningen. Detta är det ”artiga” sättet att stänga en anslutning, men det kan ge upphov till ett undantag om servern svarar med ett fel på kommandot QUIT. Detta innebär ett anrop till close()-metoden som gör FTP-instansen värdelös för efterföljande anrop (se nedan).

close()

Stäng anslutningen ensidigt. Detta bör inte tillämpas på en redan stängd anslutning, t.ex. efter ett lyckat anrop till quit(). Efter detta anrop ska instansen FTP inte användas mer (efter ett anrop till close() eller quit() kan du inte öppna anslutningen igen genom att utfärda en annan login()-metod).

FTP_TLS-objekt

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

En FTP-underklass som lägger till TLS-stöd för FTP enligt beskrivningen i RFC 4217. Anslut till port 21, vilket implicit säkrar FTP-kontrollanslutningen innan autentisering.

Anteckning

Användaren måste uttryckligen säkra dataanslutningen genom att anropa metoden prot_p().

Parametrar:

  • host (str) – Värdnamnet att ansluta till. Om det anges anropas connect(host) implicit av konstruktören.

  • user (str) – The username to log in with (default: 'anonymous'). Om den anges anropas login(host, passwd, acct) implicit av konstruktören.

  • passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

  • context (ssl.SSLContext) – Ett SSL-kontextobjekt som gör det möjligt att samla SSL-konfigurationsalternativ, certifikat och privata nycklar i en enda, potentiellt långlivad, struktur. Läs Överväganden om säkerhet för bästa praxis.

  • timeout (float | None) – En tidsgräns i sekunder för blockering av åtgärder som connect() (standard: den globala standardinställningen för tidsgräns).

  • source_address (tuple | None) – A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

  • encoding (str) – The encoding for directories and filenames (default: 'utf-8').

Tillagd i version 3.2.

Ändrad i version 3.3: Parametern source_address har lagts till.

Ändrad i version 3.4: Klassen stöder nu kontroll av värdnamn med ssl.SSLContext.check_hostname och Server Name Indication (se ssl.HAS_SNI).

Ändrad i version 3.9: Om parametern timeout är noll kommer den att skapa ett ValueError för att förhindra att en icke-blockerande socket skapas. Parametern encoding har lagts till och standardvärdet har ändrats från Latin-1 till UTF-8 för att följa RFC 2640.

Ändrad i version 3.12: De föråldrade parametrarna keyfile och certfile har tagits bort.

Här är ett exempel på en session som använder FTP_TLS class:

>>> 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']

klassen FTP_TLS ärver från klassen FTP och definierar dessa ytterligare metoder och attribut:

ssl_version

Den SSL-version som ska användas (standard är ssl.PROTOCOL_SSLv23).

auth()

Skapa en säker kontrollanslutning med hjälp av TLS eller SSL, beroende på vad som anges i attributet ssl_version.

Ändrad i version 3.4: Metoden stöder nu kontroll av värdnamn med ssl.SSLContext.check_hostname och Server Name Indication (se ssl.HAS_SNI).

ccc()

Återställer kontrollkanalen till klartext. Detta kan vara användbart för att dra nytta av brandväggar som vet hur man hanterar NAT med icke-säker FTP utan att öppna fasta portar.

Tillagd i version 3.3.

prot_p()

Upprätta en säker dataanslutning.

prot_c()

Upprätta dataanslutning i klartext.

Modulvariabler

exception ftplib.error_reply

Undantag som uppstår när ett oväntat svar tas emot från servern.

exception ftplib.error_temp

Undantag som uppstår när en felkod som innebär ett temporärt fel (svarskoder i intervallet 400–499) tas emot.

exception ftplib.error_perm

Undantag som uppstår när en felkod som innebär ett permanent fel (svarskoder i intervallet 500–599) tas emot.

exception ftplib.error_proto

Undantag som uppstår när ett svar tas emot från servern som inte uppfyller svarsspecifikationerna för File Transfer Protocol, dvs. börjar med en siffra i intervallet 1–5.

ftplib.all_errors

Uppsättningen av alla undantag (som en tupel) som metoder i FTP-instanser kan ge upphov till på grund av problem med FTP-anslutningen (i motsats till programmeringsfel som gjorts av den som anropar). Denna uppsättning innehåller de fyra undantagen som listas ovan samt OSError och EOFError.

Se även

Modul netrc

Parser för filformatet .netrc. Filen .netrc används vanligtvis av FTP-klienter för att läsa in information om användarautentisering innan användaren tillfrågas.