"nntplib" — Protocolo de cliente NNTP
*************************************

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

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

This module defines the class "NNTP" which implements the client side
of the Network News Transfer Protocol.  It can be used to implement a
news reader or poster, or automated news processors.  It is compatible
with **RFC 3977** as well as the older **RFC 977** and **RFC 2980**.

Aquí hay dos pequeños ejemplos de cómo se puede utilizar. Para
enumerar algunas estadísticas sobre un grupo de noticias e imprimir
los temas de los últimos 10 artículos:

   >>> s = nntplib.NNTP('news.gmane.io')
   >>> resp, count, first, last, name = s.group('gmane.comp.python.committers')
   >>> print('Group', name, 'has', count, 'articles, range', first, 'to', last)
   Group gmane.comp.python.committers has 1096 articles, range 1 to 1096
   >>> resp, overviews = s.over((last - 9, last))
   >>> for id, over in overviews:
   ...     print(id, nntplib.decode_header(over['subject']))
   ...
   1087 Re: Commit privileges for Łukasz Langa
   1088 Re: 3.2 alpha 2 freeze
   1089 Re: 3.2 alpha 2 freeze
   1090 Re: Commit privileges for Łukasz Langa
   1091 Re: Commit privileges for Łukasz Langa
   1092 Updated ssh key
   1093 Re: Updated ssh key
   1094 Re: Updated ssh key
   1095 Hello fellow committers!
   1096 Re: Hello fellow committers!
   >>> s.quit()
   '205 Bye!'

Para publicar un artículo desde un archivo binario (esto supone que el
artículo tiene encabezados válidos y que tienes permitido publicar en
el grupo de noticias en particular):

   >>> s = nntplib.NNTP('news.gmane.io')
   >>> f = open('article.txt', 'rb')
   >>> s.post(f)
   '240 Article posted successfully.'
   >>> s.quit()
   '205 Bye!'

El módulo en sí define las siguientes clases:

class nntplib.NNTP(host, port=119, user=None, password=None, readermode=None, usenetrc=False[, timeout])

   Retorna un nuevo objeto "NNTP" que representa una conexión con el
   servidor NNTP ejecutándose en el host *host*, escuchando en el
   puerto *port*. Se puede especificar un *timeout* opcional para la
   conexión de socket. Si se proporcionan las credenciales opcionales
   *user* y *password*, o si hay credenciales adecuadas en "/.netrc" y
   el indicador opcional *usenetrc* es verdadero, los comandos
   "AUTHINFO USER" y "AUTHINFO PASS" se utilizan para identificar y
   autenticar al usuario en el servidor.  Si el indicador opcional
   *readermode* es verdadero, se envía un comando "mode reader" antes
   de que se realice la autenticación. El modo de lector a veces es
   necesario si se conecta a un servidor NNTP en el equipo local y
   tiene la intención de llamar a comandos específicos del lector,
   como "group". Si obtienes un valor inesperado "NNTPPermanentError",
   es posible que debas establecer *readermode*. La clase "NNTP"
   admite la instrucción "with" para consumir incondicionalmente las
   excepciones "OSError" y para cerrar la conexión NNTP cuando haya
   terminado, e.g.:

   >>> from nntplib import NNTP
   >>> with NNTP('news.gmane.io') as n:
   ...     n.group('gmane.comp.python.committers')
   ... 
   ('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
   >>>

   Genera un evento de auditoría "nntplib.connect" con los argumentos
   "self", "host", "port".

   Genera un evento de auditoría "nntplib.putline" con los argumentos
   "self", "line".

   Distinto en la versión 3.2: *usenetrc* es ahora "False" por
   defecto.

   Distinto en la versión 3.3: El soporte para la declaración "with"
   fue añadido.

class nntplib.NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False[, timeout])

   Retorna un nuevo objeto "NNTP_SSL", que representa una conexión
   cifrada con el servidor NNTP ejecutándose en el host *host*,
   escuchando en el puerto *port*. Los objetos "NNTP_SSL" tienen los
   mismos métodos que los objetos "NNTP". Si se omite el *port* se
   utiliza el puerto 563 (NNTPS). *ssl_context* también es opcional, y
   también el objeto "SSLContext". Por favor, lea Security
   considerations para conocer las buenas prácticas. Todos los demás
   parámetros se comportan igual que para "NNTP".

   Tenga en cuenta que SSL-on-563 no es recomendado por **RFC 4642**,
   en favor de STARTTLS como se describe abajo. Sin embargo, algunos
   servidores solo admiten el primero.

   Genera un evento de auditoría "nntplib.connect" con los argumentos
   "self", "host", "port".

   Genera un evento de auditoría "nntplib.putline" con los argumentos
   "self", "line".

   Nuevo en la versión 3.2.

   Distinto en la versión 3.4: La clase ahora admite la verificación
   del nombre de host con "ssl.SSLContext.check_hostname" e *Indicador
   del nombre del servidor* (SNI por sus siglas en inglés, consulte
   "ssl.HAS_SNI").

