# `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.

Availability: not Emscripten, not WASI.

Este modulo no funciona o no está disponible para plataformas WebAssembly `wasm32-emscripten` y `wasm32-wasi`. Consulte Plataformas WebAssembly para más información.

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

## Reference

### FTP objects

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

  Return a new instance of the `FTP` class.

  Parámetros:

    - host (str) – The hostname to connect to. If given, `connect(host)` is implicitly called by the constructor.

    - user (str) – The username to log in with (default: `'anonymous'`). If given, `login(host, passwd, acct)` is implicitly called by the constructor.

    - passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or `"-"`, a password will be automatically generated.

    - acct (str) – Account information to be used for the `ACCT` FTP command. Few systems implement this. See RFC-959 for more details.

    - timeout (float | None) – A timeout in seconds for blocking operations like `connect()` (default: the global default timeout setting).

    - source_address (tuple | None) – A 2-tuple `(host, port)` for the socket to bind to as its source address before connecting.

    - encoding (str) – The encoding for directories and filenames (default: `'utf-8'`).

  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.

  Several `FTP` methods are available in two flavors: one for handling text files and another for binary files. The methods 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:

  set_debuglevel(level)

    Set the instance’s debugging level as an `int`. This controls the amount of debugging output printed. The debug levels are:

    - `0` (default): No debug output.

    - `1`: Produce a moderate amount of debug output, generally a single line per request.

    - `2` or higher: Produce the maximum amount of debugging output, logging each line sent and received on the control connection.

  connect(host='', port=0, timeout=None, source_address=None)

    Connect to the given host and port. This function should be called only once for each instance; it should not be called if a host argument was given when the `FTP` instance was created. All other `FTP` methods can only be called after a connection has successfully been made.

    Parámetros:

      - host (str) – The host to connect to.

      - port (int) – The TCP port to connect to (default: `21`, as specified by the FTP protocol specification). It is rarely needed to specify a different port number.

      - timeout (float | None) – A timeout in seconds for the connection attempt (default: the global default timeout setting).

      - source_address (tuple | None) – A 2-tuple `(host, port)` for the socket to bind to as its source address before connecting.

    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.

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

  login(user='anonymous', passwd='', acct='')

    Log on to the connected FTP server. This function should be called only once for each instance, after a connection has been established; it should not be called if the host and user arguments were given when the `FTP` instance was created. Most FTP commands are only allowed after the client has logged in.

    Parámetros:

      - user (str) – The username to log in with (default: `'anonymous'`).

      - passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or `"-"`, a password will be automatically generated.

      - acct (str) – Account information to be used for the `ACCT` FTP command. Few systems implement this. See RFC-959 for more details.

  abort()

    Anula una transferencia de archivo que está en progreso. Usarlo no siempre funciona, pero vale la pena intentarlo.

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

  voidcmd(cmd)

    Send a simple command string to the server and handle the response. Return the response string if the response code corresponds to success (codes in the range 200–299). Raise `error_reply` otherwise.

    Genera un evento auditor `ftplib.sendcmd` con los argumentos `self`, `cmd`.

  retrbinary(cmd, callback, blocksize=8192, rest=None)

    Retrieve a file in binary transfer mode.

    Parámetros:

      - cmd (str) – An appropriate `STOR` command: `"STOR filename"`.

      - callback (callable) – A single parameter callable that is called for each block of data received, with its single argument being the data as `bytes`.

      - blocksize (int) – The maximum chunk size to read on the low-level `socket` object created to do the actual transfer. This also corresponds to the largest size of data that will be passed to callback. Defaults to `8192`.

      - rest (int) – A `REST` command to be sent to the server. See the documentation for the rest parameter of the `transfercmd()` method.

  retrlines(cmd, callback=None)

    Retrieve a file or directory listing in the encoding specified by the encoding parameter at initialization. cmd should be an appropriate `RETR` command (see `retrbinary()`) or a command such as `LIST` or `NLST` (usually just the string `'LIST'`). `LIST` retrieves a list of files and information about those files. `NLST` retrieves a list of file names. The callback function is called for each line with a string argument containing the line with the trailing CRLF stripped. The default callback prints the line to `sys.stdout`.

  set_pasv(val)

    Habilita el modo pasivo si val es verdadero, de lo contrario lo inhabilita. El modo pasivo es el valor predeterminado.

  storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

    Store a file in binary transfer mode.

    Parámetros:

      - cmd (str) – An appropriate `STOR` command: `"STOR filename"`.

      - fp (file object) – A file object (opened in binary mode) which is read until EOF, using its `read()` method in blocks of size blocksize to provide the data to be stored.

      - blocksize (int) – The read block size. Defaults to `8192`.

      - callback (callable) – A single parameter callable that is called for each block of data sent, with its single argument being the data as `bytes`.

      - rest (int) – A `REST` command to be sent to the server. See the documentation for the rest parameter of the `transfercmd()` method.

    Distinto en la versión 3.2: The rest parameter was added.

  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.

  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.

  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()`.

  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.

  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.

  dir(argument[, ...])

    Produce a directory listing as returned by the `LIST` command, printing it to standard output. 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 the `LIST` command. If the last argument is a function, it is used as a callback function as for `retrlines()`; the default prints to `sys.stdout`. This method returns `None`.

    Nota

    Si tu servidor admite el comando, `mlsd()` ofrece una API mejor.

  rename(fromname, toname)

    Asigna un nombre nuevo al archivo en el servidor desde fromname a toname.

  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.

  cwd(pathname)

    Configura el directorio actual en el servidor.

  mkd(pathname)

    Crea un nuevo directorio en el servidor.

  pwd()

    Retorna el nombre de ruta del directorio actual en el servidor.

  rmd(dirname)

    Elimina el directorio en el servidor llamado dirname.

  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.

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

  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()`.

### FTP_TLS objects

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

  An `FTP` subclass which adds TLS support to FTP as described in RFC 4217. Connect to port 21 implicitly securing the FTP control connection before authenticating.

  Nota

  The user must explicitly secure the data connection by calling the `prot_p()` method.

  Parámetros:

    - host (str) – The hostname to connect to. If given, `connect(host)` is implicitly called by the constructor.

    - user (str) – The username to log in with (default: `'anonymous'`). If given, `login(host, passwd, acct)` is implicitly called by the constructor.

    - passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or `"-"`, a password will be automatically generated.

    - acct (str) – Account information to be used for the `ACCT` FTP command. Few systems implement this. See RFC-959 for more details.

    - context (`ssl.SSLContext`) – An SSL context object which allows bundling SSL configuration options, certificates and private keys into a single, potentially long-lived, structure. Please read Consideraciones de seguridad for best practices.

    - timeout (float | None) – A timeout in seconds for blocking operations like `connect()` (default: the global default timeout setting).

    - source_address (tuple | None) – A 2-tuple `(host, port)` for the socket to bind to as its source address before connecting.

    - encoding (str) – The encoding for directories and filenames (default: `'utf-8'`).

  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: Added the source_address parameter.

  Distinto en la versión 3.4: The class now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `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']

  `FTP_TLS` class inherits from `FTP`, defining these additional methods and attributes:

  ssl_version

    The SSL version to use (defaults to `ssl.PROTOCOL_SSLv23`).

  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: The method now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `ssl.HAS_SNI`).

  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.

  prot_p()

    Configura conexión de datos segura.

  prot_c()

    Configura la conexión de datos de tipo texto común.

### Module variables

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.