"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. Puede usar
esto para escribir programas de Python que realicen una variedad de
trabajos FTP automatizados, como duplicar otros servidores FTP.
También es utilizado por el módulo "urllib.request" para manejar URL
que usan FTP. Para más información sobre FTP (File Transfer Protocol),
ver internet :rfc:'959'.

La codificación predeterminada es UTF-8, siguiendo **RFC 2640**.

Aquí hay una sesión de ejemplo usando el módulo "ftplib":

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

El módulo define los siguientes elementos:

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

   Retorna una nueva instancia de la clase "FTP". Cuando se da *host*,
   se realiza la llamada al método "connect(host)". Cuando se da
   *user*, además se realiza la llamada al método "login(user, passwd,
   acct)" (donde *passwd* y *acct* predeterminan la cadena de
   caracteres vacía cuando no se dan). El parámetro opcional *timeout*
   especifica un tiempo de espera en segundos para bloquear
   operaciones como el intento de conexión (si no se especifica, se
   utilizará la configuración de tiempo de espera global
   predeterminada). *source_address* es una tupla de dos elementos
   "(host, port)" para que el socket se vincule como su dirección de
   origen antes de conectarse. El parámetro *encoding* especifica la
   codificación de directorios y nombres de archivo.

   La clase "FTP" admite la instrucción "with", 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*.

   Distinto en la versión 3.9: Si el parámetro *timeout* se establece
   en cero, lanzará un "ValueError" para evitar la creación de un
   socket sin bloqueo. Se agregó el parámetro *encoding*, y el valor
   predeterminado se cambió de Latin-1 a UTF-8 para seguir **RFC
   2640**.

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

   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étodo "prot_p()". *context*
   es un objeto "ssl.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
   Consideraciones de seguridad 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éase "ssl.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 que
   "ssl.create_default_context()" seleccione los certificados CA
   confiables para ti.

   Distinto en la versión 3.9: Si el parámetro *timeout* se establece
   en cero, lanzará un "ValueError" para evitar la creación de un
   socket sin bloqueo. Se agregó el parámetro *encoding*, y el valor
   predeterminado se cambió de Latin-1 a UTF-8 para seguir **RFC
   2640**.

   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én "OSError" y "EOFError".

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

Hay varios métodos disponibles en dos versiones: uno para manejar
archivos de texto y otro para archivos binarios. Estos reciben el
nombre del comando que se utiliza seguido de "lines" para la versión
de texto o "binary" para la versión binaria.

Las instancias de "FTP" tienen los siguientes métodos:

FTP.set_debuglevel(level)

   Establece el nivel de depuración de la instancia. Esto controla la
   cantidad de salida de depuración impresa. El valor predeterminado,
   "0", no produce una salida de depuración. Un valor de "1" produce
   una cantidad moderada de salida de depuración, generalmente una
   sola línea por solicitud. Un valor de "2" 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 argumentos "self",
   "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 argumentos
   "self", "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 argumentos
   "self", "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étodo "transfercmd()".

FTP.retrlines(cmd, callback=None)

   Recupera una lista de archivos o directorios en la codificación
   especificada por el parámetro *encoding* en la inicialización.
   *cmd* debe ser un comando "RETR" apropiado (ver "retrbinary()") o
   un comando como "LIST" o "NLST" (generalmente solo la cadena de
   caracteres "'LIST'"). "LIST" recupera una lista de archivos e
   información sobre esos archivos. "NLST" recupera una lista de
   nombres de archivos. La función *callback* se llama para 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 a "sys.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étodo "read()" 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étodo "transfercmd()".

   Distinto en la versión 3.2: Se agregó el parámetro *rest*.

FTP.storlines(cmd, fp, callback=None)

   Almacena un archivo en modo de línea. *cmd* debe ser un comando
   "STOR" apropiado (ver "storbinary()"). Las líneas se leen hasta EOF
   del *file object* *fp* (abierto en modo binario) usando su método
   "readline()" para proporcionar los datos que se almacenarán.
   *callback* es un parámetro único opcional que se puede llamar en
   cada línea después de su envío.

FTP.transfercmd(cmd, rest=None)

   Inicia una transferencia sobre la conexión de datos.  Si la
   transferencia es activa, envía un comando "EPRT" o  "PORT" y el
   comando de transferencia especificado por *cmd*, y acepta la
   conexión. Si el servidor es pasivo, envía un comando "EPSV" o
   "PASV", lo conecta, e inicia el comando de transferencia. De
   cualquier manera, retorna el socket para la conexión.

   Si se proporciona *rest* opcional, se envía un comando "REST" al
   servidor, pasando *rest* como argumento. *rest* suele ser un
   desplazamiento de bytes en el archivo solicitado, que le indica al
   servidor que reinicie el envío de los bytes del archivo en el
   desplazamiento solicitado, omitiendo los bytes iniciales. Sin
   embargo, tenga en cuenta que el método "transfercmd()" convierte
   *rest* en una cadena de caracteres con el parámetro *encoding*
   especificado en la inicialización, pero no se realiza ninguna
   comprobación del contenido de la cadena de caracteres. Si el
   servidor no reconoce el comando "REST", se lanzará una excepción
   "error_reply". Si esto sucede, simplemente llame a "transfercmd()"
   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 en "transfercmd()".

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

   Enumera un directorio en un formato estandarizado usando el comando
   "MLSD" (**RFC 3659**). Si se omite *path*, se asume el directorio
   actual. *facts* es una lista de cadenas de caracteres que
   representan el tipo de información deseada (por ejemplo, "["type",
   "size", "perm"]"). Retorna un objeto generador que produce una
   tupla de dos elementos por cada archivo encontrado en la ruta. El
   primer elemento es el nombre del archivo, el segundo es un
   diccionario que contiene datos sobre el nombre del archivo. El
   contenido de este diccionario puede estar limitado por el argumento
   *facts*, pero no se garantiza que el servidor retorne todos los
   datos solicitados.

   Nuevo en la versión 3.3.

FTP.nlst(argument[, ...])

   Retorna una lista de nombres de archivos tal como los retorna el
   comando "NLST". El *argument* opcional es un directorio para listar
   (el predeterminado es el directorio del servidor actual). Se pueden
   usar varios argumentos para pasar opciones no estándar al comando
   "NLST".

   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 comando
   "LIST". Si el último argumento es una función, se usa como función
   *callback* como en "retrlines()"; el valor predeterminado imprime a
   "sys.stdout".  Este método retorna "None".

   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 o "error_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 comando "SIZE" 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
   comando "QUIT". Esto implica una llamada al método "close()" que
   hace inútil la instancia de "FTP" 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 instancia "FTP" ya no debería
   utilizarse (luego de una llamada a "close()" o "quit()" no puedes
   abrir nuevamente la conexión emitiendo otro método "login()".


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éase "ssl.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.