exception nntplib.NNTPError

   Derivado de la excepción estándar "Exception", esta es la clase
   base para todas las excepciones generadas por el módulo "nntplib".
   Las instancias de esta clase tienen el siguiente atributo:

   response

      La respuesta del servidor, si está disponible, como un objeto
      "str".

exception nntplib.NNTPReplyError

   Excepción generada cuando se recibe una respuesta inesperada del
   servidor.

exception nntplib.NNTPTemporaryError

   Excepción generada cuando se recibe un código de respuesta dentro
   del rango del 400--499.

exception nntplib.NNTPPermanentError

   Excepción generada cuando se recibe un código de respuesta dentro
   del rango del 500--599.

exception nntplib.NNTPProtocolError

   Excepción generada cuando se recibe una respuesta del servidor que
   no comienza con un dígito dentro del rango 1--5.

exception nntplib.NNTPDataError

   Excepción generada cuando hay algún error en los datos de la
   respuesta.


Objetos NNTP
============

Cuando están conectados, los objetos "NNTP" y "NNTP_SSL" admiten los
siguientes métodos y atributos.


Atributos
---------

NNTP.nntp_version

   Un entero que representa la versión del protocolo NNTP compatible
   con el servidor. En la práctica, esto debería ser "2" para los
   servidores que anuncian el cumplimiento **RFC 3977** y "1" para
   otros.

   Nuevo en la versión 3.2.

NNTP.nntp_implementation

   Cadena que describe el nombre de software y la versión del servidor
   NNTP, o "None" si el servidor no lo anuncia.

   Nuevo en la versión 3.2.


Métodos
-------

La *response* que es retornada como el primer elemento de la tupla de
retorno de casi todos los métodos es la respuesta del servidor: una
cadena que comienza con un código de tres dígitos. Si la respuesta del
servidor indica un error, el método genera una de las excepciones
anteriores.

Muchos de los métodos siguientes toman un argumento opcional de
solamente palabra clave *file*. Cuando se proporciona el argumento
*file*, debe ser un *file object* abierto para la escritura binaria o
el nombre de un archivo en disco a ser escrito. El método escribirá
los datos retornados por el servidor (excepto la línea de respuesta y
el punto de terminación) en el archivo; cualquier lista de líneas,
tuplas u objetos que el método retorna normalmente estará vacía.

Distinto en la versión 3.2: Muchos de los siguientes métodos se han
rediseñado y corregido, lo que los hace incompatibles con sus
contrapartes 3.1.

NNTP.quit()

   Envía un comando "QUIT" y cierra la conexión. Una vez que se ha
   invocado este método, no se debe invocar ningún otro método del
   objeto NNTP.

NNTP.getwelcome()

   Retorna el mensaje de bienvenida enviado por el servidor en
   respuesta a la conexión inicial. (Este mensaje a veces contiene
   aclaraciones o información de ayuda que puede ser relevante para el
   usuario.)

NNTP.getcapabilities()

   Retorna las capacidades **RFC 3977** anunciadas por el servidor,
   como una instancia "dict" mapeando nombres de capacidades a listas
   de valores (posiblemente vacías). En los servidores heredados que
   no entienden el comando "CAPABILITIES", se retorna un diccionario
   vacío en su lugar.

   >>> s = NNTP('news.gmane.io')
   >>> 'POST' in s.getcapabilities()
   True

   Nuevo en la versión 3.2.

NNTP.login(user=None, password=None, usenetrc=True)

   Envía comandos "AUTHINFO" con el nombre de usuario y la contraseña.
   Si *user* y *password* son "None" y *usenetrc* es verdadero, se
   utilizarán las credenciales de "~/.netrc" si su uso es posible.

   A menos que se retrase intencionalmente, el inicio de sesión se
   realiza normalmente durante la inicialización del objeto "NNTP" y
   no es necesario invocar esta función por separado. Para forzar el
   retraso de la autenticación, no debes establecer *user* o
   *password* al crear el objeto y debes establecer *usenetrc* en
   *False*.

   Nuevo en la versión 3.2.

