11.5.1 Objets FTP

Plusieurs méthodes sont disponibles sous deux formes: l'une pour gérer des fichiers binaires, l'autre pour des fichiers texte. Elles sont appelées d'après le nom de la commande FTP utilisée, suivie de "lines" pour la version texte et de "binary" pour la version binaire.

Les instances de FTP possèdent les méthodes suivantes:

set_debuglevel(niveau)

Détermine le niveau de débogage de l'instance. Contrôle le volume d'informations de débogage produit. La valeur par défaut, 0, ne produit aucune information de débogage. Un evaleur de 1 produit un volume modéré d'informations de débogage, en général une seule lignepar requête. Une valeur de 2 ou plus produit le volume d'informations de débogage maximum, traçant toutes les lignes envoyées et reçues sur la connexion de contrôle.

connect(hote[, port])

Connecte à l'hôte et au port indiqués. Le numéro de port par défaut est 21, comme spécifié par le protocole FTP. Il est rarement nécessaire de spécifier un numéro de port différent. Cette fonction ne doit être appelée qu'une seule fois pour chaque instance; elle ne doit pas être âppelée du tout si un hôte était précisé quand l'instance a été créée. Toutes les autres méthodes ne peuvent être utilisées qu'après qu'une connexion a été établie.

getwelcome()

Retourne le message d'accueil envoyé par le serveur en réponse à la connexion initiale. (Ce message contient parfois des avis de non-responsabilité ou des informations d'aide qui peuvent être pertinents pour l'utilisateur.)

login([utilisateur[, motdepasse[, compte]]])

Ouvre une session sous le nom d'utilisateur indiqué. Les paramètres motdepasse et compte sont optionnels et sont par défaut des chaînes vides. Si aucun nom d'utilisateur n'est spécifié, il vaut par défaut 'anonymous'. Si utilisateur est 'anonymous', motdepasse prend par défaut la valeur "utilisateur_reel@hote" où utilisateur_reel est le nom de l'utilisateur réel (obtenu d'après la variable d'environnement $LOGNAME ou $USER) et hote est le nom d'hôte tel que retourné par socket.gethostname(). Cette fonction ne doit être appelée qu'une seule fois pour chaque instance, après qu'une connexion a été établie; elle ne doit pas être appelée du tout si un nom d'hôte et d'utilisateur ont été donnés quand l'instance a été créée. La plupart des commandes FTP ne sont autorisées qu'après que le client a ouvert la session.

abort()

Abandonne une transfert de fichier en cours. Cette méthode ne fonctionne pas toujours, mais ça vaut le coup d'essayer.

sendcmd(commande)

Envoie une simple chaîne de commande au serveur et retourne la chaîne de réponse.

voidcmd(commande)

Envoie une simple chaîne de commande au serveur et gère la réponse. Ne retourne rien si une réponse dans l'intervalle 200--299 est reçue ; déclenche une exception sinon.

retrbinary(commande, rappel[, tailleblocmax[, reste]])

Récupère un fichier en mode de transfert binaire. commande doit être une commande "RETR" appropriée, c'est-à-dire 'RETR nomfichier'. La fonction rappel est appelée pour chaque bloc de données reçu, avec un seul argument chaîne donnant le bloc de données. L'argument optionnel tailleblocmax spécifie la taille maximum de tronçon à lire sur l'objet socket de bas niveau créé pour effectuer le transfert effectif (ce sera aussi la taille maximum des blocs de données passés à rappel). Une valeur par défaut raisonnable est choisie. reste a la même signification que dans la méthode transfercmd().

retrlines(commande[, rappel])

Récupère un fichier ou un listage de répertoire en mode de transfert ASCII. commande doit être un commande "RETR" appropriée (voir retrbinary()) ou une commande "LIST" (en général, juste la chaîne 'LIST'). La fonction rappel est appelée pour chaque ligne, avec le CRLF enlevé. Le rappel par défut imprime la ligne sur sys.stdout.

set_pasv(booleen)

Active le mode ``passif'' si booleen est vrai, sinon désactive le mode passif.

storbinary(commande, fichier, taillebloc)

Stocke un fichier en mode de transfert binaire. commande doit être une commande "STOR" appropriée, c'est-à-dire "STOR nomfichier". fichier est un objet fichier ouvert qui est lu jusqu'à EOF en se servant de sa méthode read() par blocs de taille taillebloc pour fournir les données à stocker.

