"telnetlib" --- cliente Telnet
******************************

**Código fuente:** Lib/telnetlib.py

======================================================================

El módulo "telnetlib" proporciona una clase "Telnet" que implementa el
protocolo Telnet.  Consulte **RFC 854** para obtener más información
sobre el protocolo. Además, proporciona constantes simbólicas para los
caracteres de protocolo (ver más abajo) y para las opciones telnet.
Los nombres simbólicos de las opciones de telnet siguen las
definiciones de "arpa/telnet.h", con el "TELOPT_" principal eliminado.
Para conocer los nombres simbólicos de las opciones que
tradicionalmente no se incluyen en "arpa/telnet.h", consulte la propia
fuente del módulo.

Las constantes simbólicas para los comandos telnet son: IAC, DONT, DO,
WONT, WILL, SE (Subnegotiation End), NOP (No Operation), DM (Data
Mark), BRK (Break), IP (Interrupt process), AO (Abort output), AYT
(Are You There), EC (Eliminar Character), EL (Erase Line), GA (Go
Ahead), SB (Subnegotiation Begin).

class telnetlib.Telnet(host=None, port=0[, timeout])

   "Telnet" representa una conexión a un servidor Telnet. La instancia
   inicialmente no está conectada de forma predeterminada; el método
   "open()" debe utilizarse para establecer una conexión.  Como
   alternativa, el nombre de host y el número de puerto opcional
   también se pueden pasar al constructor, en cuyo caso se establecerá
   la conexión con el servidor antes de que se retorne el constructor.
   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 usará la configuración de tiempo de espera
   predeterminada global).

   No vuelve a abrir una instancia ya conectada.

   Esta clase tiene muchos métodos "read_*()".  Tenga en cuenta que
   algunos de ellos generan "EOFError" cuando se lee el final de la
   conexión, porque pueden retornar una cadena vacía por otros
   motivos.  Vea las descripciones individuales a continuación.

   Un objeto "Telnet" es un gestor de contexto y se puede utilizar en
   una instrucción "with".  Cuando finaliza el bloque "with", se llama
   al método "close()":

      >>> from telnetlib import Telnet
      >>> with Telnet('localhost', 23) as tn:
      ...     tn.interact()
      ...

   Distinto en la versión 3.6: Soporte de gestor de contexto añadido

Ver también:

  **RFC 854** - Especificación del protocolo Telnet
     Definición del protocolo Telnet.


Objetos Telnet
==============

Las instancias "Telnet" contienen los siguientes métodos:

Telnet.read_until(expected, timeout=None)

   Lee hasta que se encuentre una cadena de bytes determinada,
   *expected*, o hasta que hayan pasado los segundos *timeout*.

   Cuando no se encuentra ninguna coincidencia, retorna lo que esté
   disponible en su lugar, posiblemente bytes vacíos.  Lanza
   "EOFError" si la conexión está cerrada y no hay datos cocinados
   disponibles.

Telnet.read_all()

   Lee todos los datos hasta EOF como bytes; bloquea hasta que se
   cierre la conexión.

Telnet.read_some()

   Lee al menos un byte de datos cocinados a menos que se golpee EOF.
   Retorna "b''" si se llega a EOF.  Bloquea si no hay datos
   disponibles inmediatamente.

Telnet.read_very_eager()

   Lee todo lo que puede ser sin bloquear en E/S (ansioso).

   Lanza "EOFError" si la conexión está cerrada y no hay datos cocidos
   disponibles. Retorna "b''" si no hay datos cocinados disponibles de
   otra manera. No bloquea a menos que esté en medio de una secuencia
   IAC.

Telnet.read_eager()

   Lee los datos disponibles.

   Lanza "EOFError" si la conexión está cerrada y no hay datos cocidos
   disponibles. Retorna "b''" si no hay datos cocinados disponibles de
   otra manera. No bloquea a menos que esté en medio de una secuencia
   IAC.

Telnet.read_lazy()

   Procesa y retorna datos ya en las colas (perezoso).

   Lanza "EOFError" si la conexión está cerrada y no hay datos
   disponibles. Retorna "b''" si no hay datos cocinados disponibles de
   otra manera.  No bloquea a menos que esté en medio de una secuencia
   IAC.