NNTP.starttls(context=None)

   Envía un comando "STARTTLS". Esto habilitará el cifrado en la
   conexión NNTP. El argumento *context* es opcional y debe ser el
   objeto "ssl. SSLContext". Por favor lea Security considerations
   para conocer las buenas prácticas.

   Tenga en cuenta que esto no se puede hacer después de que se haya
   transmitido la información de autenticación y la autenticación se
   produce de forma predeterminada, si es posible, durante la
   inicialización de un objeto "NNTP". Consulte "NNTP.login()" para
   obtener información sobre cómo suprimir este comportamiento.

   Nuevo en la versión 3.2.

   Distinto en la versión 3.4: El método ahora admite la comprobación
   del nombre de host con "ssl. SSLContext.check_hostname" y
   *Indicador del nombre del servidor* (SNI por sus siglas en inglés,
   consulte "ssl.HAS_SNI").

NNTP.newgroups(date, *, file=None)

   Envía un comando "NEWGROUPS". El argumento *date* debe ser un
   objeto "datetime.date" o "datetime.datetime". Retorna un par
   "(response, groups)" donde *groups* es una lista que representa los
   grupos que son nuevos desde la fecha determinada. Sin embargo, si
   se proporciona *file*, entonces *groups* estará vacío.

   >>> from datetime import date, timedelta
   >>> resp, groups = s.newgroups(date.today() - timedelta(days=3))
   >>> len(groups) 
   85
   >>> groups[0] 
   GroupInfo(group='gmane.network.tor.devel', last='4', first='1', flag='m')

NNTP.newnews(group, date, *, file=None)

   Envía un comando "NEWNEWS". Aquí, *group* es un nombre de grupo o
   "'*'", y *date* tiene el mismo significado que para "newgroups()".
   Retorna un par "(response, articles)" donde *articles* es una lista
   de identificadores de mensaje.

   Este comando es inhabilitado frecuentemente por los administradores
   del servidor NNTP.

NNTP.list(group_pattern=None, *, file=None)

   Envía un comando "LIST" o "LIST ACTIVE". Retorna un par "(response,
   list)" donde *list* es una lista de tuplas que representan todos
   los grupos disponibles desde este servidor NNTP, opcionalmente
   coincidiendo con el patrón de cadena *group_pattern*. Cada tupla
   tiene el formato "(group, last, first, flag)", donde *group* es un
   nombre de grupo, *last* y *first* son los últimos y primeros
   números de artículo, y *flag* suele tomar uno de estos valores:

   * "y": Se permiten publicaciones locales y artículos de pares.

   * "m": El grupo está moderado y todas las publicaciones deben ser
     aprobadas.

   * "n": No se permiten publicaciones locales, solo artículos de
     pares.

   * "j": Los artículos de pares se archivan en el grupo de basura en
     su lugar.

   * "x": No hay publicaciones locales y los artículos de pares son
     ignorados.

   * "=foo.bar": Los artículos se archivan en el grupo "foo.bar" en su
     lugar.

   Si *flag* tiene otro valor, el estado del grupo de noticias debe
   considerarse como desconocido.

   Este comando puede devolver resultados muy grandes, especialmente
   si no se especifica *group_pattern*. Es mejor almacenar en caché
   los resultados sin conexión a menos que realmente necesite
   actualizarlos.

   Distinto en la versión 3.2: *group_pattern* fue añadido.

NNTP.descriptions(grouppattern)

   Envía un comando "LIST NEWSGROUPS", donde *grouppattern* es una
   cadena comodín como se especifica en **RFC 3977** (es esencialmente
   lo mismo que las cadenas comodín de shell DOS o UNIX). Retorna un
   par "(response, descriptions)", donde *descriptions* es un
   diccionario que asigna nombres de grupos a descripciones textuales.

   >>> resp, descs = s.descriptions('gmane.comp.python.*')
   >>> len(descs) 
   295
   >>> descs.popitem() 
   ('gmane.comp.python.bio.general', 'BioPython discussion list (Moderated)')

NNTP.description(group)

   Obtiene una descripción para un único grupo *group*. Si más de un
   grupo coincide (si *'group'* es una cadena comodín real), retorna
   la primera coincidencia. Si ningún grupo coincide, retorna una
   cadena vacía.

   Esto elude el código de respuesta del servidor. Si necesita el
   código de respuesta, use "descriptions()".

