11.7.1 Oggetti FTP

Parecchi metodi sono disponibili in due versioni: uno per gestire testo ed un'altro per i file binari. Questi vengono chiamati per i comandi che vengono usati, seguiti da "lines" per la versione testo e "binary" per la versione binaria.

Le istanze FTP hanno i seguenti metodi:

set_debuglevel( level): Imposta il livello level di debugging dell'istanza. Questo controlla l'ammontare del quantitativo di messaggi stampati. Il valore predefinito è 0, non produce alcun output di debugging. Un valore di 1 produce un quantitativo moderato di messaggi di output, generalmente una singola riga per richiesta. Un valore di 2 o maggiore produce il massimo quantitativo di messaggi di debugging, registrando ogni riga inviata e ricevuta sulla connessione sotto controllo.

connect( host[, port]): Si connette agli host e port passati. Il numero predefinito per la porta port è 21, come indicato dalle specifiche del protocollo FTP. Raramente è necessario specificare un numero differente di porta. Questa funzione dovrebbe essere chiamata solo una volta per istanza; non dovrebbe essere chiamata mai se un host è già stato fornito quando l'istanza è stata creata. Tutti gli altri metodi possono essere usati dopo che la connessione è stata stabilita.

getwelcome( ): Restituisce il messaggio di benvenuto inviato dal server in risposta alla connessione iniziale. Questo messaggio, qualche volta, contiene avvisi o informazioni di aiuto che possono essere rilevanti per l'utente.

login( [user[, passwd[, acct]]]): Si connette con l'utente user passato. I parametri passwd ed acct sono facoltativi e, in modo predefinito, sono stringhe vuote. Se non viene specificato nessun user, il predefinito viene impostato ad 'anonymous'. Se l'utente user è 'anonymous', la password predefinita è 'anonymous@'. Questa funzione dovrebbe essere chiamata solamente una volta per ogni istanza, dopo che una connessione è stata stabilita; non dovrebbe essere chiamata mai se un host ed un utente vengono forniti quando è stata creata l'istanza. Molti comandi FTP sono consentiti solamente dopo che il client si è autenticato.

abort( ): Annulla un trasferimento file che è in corso. L'uso di questo metodo non sempre funziona, ma vale la pena di fare una prova.

sendcmd( command): Invia una semplice stringa di comando al server e restituisce una stringa di risposta.

voidcmd( command): Invia una semplice stringa di comando al server e gestisce la risposta. Non restituisce niente se viene ricevuto un codice di risposta nell'intervallo 200-299. Altrimenti solleva un'eccezione.

retrbinary( command, callback[, maxblocksize[, rest]]): Recupera un file usando il modo di trasferimento binario. command dovrebbe essere un comando appropriato "RETR": 'RETR filename'. La funzione callback viene chiamata per ogni blocco di dati ricevuti, con un singolo argomento stringa contenente il blocco di dati. L'argomento facoltativo maxblocksize specifica la misura massima del blocco da leggere sull'oggetto socket di basso livello, creato per eseguire il trasferimento in corso (che sarà anche la misura massima del blocco di dati passato al callback). Viene scelto un ragionevole valore predefinito. rest ha lo stesso significato che ha nel metodo transfercmd().

retrlines( command[, callback]): Restituisce un elenco di file o directory in modalità di trasferimento ASCII. command dovrebbe essere un appropriato comando "RETR" (vedere retrbinary()) o un comando "LIST"(tipicamente solo la stringa 'LIST'). La funzione callback viene chiamata per ogni riga, rimuovendo il carattere CRLF. La callback, stampa in modo predefinito la riga su sys.stdout.

set_pasv( boolean): Abilita la modalità ``passiva'' se boolean è vera, altrimenti disabilita la modalità passiva. In Python 2.0 e successivi, la modalità passiva veniva impostata al valore predefinito off; dalla versione 2.1 in poi, viene impostata al valore predefinito on.

storbinary( command, file[, blocksize]): Memorizza un file nella modalità trasferimento binaria. command dovrebbe essere un appropriato comando "STOR": ``STOR nomefile''. file è un oggetto file aperto che viene letto fino ad EOF usando il proprio metodo read() in blocchi di misura blocksize che ha il valore predefinito 8192. Modificato nella versione 2.1: è stato aggiunto un valore predefinito per blocksize.

