ftplib
— cliente de protocolo FTP¶
Código fuente Lib/ftplib.py
Este módulo define la clase FTP
y algunos elementos relacionados. La clase FTP
implementa el lado cliente del protocolo FTP. Puedes usarlo para escribir programas en Python que realizan una variedad de trabajos FTP automatizados, como reflejar otros servidores FTP. También es utilizado por el módulo urllib.request
para manejar URLs que usan FTP. Para más información sobre FTP (Protocolo de transferencia de archivos), véase Internet RFC 959.
Aquí hay una sesión de ejemplo usando el módulo ftplib
:
>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org') # connect to host, default port
>>> ftp.login() # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian') # change into "debian" directory
>>> 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()
El módulo define los siguientes elementos:
-
class
ftplib.
FTP
(host='', user='', passwd='', acct='', timeout=None, source_address=None)¶ Retorna una instancia nueva de la clase
FTP
. Cuando se proporciona host, se llama al métodoconnect(host)
. Cuando se proporciona user, se llama adicionalmente al métodologin(user, passwd, acct)
(donde passwd y acct tienen como valor predeterminado la cadena vacía cuando no se indica). El parámetro opcional timeout especifica un tiempo de espera en segundo para bloquear operaciones como el intento de conexión (si no está especificado, se usa el tiempo de espera global por defecto). source_address es una tupla de 2(host, port)
para que el socket se enlace como su dirección de origen antes de conectarse.La clase
FTP
admite la instrucciónwith
, por ejemplo:>>> 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 >>>
Distinto en la versión 3.2: Se agregó compatibilidad con la instrucción
with
.Distinto en la versión 3.3: Se agregó el parámetro source_address.
-
class
ftplib.
FTP_TLS
(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)¶ Una subclase
FTP
que agrega compatibilidad con TLS a FTP como se describe en RFC 4217. Conéctate como de costumbre al puerto 21 asegurando implícitamente la conexión de control antes de autenticar. Proteger la conexión de datos requiere que el usuario la solicite explícitamente llamando al métodoprot_p()
. context es un objetossl.SSLContext
que permite agrupar opciones de configuración SSL, certificados y claves privadas en una sola estructura (potencialmente de larga duración). Por favor, lee Security considerations para conocer las mejores prácticas.keyfile y certfile son una alternativa de legado a context – pueden apuntar a una clave privada en formato PEM y certificar archivos de cadena (respectivamente) para la conexión SSL.
Nuevo en la versión 3.2.
Distinto en la versión 3.3: Se agregó el parámetro source_address.
Distinto en la versión 3.4: La clase ahora admite el chequeo del nombre de host con
ssl.SSLContext.check_hostname
y Server Name Indication (véasessl.HAS_SNI
).Obsoleto desde la versión 3.6: keyfile y certfile son rechazados a favor de context. Por favor, usa
ssl.SSLContext.load_cert_chain()
en su lugar, o deja quessl.create_default_context()
seleccione los certificados CA confiables para ti.Aquí hay una sesión de ejemplo que usa la clase
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']
-
exception
ftplib.
error_reply
¶ Se lanza una excepción cuando una respuesta inesperada se recibe del servidor.
-
exception
ftplib.
error_temp
¶ Se genera una excepción cuando se recibe un código de error que refiere a un error temporal (códigos de respuesta en el rango 400-499).
-
exception
ftplib.
error_perm
¶ Se lanza una excepción cuando se recibe un código de error que refiere a un error permanente (códigos de respuesta en el rango 500–599).
-
exception
ftplib.
error_proto
¶ Se lanza una excepción cuando se recibe una respuesta del servidor que no coincide con las especificaciones de respuesta del protocolo de transferencia de archivos (FTP), es decir, que comienza con un dígito en el rango 1–5.
-
ftplib.
all_errors
¶ El conjunto de todas las excepciones (como una tupla) que los métodos de instancias
FTP
pueden lanzar como resultado de problemas con la conexión FTP (a diferencia de los errores de programación hechos por el autor de la llamada). Este conjunto incluye las cuatro excepciones enumeradas anteriormente, como tambiénOSError
yEOFError
.
Ver también
- Módulo
netrc
Analizador para el formato de archivo
.netrc
. El archivo.netrc
suele ser utilizado por clientes FTP para cargar la información de autenticación de usuario antes de solicitarlo al usuario.
Objetos FTP¶
Several methods are available in two flavors: one for handling text files and
another for binary files. These are named for the command which is used
followed by lines
for the text version or binary
for the binary version.
Las instancias de FTP
tienen los siguientes métodos:
-
FTP.
set_debuglevel
(level)¶ Establece el nivel de depuración de la isntancia. Esto controla la cantidad de salida de depuración impresa. El valor predeterminado,
0
, no produce una salida de depuración. Un valor de1
produce una cantidad moderada de salida de depuración, generalmente una sola línea por solicitud. Un valor de2
produce la cantidad máxima de salida de depuración, registrando cada línea enviada y recibida en la conexión de control.
-
FTP.
connect
(host='', port=0, timeout=None, source_address=None)¶ Conéctate al puerto y al host dados. El número de puerto por defecto es
21
, como se establece en la especificación de protocolo FTP. Raramente se necesita un número de puerto diferente. Esta función debería llamarse una vez por cada instancia; no debería llamarse si el host fue dado cuando se creó la instancia. Todos los otros métodos se pueden usar solo después de que se hizo una conexión. Si no se pasa ningún parámetro opcional timeout en segundos para el intento de conexión. Si no se pasa ningún timeout, se usará la configuración de tiempo de espera global. source_address is una tupla de 2(host, port)
para que el socket se enlace como su dirección de origen antes de conectarse.Lanza un evento auditor
ftplib.connect
con los argumentosself
,host
,port
.Distinto en la versión 3.3: Se agregó el parámetro source_address.
-
FTP.
getwelcome
()¶ Retornar el mensaje de bienvenida enviado por el servidor como respuesta a la conexión inicial. (Este mensaje a veces contiene renuncias de responsabilidad o información de ayuda que puede ser relevante para el usuario.)
-
FTP.
login
(user='anonymous', passwd='', acct='')¶ Inicia sesión como el usuario dado. Los parámetros passwd y acct son opcionales y tienen como valor predeterminado la cadena vacía. Si no se especifica ningún usuario, toma como valor predeterminado
'anónimo'
, el valor predeterminado de passwd es'anonymous@'
. Esta función debería ser invocada solo una vez por cada instancia, luego de que se haya establecido una conexión; no debería invocarse en lo absoluto si se dio un anfitrión y un usuario cuando se creó la instancia. La mayoría de los comandos FTP solo están permitidos luego de que el cliente ha iniciado sesión. El parámetro acct proporciona «información contable»; pocos sistemas implementan esto.
-
FTP.
abort
()¶ Anula una transferencia de archivo que está en progreso. Usarlo no siempre funciona, pero vale la pena intentarlo.
-
FTP.
sendcmd
(cmd)¶ Envía una cadena de comando simple al servidor y retorna la cadena de caracteres de respuesta.
Genera un evento auditor
ftplib.sendcmd
con los argumentosself
,cmd
.
-
FTP.
voidcmd
(cmd)¶ Envía una cadena de caracteres como comando simple al servidor y maneja la respuesta. No retorna nada si recibe el código de respuesta que corresponde a una transferencia exitosa (códigos en el rango 200–299).Lanza
error_reply
de lo contrario.Genera un evento auditor
ftplib.sendcmd
con los argumentosself
,cmd
.
-
FTP.
retrbinary
(cmd, callback, blocksize=8192, rest=None)¶ Recupera un archivo en el modo de transferencia binaria. cmd debería ser un comando
RETR``apropiado: ``'RETR filename'
. La función callback es invocada por cada bloque de datos recibido, con un único argumento bytes que proporciona el bloque de datos. El argumento opcional blocksize especifica el tamaño máximo de fragmento que se leerá en el socket de bajo nivel creado para hacer la transferencia real (que también será el tamaño máximo de fragmento que se pasará a callback). Se elige un valor predeterminado razonable. rest significa lo mismo que en el métodotransfercmd()
.
-
FTP.
retrlines
(cmd, callback=None)¶ Recupera una lista de archivos o directorios en modo de transferencia ASCII. cmd debería ser un comando
RETR
apropiado (véaseretrbinary()
) o un comando comoLIST
oNLST
(usualmente solo la cadena de caracteres'LIST'
).LIST
recupera una lista de archivos y la información sobre esos archivos.NLST
recupera una lista de nombres de archivos. La función callback se invoca por cada línea con un argumento de cadena de caracteres que contiene la línea con el CRLF final eliminado. El callback predeterminado imprime la línea asys.stdout
.
-
FTP.
set_pasv
(val)¶ Habilita el modo pasivo si val es verdadero, de lo contrario lo inhabilita. El modo pasivo es el valor predeterminado.
-
FTP.
storbinary
(cmd, fp, blocksize=8192, callback=None, rest=None)¶ Almacena un archivo en el modo de transferencia binaria. cmd debería ser un comando
STOR``apropiado: ``"STOR filename"
. fp es un file object (abierto en modo binario) que es leído hasta EOF (final del archivo) usando el métodoread()
en bloques de tamaño blocksize para proporcionar los datos que serán almacenados. El argumento blocksize toma 8192 como valor predeterminado. callback es un único parámetro invocable que se llama en cada bloque de datos luego de que fue enviado. rest significa lo mismo que en el métodotransfercmd()
.Distinto en la versión 3.2: Se agregó el parámetro rest.
-
FTP.
storlines
(cmd, fp, callback=None)¶ Almacena un archivo en el modo de transferencia ASCII. cmd debería ser un comando
STOR
apropiado (véasestorbinary()
). Las líneas son leídas hasta EOF (final del archivo) desde el file object fp (abierto en modo binario) usando su métodoreadline()
para proporcionar los datos que serán almacenados. callback es un único parámetro opcional invocable que se llama en cada línea luego de que es enviada.
-
FTP.
transfercmd
(cmd, rest=None)¶ Inicia una transferencia sobre la conexión de datos. Si la transferencia es activa, envía un comando
EPRT
oPORT
y el comando de transferencia especificado por cmd, y acepta la conexión. Si el servidor es pasivo, envía un comandoEPSV
oPASV
, lo conecta, e inicia el comando de transferencia. De cualquier manera, retorna el socket para la conexión.Si el opcional rest está dado, un comando
REST
se envía al servidor, pasando rest como argumento. rest es usualmente un offset de byte en el archivo solicitado y le pide al servidor que reinicie enviando los bytes del archivo al offset solicitado, saltándose los bytes iniciales. Nota, sin embargo, que rfc:`959 requieres no solo que rest sea una cadena de caracteres que contiene caracteres en el rango imprimible del código ASCII 33 al 126. El métodotransfercmd()
, entonces, convierte rest a una cadena de caracteres, pero no se ejecuta ningún chequeo en los contenidos de la cadena de caracteres. Si el servidor no reconoce el comandoREST
, se lanza una excepciónerror_reply
. Si esto ocurre, simplemente invocatransfercmd()
sin un argumento rest.
-
FTP.
ntransfercmd
(cmd, rest=None)¶ Como
transfercmd()
, pero retorna una tupla de conexión de datos y el tamaño esperado de los datos. Si el tamaño esperado no se pudo computar, retornaráNone
como tal. cmd y rest significan lo mismo que entransfercmd()
.
-
FTP.
mlsd
(path="", facts=[])¶ List a directory in a standardized format by using
MLSD
command (RFC 3659). If path is omitted the current directory is assumed. facts is a list of strings representing the type of information desired (e.g.["type", "size", "perm"]
). Return a generator object yielding a tuple of two elements for every file found in path. First element is the file name, the second one is a dictionary containing facts about the file name. Content of this dictionary might be limited by the facts argument but server is not guaranteed to return all requested facts.Nuevo en la versión 3.3.
-
FTP.
nlst
(argument[, ...])¶ Return a list of file names as returned by the
NLST
command. The optional argument is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to theNLST
command.Nota
Si tu servidor admite el comando,
mlsd()
ofrece una API mejor.
-
FTP.
dir
(argument[, ...])¶ Produce una lista de directorios como se retorna por el comando
LIST
, imprimiéndola en una salida estándar. El argument opcional es un directorio a ser listado (el valor predeterminado es el directorio del servidor actual). Se pueden utilizar argumentos múltiples para pasar las opciones que no son estándar al comandoLIST
. Si el último argumento es una función, se usa como función callback como enretrlines()
; el valor predeterminado imprime asys.stdout
. Este método retornaNone
.Nota
Si tu servidor admite el comando,
mlsd()
ofrece una API mejor.
-
FTP.
rename
(fromname, toname)¶ Asigna un nombre nuevo al archivo en el servidor desde fromname a toname.
-
FTP.
delete
(filename)¶ Remueve el archivo nombrado filename del servidor. De ser exitoso, retorna el texto de la respuesta, de lo contrario, lanza
error_perm
sobre errores de permiso oerror_reply
sobre otros errores.
-
FTP.
cwd
(pathname)¶ Configura el directorio actual en el servidor.
-
FTP.
mkd
(pathname)¶ Crea un nuevo directorio en el servidor.
-
FTP.
pwd
()¶ Retorna el nombre de ruta del directorio actual en el servidor.
-
FTP.
rmd
(dirname)¶ Elimina el directorio en el servidor llamado dirname.
-
FTP.
size
(filename)¶ Solicita el tamaño del archivo llamado filename en el servidor. De ser exitoso, se retorna el tamaño del archivo como un entero, de lo contrario retorna
None
. Nótese que el comandoSIZE
no está estandarizado, pero es admitido por muchas implementaciones comunes de servidor.
-
FTP.
quit
()¶ Envía un comando
QUIT
al servidor y cierra la conexión. Esta es la forma «políticamente correcta» de cerrar una conexión, pero puede lanzar una excepción si el servidor responde con un error al comandoQUIT
. Esto implica una llamada al métodoclose()
que hace inútil la instancia deFTP
para llamadas posteriores (véase más adelante).
-
FTP.
close
()¶ Cierra la conexión de forma unilateral. Esto no debería aplicarse a una conexión ya cerrada, como luego de una llamada exitosa a
quit()
. Después de esta llamada, la instanciaFTP
ya no debería utilizarse (luego de una llamada aclose()
oquit()
no puedes abrir nuevamente la conexión emitiendo otro métodologin()
.
Objetos FTP_TLS¶
La clase FTP_TLS
hereda de FTP
, definiendo los siguientes objetos adicionales:
-
FTP_TLS.
ssl_version
¶ La versión SSL para usar (toma como predeterminado
ssl.PROTOCOL_SSLv23
).
-
FTP_TLS.
auth
()¶ Establece una conexión de control segura usando TLS o SSL, dependiendo de qué esté especificado en el atributo
ssl_version
.Distinto en la versión 3.4: El método ahora admite el chequeo del nombre de host con
ssl.SSLContext.check_hostname
y Server Name Indication (véasessl.HAS_SNI
).
-
FTP_TLS.
ccc
()¶ Revierte el canal de control a texto plano. Esto puede ser útil para aprovechar cortafuegos que saben manejar NAT con FTP no-seguro sin abrir puertos fijos.
Nuevo en la versión 3.3.
-
FTP_TLS.
prot_p
()¶ Configura conexión de datos segura.
-
FTP_TLS.
prot_c
()¶ Configura la conexión de datos de tipo texto común.