NNTP.group(name)

   Envía un comando "GROUP", donde *name* es el nombre del grupo. El
   grupo se selecciona como el grupo actual, si este existe. Retorna
   una tupla "(response, count, first, last, name)" donde *count* es
   el número (estimado) de artículos en el grupo, *first* es el primer
   número de artículo del grupo, *last* es el último número de
   artículo en el grupo y *name* es el nombre del grupo.

NNTP.over(message_spec, *, file=None)

   Envía un comando "OVER" o un comando "XOVER" en servidores
   heredados. *message_spec* puede ser una cadena que represente un
   identificador de mensaje o una tupla de números "(first, None)" que
   indique un rango de artículos en el grupo actual, o una tupla
   "(first, None)" que indique un rango de artículos comenzando desde
   *first* hasta el último artículo del grupo actual, o "None" para
   seleccionar el artículo actual en el grupo actual.

   Retorna un par "(response, overviews)". *overviews* es una lista de
   tuplas del tipo "(article_number, overview)", una para cada
   artículo seleccionado por *message_spec*. Cada *overview* es un
   diccionario con el mismo número de elementos, pero este número
   depende del servidor. Estos elementos son encabezados de mensajes
   (la clave es entonces el nombre del encabezado en minúsculas) o
   elementos de metadatos (la clave es entonces el nombre de los
   metadatos precedido de "":""). Se garantiza la presencia de los
   siguientes elementos por la especificación NNTP:

   * los encabezados "subject", "from", "date", "message-id" y
     "references"

   * los metadatos ":bytes": el número de bytes en todo el artículo
     sin procesar (incluidos los encabezados y el cuerpo)

   * los metadatos ":lines": el número de líneas en el cuerpo del
     artículo

   El valor de cada elemento es una cadena o "None" si no está
   presente.

   Es aconsejable utilizar la función "decode_header()" en los valores
   del encabezado cuando pueden contener caracteres no-ASCII:

      >>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
      >>> resp, overviews = s.over((last, last))
      >>> art_num, over = overviews[0]
      >>> art_num
      117216
      >>> list(over.keys())
      ['xref', 'from', ':lines', ':bytes', 'references', 'date', 'message-id', 'subject']
      >>> over['from']
      '=?UTF-8?B?Ik1hcnRpbiB2LiBMw7Z3aXMi?= <martin@v.loewis.de>'
      >>> nntplib.decode_header(over['from'])
      '"Martin v. Löwis" <martin@v.loewis.de>'

   Nuevo en la versión 3.2.

NNTP.help(*, file=None)

   Envía un comando "HELP". Retorna un par "(response, list)" donde
   *list* es una lista de cadenas de caracteres de ayuda.

NNTP.stat(message_spec=None)

   Envía un comando "STAT", donde *message_spec* es un identificador
   de mensaje (incluido en "'<'" y "'>'") o un número de artículo en
   el grupo actual. Si se omite *message_spec* o es "None" se
   considera el artículo actual del grupo actual. Retorna un triple
   "(response, number, id)" donde *number* es el número de artículo e
   *id* es el identificador del mensaje.

   >>> _, _, first, last, _ = s.group('gmane.comp.python.devel')
   >>> resp, number, message_id = s.stat(first)
   >>> number, message_id
   (9099, '<20030112190404.GE29873@epoch.metaslash.com>')

NNTP.next()

   Envía un comando "NEXT". Retorna como para "stat()".

NNTP.last()

   Envía un comando "LAST". Retorna como para "stat()".

NNTP.article(message_spec=None, *, file=None)

   Envía un comando "ARTICLE", donde *message_spec* tiene el mismo
   significado que para "stat()". Retorna una tupla "(response, info)"
   donde *info* es un "namedtuple" con tres atributos *number*,
   *message_id* y *lines* (en ese orden). *number* es el número de
   artículo del grupo (o 0 si la información no está disponible),
   *message_id* el identificador del mensaje como una cadena y *lines*
   una lista de líneas (sin terminar líneas nuevas) que comprende el
   mensaje sin procesar, incluidos los encabezados y el cuerpo.

   >>> resp, info = s.article('<20030112190404.GE29873@epoch.metaslash.com>')
   >>> info.number
   0
   >>> info.message_id
   '<20030112190404.GE29873@epoch.metaslash.com>'
   >>> len(info.lines)
   65
   >>> info.lines[0]
   b'Path: main.gmane.org!not-for-mail'
   >>> info.lines[1]
   b'From: Neal Norwitz <neal@metaslash.com>'
   >>> info.lines[-3:]
   [b'There is a patch for 2.3 as well as 2.2.', b'', b'Neal']

