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'