11.5.1 Objetos FTP

Disponen de diversos métodos, en dos sabores: uno para gestionar ficheros de texto y otros para ficheros binarios. Éstos últimos reciben su nombre a partir de la orden utilizada más "lines" para la versión de texto y más "binary" para la versión binaria.

Las instancias de FTP cuentan con los siguientes métodos:

set_debuglevel (level): Establece el nivel de depuración de la instancia. Éste controla la cantidad de información de depuración presentada. El valor predeterminado, 0, no muestra información de depuración. Un valor de 1 produce una cantidad moderada de información de depuración, del orden de una línea por petición. Un valor de 2 o superior produce la máxima cantidad de información de depuración, presentando cada línea enviada y recibida sobre la conexión de control.

connect (host[, port]): Conectarse al servidor y puerto especificados. El número de puerto predeterminado es 21, como dice la especificación del protocolo FTP. Es poco común que sea necesario especificar un número de puerto diferente. La función se ha de llamar una sola vez para cada instancia y no debería llamarse en absoluto si se especificó un servidor al crear la instancia. El resto de los métodos sólo funcionan tras realizarse la conexión.

getwelcome (): Devuelve el mensaje de bienvenida enviado por el servidor en respuesta a la conexión inicial (este mensaje contiene a veces reductores de la responsabilidad o información de ayuda que puede ser relevante para el usuario).

login ([user[, passwd[, acct]]]): Iniciar sesión como el usuario user especificado. Los parámetros passwd y acct son opcionales y toman como valor predeterminado la cadena vacía. Si user es 'anonymous', la contraseña predeterminada es "realuser@host" donde realuser es el nombre real del usuario (a partir de las variables de entorno $LOGNAME o $USER y host es el nombre del nodo devuelto por socket.gethostname(). Se ha de llamar a esta función una sola vez por instancia, tras establecer la conexión. No se ha de llamar en absoluto si se proporcionó un nombre de servidor y usuario al crear la instancia. La mayor parte de las órdenes de FTP sólo están permitidas tras iniciar sesión.

abort (): Interrumpe la transferencia en curso. No siempre funciona, pero trae cuenta intentarlo.

sendcmd (command): Envía una cadena de orden simple al servidor y devuelve la cadena de respuesta.

voidcmd (command): Envía una cadena de orden simple al servidor y gestiona la respuesta. No devuelve nada so se recibe un código de respuesta del rango 200-299. Lanza una excepción en caso contrario.

retrbinary (command, callback[, maxblocksize[, rest]]): Recupera un fichero en modo de transferencia binario. command debe ser una orden "RETR" adecuada, por ejemplo 'RETR nombrefichero'. Se llama a la función callback para cada bloque de datos recibido, con un solo argumento, el bloque de datos. El argumento opcional maxblocksize especifica el tamaño máximo del bloque que se ha de leer a bajo nivel, al nivel del socket generado para realizar la transferencia (será también el tamaño máximo de la cadena de datos que llegue a callback). El valor predeterminado es razonable. rest indica lo mismo que en el método transfercmd().

retrlines (command[, callback]): Recupera un fichero o listado de directorio en modo de transferencia ASCII. command debe ser una orden "RETR" adecuada (ver retrbinary() o una orden "LIST" (que suele ser solamente la cadena'LIST'). Se llama a la función callback para cada línea recibida, eliminando el retorno final. La función callback predeterminada presenta la salida a sys.stdout.

set_pasv (boolean): Establece el modo ``pasivo'' de transferencia si boolean es verdadero, en caso contrario, quita el modo pasivo.

storbinary (command, file, blocksize): Almacena (sube) un fichero en modo de transferencia binario. command debe ser una orden "STOR" adecuada, por ejemplo "STOR nombreFichero". file es un objeto fichero abierto, que se lee con su método read(), en bloques de tamaño blocksize para proporcionar los datos a enviar.

storlines (command, file): Almacena un fichero en modo ASCII de transferencia. command debe ser una orden "STOR" adecuada (ver storbinary()). Se leen líneas del fichero file, que debe estar abierot,hasta encontrar EOF, usando su método readline() para proporcionar los datos a enviar.

transfercmd (cmd[, rest]): Inicia una transferencia por la conexión de datos. Si la transferencia es activa, envía una orden "PORT" y la orden de transferencia especificada por cmd, y acepta la conexión. Si el servidor es pasivo, envía una orden "PASV", se conecta e inicia la orden de transferencia. En ambos casos, devuelve el socket de la conexión.
Si se proporciona el parámetro opcional rest, se envía una orden "REST" al servidor, pasando rest como argumento. rest suele ser un punto de arranque en bytes, que indica al servidor que debe enviar los datos a partir de dicho punto de arranque, saltándose lo bytes iniciales indicados. Es importante destacar que la RFC 959 sólo requiere que rest sea una cadena que contenga caracteres del rango ASCII imprimibles (entre 33 y 126). El método transfercmd(), por lo tanto, convierte rest a una cadena, pero no realiza ninguna comprobación sobre su contenido. Si el servidor no reconoce la orden "REST", se lanzará una excepción error_reply. En tal caso , se ha de llamar a transfercmd() sin argumento rest.

ntransfercmd (cmd[, rest]): Como transfercmd(), pero devuelve una tupla de la conexión de datos y el tamaño esperado de los datos. Si no puede calcularse el tamaño esperado, se devuelve None como tamaño esperado. cmd y rest significan lo mismo que en transfercmd().

nlst (argument[, ...]): Devuelve una lista de los ficheros a partir de la orden "NLST", El argumento opcional argument es el directorio a listar (por omisión el directorio actual del servidor). Se pueden pasar múltiples argumentos para pasar opciones no estándar a la orden "NLST".

dir (argument[, ...]): Produce un listado del directorio, según la orden "LIST", y la presenta en la salida estándar. El argumento opcional argument es el directorio a listar (por omisión el directorio actual del servidor). Se pueden pasar múltiples argumentos para pasar opciones no estándar a la orden "LIST". Si el último argumento es una función, se usa de llamada de respuesta como en el método retrlines(); por omisión se presenta la salida en sys.stdout. Este método devuelve None.

rename (fromname, toname): Renombra el fichero fromname del servidor a toname.

delete (filename): Elimina el fichero denominado filename del servidor, SI tiene éxito, devuelve el texto de respuesta. En caso contrario lanza error_perm para errores de permisos o error_reply para otros errores.

cwd (pathname): Establece el directorio actual en el lado del servidor.

mkd (pathname): Crea un nuevo directorio en el servidor.

pwd (): Devuelve el camino completo del directorio actual del servidor.

rmd (dirname): Elimina el directorio dirname del servidor.

size (filename): Solicita el tamaño del fichero filename del servidor. Si tiene éxito, se devuelve el tamaño del fichero como entero. En caso contrario, se devuelve None. La orden "SIZE" no es estándar, pero está soportada en la mayoría de las implementaciones de servidor comunes.

quit (): Envía una orden "QUIT" al servidor y cierra la conexión. Es el modo ``educado'' de cerrar la conexión, pero puede lanzar una excepción si el servidor responde con un error a la orden "QUIT". Implica una llamada al método close(), que torna la instancia de FTP inútil para las siguientes llamadas (ver lo siguiente).

close (): Cierra la conexión unilateralmente. No se debería aplicar a una conexión ya cerrada (es decir, tras llamar a quit()). Tras esta llamada, la instancia de FTP no se debería usar. No se puede reabrir la conexión mediante una llamada al método login().

Ver Sobre este documento... para obtener información sobre sugerencias.