storlines( command, file): Memorizza un file usando la modalità di trasferimento ASCII. command dovrebbe essere un appropriato comando "STOR"(vedere storbinary()). Le righe vengono lette fino all'EOF da un oggetto file aperto usando il proprio metodo readline() che deve fornire i dati da memorizzare.

transfercmd( cmd[, rest]): Inizia un trasferimento sopra la connessione dati. Se il trasferimento è attivo, invia un comando "EPRT" o "PORT", il comando di trasferimento specificato da cmd, e accetta la connessione. Se il server lavora in modalità passiva, invia un comando "EPSV" o "PASV", si connette, e avvia il comando di trasferimento. In entrambi i casi, restituisce il socket per la connessione.
Se viene fornita l'opzione rest, allora viene inviato un comando "REST" al server, passando rest come un argomento. rest è usualmente una posizione in byte all'interno del file richiesto, chiedendo al server di ricominciare nuovamente ad inviare i byte del file dalla posizione indicata, saltando sui byte iniziali. Notare, comunque, che la RFC 959 richiede solamente che rest sia una stringa contenente caratteri nell'intervallo stampabile dal codice ASCII 33 al codice ASCII 126. Il metodo transfercmd(), comunque, converte rest in una stringa, ma non ne controlla la validità del contenuto. Se il server non riconosce il comando "REST", verrà sollevata un'eccezione error_reply. Se questo avviene, chiamare semplicemente transfercmd() senza il comando rest.

ntransfercmd( cmd[, rest]): Come transfercmd(), ma restituisce una tupla della connessione dati e la dimensione attesa dei dati. Se la dimensione attesa non può essere calcolata, verrà restituito, come dimensione attesa, None. cmd e rest hanno lo stesso significato degli equivalenti in transfercmd().

nlst( argument[, ...]): Restituisce un elenco di file come restituito dal comando "NLST". L'argomento facoltativo argument è una directory da elencare (il suo valore predefinito è la directory corrente del server). Argomenti multipli possono essere usati per inviare opzioni non standard al comando "NLST".

dir( argument[, ...]): Produce un elenco del contenuto della directory come restituito dal comando "LIST", inviandolo allo standard output. L'argomento facoltativo argument è una directory da elencare (il suo valore predefinito è la directory corrente del server). Argomenti multipli possono essere usati per inviare opzioni non standard al comando "LIST". Se l'ultimo argomento è una funzione, questa viene usata come funzione di callback come per retrlines(); in modo predefinito, questa funzione stampa su sys.stdout. Il metodo restituisce None.

rename( fromname, toname): Rinomina il file sul server fromname in toname.

delete( filename): Rimuove il file filename dal server. Se ha successo, restituisce il testo della risposta, altrimenti solleva l'eccezione error_perm su errori di permessi o error_reply su altri errori.

cwd( pathname): Imposta la directory corrente sul server.

mkd( pathname): Crea una nuova directory sul server.

pwd( ): Restituisce il nome della directory corrente sul sul server.

rmd( dirname): Rimuove la directory dirname sul server.

size( filename): Richiede la dimensione del file filename sul server. In caso di successo, viene restituita la dimensione del file come un intero, altrimenti viene restituito None. Notare che il comando "SIZE" non è standardizzato, ma viene supportato da molte comuni implementazioni di server.

quit( ): Invia un comando "QUIT" al server e chiude la connessione. Questo è il modo corretto di chiudere una connessione, ma può sollevare un'eccezione nel caso che il server risponda con un errore al comando "QUIT". Questo richiede una chiamata al metodo close() che rende l'istanza FTP inutile per chiamate successive (vedere sotto).

close( ): Chiude la connessione unilateralmente. Questo non dovrebbe essere applicato ad una connessione già chiusa come in seguito ad una chiamata quit() eseguita con successo. Dopo questa chiamata, l'istanza FTP non dovrebbe più essere usata (dopo una chiamata a close() o quit() non si può riaprire una connessione richiamando il metodo login()).

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.