Telnet.read_very_lazy()

   Retorna los datos disponibles en la cola cocida (muy perezoso).

   Lanza "EOFError" si la conexión está cerrada y no hay datos
   disponibles. Retorna "b''" si no hay datos cocinados disponibles de
   otra manera.  Este método nunca se bloquea.

Telnet.read_sb_data()

   Retorna los datos recopilados entre un par SB/SE
   (suboptionbegin/end). La retrollamada debe tener acceso a estos
   datos cuando se invocó con un comando "SE". Este método nunca se
   bloquea.

Telnet.open(host, port=0[, timeout])

   Conecta a un host. El segundo argumento opcional es el número de
   puerto, que tiene como valor predeterminado el puerto Telnet
   estándar (23). 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 usará la configuración de tiempo
   de espera predeterminada global).

   Do not try to reopen an already connected instance.

   Genera un  evento de auditoría "telnetlib. Telnet.open" con
   argumentos "self", "host", "port".

Telnet.msg(msg, *args)

   Imprime un mensaje de depuración cuando el nivel de depuración sea
   ">" 0. Si hay argumentos adicionales, se sustituyen en el mensaje
   mediante el operador de formato de cadena de caracteres estándar.

Telnet.set_debuglevel(debuglevel)

   Establece el nivel de depuración.  Cuanto mayor sea el valor de
   *debuglevel*, más salida de depuración obtendrá (en "sys.stdout").

Telnet.close()

   Cierra la conexión.

Telnet.get_socket()

   Retorna el objeto de socket utilizado internamente.

Telnet.fileno()

   Retorna el descriptor de archivo del objeto de socket utilizado
   internamente.

Telnet.write(buffer)

   Escribe una cadena de bytes en el socket, duplicando los caracteres
   IAC. Esto puede bloquearse si la conexión está bloqueada.  Puede
   generar "OSError" si la conexión está cerrada.

   Lanza un evento de auditoría "telnetlib.Telnet.write" con
   argumentos "self", "buffer".

   Distinto en la versión 3.3: Este método se utiliza para lanzar
   "socket.error", que ahora es un alias de "OSError".

Telnet.interact()

   Función de interacción, emula a un cliente Telnet muy tonto.

Telnet.mt_interact()

   Versión multiproceso de "interact()".

Telnet.expect(list, timeout=None)

   Lee hasta que uno de una lista de expresiones regulares coincida.

   El primer argumento es una lista de expresiones regulares,
   compiladas (objetos regex) o no compiladas (cadenas de bytes). El
   segundo argumento opcional es un tiempo de espera, en segundos; el
   valor predeterminado es bloquear indefinidamente.

   Retorna una tupla de tres elementos: el índice de la lista de la
   primera expresión regular que coincide; el objeto de coincidencia
   retornado; y los bytes leen hasta e incluyendo la coincidencia.

   Si se encuentra el final del archivo y no se leyó ningún bytes,
   lanza "EOFError". De lo contrario, cuando nada coincide, retorna
   "(-1, None, data)" donde *data* es los bytes recibidos hasta ahora
   (pueden ser bytes vacíos si se ha producido un tiempo de espera).

   Si una expresión regular termina con una coincidencia expansiva
   (como ".*") o si más de una expresión puede coincidir con la misma
   entrada, los resultados no son deterministas y pueden depender de
   la sincronización de E/S.

Telnet.set_option_negotiation_callback(callback)

   Cada vez que se lee una opción telnet en el flujo de entrada, se
   llama a esta *callback* (si se establece) con los siguientes
   parámetros: callback(telnet socket, command (DO/DONT/WILL/WONT),
   opción).  No hay ninguna otra acción se realiza después por
   telnetlib.


Ejemplo de Telnet
=================

Un ejemplo sencillo que ilustra el uso típico:

   import getpass
   import telnetlib

   HOST = "localhost"
   user = input("Enter your remote account: ")
   password = getpass.getpass()

   tn = telnetlib.Telnet(HOST)

   tn.read_until(b"login: ")
   tn.write(user.encode('ascii') + b"\n")
   if password:
       tn.read_until(b"Password: ")
       tn.write(password.encode('ascii') + b"\n")

   tn.write(b"ls\n")
   tn.write(b"exit\n")

   print(tn.read_all().decode('ascii'))