storlines(commande, fichier)

Stocke un fichier en mode de transfert ASCII. commande doit être une commande "STOR" appropriée (voir storbinary()). Les lignes sont lues jusqu'à EOF depuis l'objet fichier ouvert ficier en se servant de sa méthode readline() pour fournir les données à stocker.

transfercmd(cmd[, reste])

Initie un transfert sur la connexion de données. Si le transfert est actif, envoie une commande "PORT" et la commande de transfert spécifiée par cmd, et accepte la connexion. Si le serveur est passif, envoie une commande "PASV", se connecte, et commence la commande de transfert. Dans tous les cas, retourne la socket pour la connexion.

Si l'option reste est fournie, une commande "REST" est envoyée au serveur, en passant reste comme argument. reste est généralement un décalage en octets dans le fichier demandé, pour dire au serveur de recommencer à envoyer les octets du fichier à partir du décalage demandé, en sautant les octets initiaux. Notez cependant que le RFC 959 requiert seulement que reste soit une chaîne de caractères contenant des caractères dans l'intervalle imprimable du code ASCII 33 au code ASCII 126. La méthode transfercmd(), par conséquent, convertit reste en une chaîne, mais aucune vérification n'est effectuée sur le contenu de la chaîne. Si le serveur ne reconnaît pas la commande "REST", une exception error_reply sera déclenchée. Si ceci se produit, appelez simplement transfercmd() sans argument reste.

ntransfercmd(cmd[, reste])

Comme transfercmd(), mais retourne un tuple de la connexion de données et de la taille attendue des données. Si la taille attendue n'a pas pu être calculée, None sera retourné comme taille attendue. cmd et reste signifient la même chose que dans transfercmd().

nlst(argument[, ...])

Retourne une liste des fichiers tels que retournés par la commande "NLST". L'argument optionnel argument est un répertoire à lister (par défaut, le répertoire courant du serveur). Plusieurs arguments peuvent être utilisés pour passer des options non standard à la commande "NLST".

dir(argument[, ...])

Produit un listage du répertoire retourné par la commande "LIST", et l'imprime sur la sortie standard. L'argument optionnel indique un répertoire à lister (par défaut, le répertoire courant du serveur). Plusieurs arguments peuvent être utilisés pour passer des options non standard à la commande "LIST". Si le dernier argument est une fonction, elle sert de fonction rappel comme pour retrlines(); par défaut, c'est l'impression sur sys.stdout. Cette méthode retourne None.

rename(denom, versnom)

Renomme le fichier denom sur le serveur en versnom.

delete(nomfichier)

Supprime le fichier appelé nomfichier du serveur. Si cette commande réussit, retourne le texte de la réponse, sinon déclenche error_perm en cas d'erreur de permission ou error_reply pour les autres erreurs.

cwd(chemin)

Définit le répertoire courant sur le serveur.

mkd(chemin)

Crée un nouveau répertoire sur le serveur.

pwd()

Retourne le nom de chemin du répertoire courant sur le serveur.

rmd(nomrep)

Supprime le répertoire appelé nomrep sur le serveur.

size(nomfichier)

Demande la taille du fichier appelé nomfichier sur le serveur. Si la commande réussit, la taille du fichier est retournée sous la forme d'un entier, sinon c'est None qui est retourné. Notez que la commande "SIZE" n'est pas standardisée, mais qu'elle est prise en charge par de nombreuses implémentations de serveurs.

quit()

Envoie une commande "QUIT" au serveur et ferme la connexion. C'est la façon ``polie'' de fermer une connexion, mais elle peut déclencher une exception si le serveur répond par une erreur à la commande "QUIT". Elle implique un appel à la méthode close(), qui rend l'instance de la classe FTP inutilisable pour des appels ultérieurs (voir ci-dessous).

close()

Ferme la connexion unilatéralement. A ne pas appliquer à une connexion déjà fermée (par exemple après un appel réussi à la méthode quit(). Après cet appel, l'instance de FTP ne doit plus être utilisée (c'est-à-dire qu'après un appel à close() ou à quit() vous ne pouvez pas réouvrir la connexion en effectuant un nouvel appel à login()).