NNTP.head(message_spec=None, *, file=None)

   Igual que "article()", pero envía un comando "HEAD". Las *lines*
   retornadas (o escritas a *file*) solo contendrán los encabezados
   del mensaje, no el cuerpo.

NNTP.body(message_spec=None, *, file=None)

   Igual que "article()", pero envía un comando "BODY". Las *lines*
   retornadas (o escritas a *file*) solo contendrán los encabezados
   del mensaje, no el cuerpo.

NNTP.post(data)

   Publica un artículo utilizando el comando "POST". El argumento
   *data* es un *file object* abierto para la lectura binaria o
   cualquier iterable de objetos bytes (que representa las líneas sin
   procesar del artículo que se va a publicar). Debe representar un
   artículo de noticias bien formado, incluidos los encabezados
   requeridos. El método "post()" escapa automáticamente las líneas
   que comienzan con "." y añade la línea de terminación.

   Si el método tiene éxito, se retorna la respuesta del servidor. Si
   el servidor se niega a publicarlo, se genera un "NNTPReplyError".

NNTP.ihave(message_id, data)

   Envía un comando "IHAVE". *message_id* es el identificador del
   mensaje que se enviará al servidor (incluido entre "'<'" y "'>'").
   El parámetro *data* y el valor de retorno son los mismos que para
   "post()".

NNTP.date()

   Devuelve un par "(response, date)". *date* es un objeto "datetime"
   que contiene la fecha y hora actuales del servidor.

NNTP.slave()

   Envía un comando "SLAVE". Retorna la *response* del servidor.

NNTP.set_debuglevel(level)

   Establece el nivel de depuración de la instancia. Esto controla la
   cantidad de salida de depuración impresa. El valor por defecto,
   "0", no produce salida de depuración. Un valor de "1" produce una
   cantidad moderada de salida de depuración, generalmente una sola
   línea por solicitud o por respuesta. Un valor de "2" o superior
   produce la cantidad máxima de salida de depuración, registrando
   cada línea enviada y recibida en la conexión (incluyendo el texto
   del mensaje).

Las siguientes son extensiones NNTP opcionales definidas en **RFC
2980**. Algunas de ellas han sido reemplazados por comandos más nuevos
en **RFC 3977**.

NNTP.xhdr(hdr, str, *, file=None)

   Envía un comando "XHDR". El argumento *hdr* es una palabra clave de
   encabezado, por ejemplo "'subject'". El argumento *str* debe tener
   la forma "'first-last'" donde *first* y *last* son el primer y
   último número de artículo para buscar. Retorna un par "(response,
   list)", donde *list* es una lista de pares "(id, text)", donde *id*
   es un número de artículo (como una cadena) y *text* es el texto del
   encabezado solicitado para ese artículo. Si se proporciona el
   parámetro *file*, entonces la salida del comando "XHDR" se almacena
   en un archivo. Si *file* es una cadena, entonces el método abrirá
   un archivo con ese nombre, que escribirá en él y luego lo cerrará.
   Si *file* es un *file object*, entonces comenzará invocando
   "write()" en él para almacenar las líneas de la salida del comando.
   Si se proporciona *file*, entonces retorna *list* o una lista
   vacía.

NNTP.xover(start, end, *, file=None)

   Envía un comando "XOVER". *start* and *end* son números de artículo
   que delimitan el rango de artículos a seleccionar. El valor de
   retorno es el mismo que para "over()". Se recomienda usar "over()"
   en su lugar, ya que se usará automáticamente el comando más nuevo
   "OVER" si está disponible.

NNTP.xpath(id)

   Retorna un par "(resp, path)", donde *path* es la ruta del
   directorio al artículo con un ID de mensaje *id*. La mayoría de las
   veces, los administradores del servidor NNTP no habilitan esta
   extensión.

   Obsoleto desde la versión 3.3: La extensión XPATH no se utiliza
   activamente.


Funciones de utilidad
=====================

El módulo también define la siguiente función de utilidad:

nntplib.decode_header(header_str)

   Decodifica un valor de encabezado, eliminando los caracteres de
   escape que no sean ASCII. *header_str* debe ser un objeto "str". Se
   retorna el valor sin escape. Se recomienda utilizar esta función
   para mostrar algunos encabezados en una forma legible por humanos:

      >>> decode_header("Some subject")
      'Some subject'
      >>> decode_header("=?ISO-8859-15?Q?D=E9buter_en_Python?=")
      'Débuter en Python'
      >>> decode_header("Re: =?UTF-8?B?cHJvYmzDqG1lIGRlIG1hdHJpY2U=?=")
      'Re: problème de matrice'
