mailbox — Manipular buzones de correo en varios formatos

Código fuente: Lib/mailbox.py

Este módulo define dos clases, Mailbox y Message, para acceder y manipular en disco los buzones de correo y los mensajes que contienen. Mailbox ofrece una asignación similar a un diccionario de claves a mensajes. Message extiende la clase email.message del módulo Message con el estado y el comportamiento específicos del formato. Los formatos de buzón de correo compatibles son Maildir, mbox, MH, Babyl y MMDF.

Ver también

Módulo email

Representar y manipular mensajes.

Objetos :class:”Mailbox”

class mailbox.Mailbox

Un buzón de correo, que se puede inspeccionar y modificar.

La clase Mailbox define una interfaz y no está diseñada para crear instancias. En su lugar, las subclases específicas del formato deben heredar de Mailbox y el código debe crear una instancia de una subclase determinada.

La interfaz Mailbox es similar a un diccionario, con pequeñas claves correspondientes a los mensajes. Las claves son emitidas por la instancia Mailbox con la que se utilizarán y solo son significativas para esa instancia Mailbox. Una clave continúa identificando un mensaje incluso si se modifica el mensaje correspondiente, por ejemplo, sustituyéndolo por otro mensaje.

Los mensajes se pueden agregar a una instancia Mailbox utilizando el método como add() y quitarse mediante una instrucción del o los métodos como remove() y discard().

La semántica de la interfaz Mailbox difiere de la semántica del diccionario en algunos aspectos notables. Cada vez que se solicita un mensaje, se genera una nueva representación (típicamente una instancia Message) basada en el estado actual del buzón de correo. De forma similar, cuando se añade un mensaje a una instancia Mailbox, se copia el contenido de la representación del mensaje proporcionado. En ninguno de los dos casos se mantiene una referencia a la representación del mensaje por parte de la instancia Mailbox.

El iterador por defecto de Mailbox itera sobre las representaciones de los mensajes, no sobre las claves como lo hace el iterador del diccionario por defecto. Además, la modificación de un buzón de correo durante la iteración es segura y bien definida. Los mensajes añadidos al buzón de correo después de que se cree un iterador no serán vistos por el iterador. Los mensajes eliminados del buzón de correo antes de que el iterador los ceda serán omitidos silenciosamente, aunque el uso de una clave de un iterador puede dar lugar a una excepción KeyError si el mensaje correspondiente es eliminado posteriormente.

Advertencia

Sea muy cauteloso al modificar los buzones de correo que pueden ser cambiados simultáneamente por algún otro proceso. El formato más seguro de buzón de correo que se puede utilizar para esas tareas es Maildir; trate de evitar el uso de formatos de un solo archivo, como mbox, para la escritura simultánea. Si estás modificando un buzón de correo, debes bloquearlo llamando a los métodos lock() y unlock() antes de leer cualquier mensaje en el fichero o hacer cualquier cambio añadiendo o borrando un mensaje. Si no se bloquea el buzón se corre el riesgo de perder mensajes o de corromper todo el buzón.

Las instancias de Mailbox tienen los siguientes métodos:

add(message)

Añade message al buzón de correo y retorna la clave que se le ha asignado.

El parámetro message puede ser una instancia Message, una instancia email.message.Message, una cadena, una cadena de bytes o un objeto tipo archivo (que debe estar abierto en modo binario). Si message es una instancia de la subclase Message con el formato apropiado (por ejemplo, si es una instancia mboxMessage y ésta es una instancia mbox), se utiliza su información de formato específico. En caso contrario, se utilizan valores por defecto razonables para la información específica del formato.

Distinto en la versión 3.2: Se añadió el soporte para la entrada binaria.

remove(key)
__delitem__(key)
discard(key)

Borre el mensaje correspondiente a la key del buzón de correo.

Si no existe tal mensaje, se levanta una excepción KeyError si el método se llamó remove() o __delitem__() pero no se levanta una excepción si el método se llamó discard(). El comportamiento de discard() puede ser preferido si el formato de buzón subyacente soporta la modificación concurrente por otros procesos.

__setitem__(key, message)

Reemplaza el mensaje correspondiente a key por message. Levante una excepción KeyError si ningún mensaje ya corresponde a key.

Al igual que add(), el parámetro message puede ser una instancia Message, una instancia email.message.Message, una cadena, una cadena de bytes, o un objeto tipo archivo (que debe estar abierto en modo binario). Si message es una instancia de la subclase Message con el formato apropiado (por ejemplo, si es una instancia mboxMessage y ésta es una instancia mbox), se utiliza su información de formato específico. En caso contrario, la información específica del formato del mensaje que actualmente corresponde a key se deja sin cambios.

iterkeys()
keys()

Retorna un iterador sobre todas las claves si se llama iterkeys() o retorna una lista de claves si se llama keys().

itervalues()
__iter__()
values()

Retorna un iterador sobre las representaciones de todos los mensajes si se llama itervalores() o __iter__() o retorna una lista de tales representaciones si se llama values(). Los mensajes se representan como instancias de la subclase Message específica del formato, a menos que se haya especificado una fábrica de mensajes personalizados cuando se haya inicializado la instancia Mailbox.

Nota

El comportamiento de __iter__() es diferente al de los diccionarios, que iteran sobre las claves.

iteritems()
items()

Retorna un iterador sobre los pares (key, message), donde key es una clave y message es una representación de un mensaje, si se llama como iteritems() o retorna una lista de tales pares si se llama como items(). Los mensajes se representan como instancias de la subclase Message específica del formato, a menos que se haya especificado una fábrica de mensajes personalizados cuando se haya inicializado la instancia Maiblox.

get(key, default=None)
__getitem__(key)

Retorna una representación del mensaje correspondiente a key. Si no existe tal mensaje, se retorna default si el método fue llamado como get() y se produce una excepción KeyError si el método fue llamado como __getitem__(). El mensaje se representa como una instancia de la subclase Message específica del formato, a menos que se especificara una fábrica de mensajes personalizados cuando se inicializa la instancia Mailbox.

get_message(key)

Retorna una representación del mensaje correspondiente a key como una instancia de la subclase Message específica del formato, o lanza una excepción KeyError si no existe tal mensaje.

get_bytes(key)

Retorna una representación en bytes del mensaje correspondiente a key, o levanta una excepción KeyError si no existe tal mensaje.

Nuevo en la versión 3.2.

get_string(key)

Retorna una representación en cadena del mensaje correspondiente a key, o lanza una excepción KeyError si no existe tal mensaje. El mensaje se procesa a través de email.message.Message para convertirlo en una representación limpia de 7 bits.

get_file(key)

Retorna una representación en forma de archivo del mensaje correspondiente a key, o lanza una excepción KeyError si no existe tal mensaje. El objeto tipo archivo se comporta como si estuviera abierto en modo binario. Este archivo debería cerrarse una vez que ya no se necesite.

Distinto en la versión 3.2: El objeto del archivo es realmente un archivo binario; anteriormente fue retornado incorrectamente en modo de texto. Además, el objeto tipo archivo ahora soporta el protocolo de gestión de contexto: puedes usar una sentencia with para cerrarlo automáticamente.

Nota

A diferencia de otras representaciones de mensajes, las representaciones en forma de archivo no son necesariamente independientes de la instancia Mailbox que las creó o del buzón de correo subyacente. Cada subclase proporciona una documentación más específica.

__contains__(key)

Retorna True si «key» corresponde a un mensaje, si no False.

__len__()

Retorna un recuento de los mensajes en el buzón de correo.

clear()

Borrar todos los mensajes del buzón.

pop(key, default=None)

Retorna una representación del mensaje correspondiente a key y borra el mensaje. Si no existe tal mensaje, retorna default. El mensaje se representa como una instancia de la subclase Message con el formato apropiado, a menos que se haya especificado una fábrica de mensajes personalizados al inicializar la instancia Mailbox.

popitem()

Retorna un par arbitrario (key, message), donde key es una clave y message es una representación de un mensaje, y borra el mensaje correspondiente. Si el buzón de correo está vacío, lanza una excepción KeyError. El mensaje se representa como una instancia de la subclase Message específica del formato, a menos que se haya especificado una fábrica de mensajes personalizados al inicializar la instancia Mailbox.

update(arg)

El parámetro arg debe ser un mapa de key a message o un iterable de pares (key, message). Actualiza el buzón de correo para que, por cada key y message dados, el mensaje correspondiente a key será establecido a*message* como si se usara __setitem__(). Como con __setitem__(), cada key debe corresponder ya a un mensaje en el buzón de correo o de lo contrario se lanzará una excepción KeyError, por lo que en general es incorrecto que arg sea una instancia de Mailbox.

Nota

A diferencia de los diccionarios, los argumentos de las palabras clave no están soportados.

flush()

Escribe cualquier cambio pendiente en el sistema de archivos. Para algunas subclases de Mailbox, los cambios siempre se escriben inmediatamente y flush() no hace nada, pero aún así deberías tener el hábito de llamar a este método.

lock()

Adquiera un aviso exclusivo de bloqueo en el buzón de correo para que otros procesos sepan que no deben modificarlo. Un ExternalClashError se lanza si el bloqueo no está disponible. Los mecanismos de bloqueo particulares utilizados dependen del formato del buzón de correo. Deberías siempre bloquear el buzón antes de hacer cualquier modificación a su contenido.

unlock()

Libera el bloqueo del buzón de correo, si lo hay.

close()

Limpia el buzón de correo, y lo desbloquea si es necesario, y cierra cualquier archivo abierto. Para algunas subclases de Mailbox, este método no hace nada.

Maildir

class mailbox.Maildir(dirname, factory=None, create=True)

Una subclase de Mailbox para los buzones de correo en formato Maildir. El parámetro factory es un objeto invocable que acepta una representación de mensaje tipo archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, MaildirMessage se utiliza como representación de mensaje por defecto. Si create es True, el buzón se crea si no existe.

Si create es True y la ruta de dirname existe, será tratado como un maildir existente sin intentar verificar su diseño de directorio.

Es por razones históricas que dirname es nombrado como tal en lugar de path.

Maildir es un formato de buzón de correo basado en un directorio inventado para el agente de transferencia de correo qmail y ahora ampliamente soportado por otros programas. Los mensajes en un buzón de correo de Maildir se almacenan en archivos separados dentro de una estructura de directorio común. Este diseño permite que los buzones de Maildir sean accedidos y modificados por múltiples programas no relacionados sin corrupción de datos, por lo que el bloqueo de archivos es innecesario.

Los buzones de correo de Maildir contienen tres subdirectorios, a saber: tmp, new, y cur. Los mensajes se crean momentáneamente en el subdirectorio tmp y luego se mueven al subdirectorio new para finalizar la entrega. Un agente de usuario de correo puede posteriormente mover el mensaje al subdirectorio cur y almacenar la información sobre el estado del mensaje en una sección especial «info» adjunta a su nombre de archivo.

Se admiten también carpetas del estilo introducido por el agente de transferencia de correo Courier. Cualquier subdirectorio del buzón de correo principal se considera una carpeta si '.' es el primer carácter de su nombre. Los nombres de las carpetas están representados por Maildir sin la palabra '.'. Cada carpeta es en sí misma un buzón de correo de Maildir pero no debe contener otras carpetas. En su lugar, se indica un anidamiento lógico usando '.' para delimitar los niveles, por ejemplo, «Archived.2005.07».

Nota

La especificación Maildir requiere el uso de dos puntos (':') en ciertos nombres de archivos de mensajes. Sin embargo, algunos sistemas operativos no permiten este carácter en los nombres de archivo, si desea utilizar un formato similar a Maildir en dicho sistema operativo, debe especificar otro carácter para utilizarlo en su lugar. El signo de exclamación ('!') es una elección popular. Por ejemplo:

import mailbox
mailbox.Maildir.colon = '!'

El atributo colon también puede ser establecido para cada instancia.

Las instancias de Maildir tienen todos los métodos de Mailbox además de los siguientes:

list_folders()

Retorna una lista con los nombres de todas las carpetas.

get_folder(folder)

Retorna una instancia Maildir que representa la carpeta cuyo nombre es folder. Una excepción NoSuchMailboxError se lanza si la carpeta no existe.

add_folder(folder)

Crea una carpeta cuyo nombre sea folder y retorna una instancia Maildir que la represente.

remove_folder(folder)

Elimina la carpeta cuyo nombre es folder. Si la carpeta contiene algún mensaje, se lanzará una excepción NotEmptyError y la carpeta no se borrará.

clean()

Borra los archivos temporales del buzón de correo que no han sido accedidos en las últimas 36 horas. La especificación Maildir dice que los programas de lectura de correo deben hacer esto ocasionalmente.

Algunos métodos de Mailbox implementados por Maildir merecen comentarios especiales:

add(message)
__setitem__(key, message)
update(arg)

Advertencia

Estos métodos generan nombres de archivo únicos basados en el ID del proceso actual. Cuando se utilizan varios hilos, pueden producirse conflictos de nombres no detectados y causar la corrupción del buzón de correo a menos que se coordinen los hilos para evitar que se utilicen estos métodos para manipular el mismo buzón de correo simultáneamente.

flush()

Todos los cambios en los buzones de Maildir se aplican inmediatamente, así que este método no hace nada.

lock()
unlock()

Los buzones de Maildir no admiten (o requieren) bloqueo, por lo que estos métodos no hacen nada.

close()

Las instancias de Maildir no mantienen ningún archivo abierto y los buzones subyacentes no soportan el bloqueo, por lo que este método no hace nada.

get_file(key)

Dependiendo de la plataforma del host, puede que no sea posible modificar o eliminar el mensaje subyacente mientras el archivo retornado permanezca abierto.

Ver también

pagina web maildir de Courier

Una especificación del formato. Describe una extensión común para admitir carpetas.

Utilizando el formato maildir

Notas sobre Maildir por su inventor. Incluye un esquema actualizado de creación de nombres y detalles sobre la «info» de la semántica».

mbox

class mailbox.mbox(path, factory=None, create=True)

Una subclase de Mailbox para los buzones de correo en formato mbox. El parámetro factory es un objeto invocable que acepta una representación de mensaje tipo archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, mboxMessage se utiliza como representación de mensaje por defecto. Si create es True, el buzón de correo se crea si no existe.

El formato mbox es el formato clásico para almacenar correo en sistemas Unix. Todos los mensajes de un buzón de correo mbox se almacenan en un único archivo con el comienzo de cada mensaje indicado por una línea cuyos cinco primeros caracteres son «From».

Existen varias variaciones del formato mbox para abordar las deficiencias percibidas en el original. En aras de la compatibilidad, mbox implementa el formato original, que a veces se denomina mboxo. Esto significa que el encabezado Content-Length, si está presente, se ignora y que cualquier ocurrencia de «From » al principio de una línea en el cuerpo de un mensaje se transforma en «>From » al almacenar el mensaje, aunque las ocurrencias de «>From » no se transforman en «From » al leer el mensaje.

Algunos métodos de Mailbox implementados por Maildir merecen comentarios especiales:

get_file(key)

Usar el archivo después de llamar a flush() o close() en la instancia mbox puede producir resultados impredecibles o lanzar una excepción.

lock()
unlock()

Se utilizan tres mecanismos de bloqueo… el bloqueo por puntos y, si está disponible, las llamadas del sistema flock() y lockf().

Ver también

pagina web mbox de tin

Una especificación del formato, con detalles sobre el bloqueo.

Configurando el correo de Netscape en Unix: Por qué el formato de longitud de contenido es malo

Un argumento para usar el formato original mbox en lugar de una variación.

«mbox» es una familia de varios formatos de buzón de correo mutuamente incompatibles <https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml>`__

Una historia de variaciones de mbox.

MH

class mailbox.MH(path, factory=None, create=True)

Una subclase de Mailbox para los buzones de correo en formato MH. El parámetro factory es un objeto invocable que acepta una representación de mensaje tipo archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, MHMessage se utiliza como representación de mensaje por defecto. Si create es True, el buzón de correo se crea si no existe.

MH es un formato de buzón de correo basado en un directorio inventado para el Sistema de Manejo de Mensajes MH, un agente de usuario de correo. Cada mensaje de un buzón de correo MH reside en su propio archivo. Un buzón de correo MH puede contener otros buzones de correos MH (llamados folders) además de los mensajes. Las carpetas pueden anidarse indefinidamente. Los buzones de correo MH también soportan sequences, que son listas con nombre usadas para agrupar lógicamente los mensajes sin moverlos a subcarpetas. Las secuencias se definen en un archivo llamado .mh_sequences en cada carpeta.

La clase MH manipula los buzones de correos de MH, pero no intenta emular todos los comportamientos de mh. En particular, no modifica ni se ve afectado por los archivos de context o .mh_profile que utiliza mh para almacenar su estado y configuración.

Las instancias de Maildir tienen todos los métodos de Mailbox además de los siguientes:

list_folders()

Retorna una lista con los nombres de todas las carpetas.

get_folder(folder)

Retorna una instancia Maildir que representa la carpeta cuyo nombre es folder. Una excepción NoSuchMailboxError se lanza si la carpeta no existe.

add_folder(folder)

Crea una carpeta cuyo nombre sea folder y retorna una instancia MH que la represente.

remove_folder(folder)

Elimina la carpeta cuyo nombre es folder. Si la carpeta contiene algún mensaje, se lanzará una excepción NotEmptyError y la carpeta no se borrará.

get_sequences()

Retorna un diccionario de nombres de secuencias mapeadas a listas clave. Si no hay secuencias, se retorna el diccionario vacío.

set_sequences(sequences)

Re-define las secuencias que existen en el buzón de correo basado en sequences, un diccionario de nombres mapeados a listas de claves, como las retornadas por get_sequences().

pack()

Renombra los mensajes en el buzón de correo según sea necesario para eliminar los huecos en la numeración. Las entradas en la lista de secuencias se actualizan correspondientemente.

Nota

Las llaves ya emitidas quedan invalidadas por esta operación y no deben utilizarse posteriormente.

Algunos métodos de Mailbox implementados por Maildir merecen comentarios especiales:

remove(key)
__delitem__(key)
discard(key)

Estos métodos borran inmediatamente el mensaje. No se utiliza la convención del MH de marcar un mensaje para borrarlo poniendo una coma en su nombre.

lock()
unlock()

Se utilizan tres mecanismos de bloqueo… el bloqueo por puntos y, si está disponible, las llamadas del sistema flock() y lockf(). Para los buzones de correos MH, bloquear el buzón de correo significa bloquear el archivo .mh_sequences y, sólo durante la duración de cualquier operación que les afecte, bloquear los archivos de mensajes individuales.

get_file(key)

Dependiendo de la plataforma anfitriona, puede que no sea posible eliminar el mensaje subyacente mientras el archivo retornado permanezca abierto.

flush()

Todos los cambios en los buzones de correos de Maildir se aplican inmediatamente, así que este método no hace nada.

close()

Las instancias de MH no mantienen ningún archivo abierto, así que este método es equivalente a unlock().

Ver también

nmh - Sistema de Manejo de Mensajes

Página principal de nmh, una versión actualizada del original mh.

MH & nmh: Correo electrónico para usuarios y programadores

Un libro con licencia GPL sobre mh y nmh, con alguna información sobre el formato del buzón.

Babyl

class mailbox.Babyl(path, factory=None, create=True)

Una subclase de Mailbox para los buzones en formato Babyl. El parámetro factory es un objeto invocable que acepta una representación de mensaje tipo archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, BabylMessage se utiliza como representación de mensaje por defecto. Si create es True, el buzón se crea si no existe.

Babyl es un formato de buzón de un solo archivo usado por el agente de usuario de correo de Rmail incluido en Emacs. El comienzo de un mensaje se indica con una línea que contiene los dos caracteres Control-Underscore ('\037') y Control-L ('\014'). El final de un mensaje se indica con el comienzo del siguiente mensaje o, en el caso del último mensaje, una línea que contiene un carácter Control-Underscore ('\037').

Los mensajes en un buzón de correo de Babyl tienen dos juegos de encabezados, los encabezados originales y los llamados encabezados visibles. Los encabezados visibles son típicamente un subconjunto de los encabezados originales que han sido reformateados o abreviados para ser más atractivos. Cada mensaje de un buzón de correo de Babyl también tiene una lista de labels, o cadenas cortas que registran información adicional sobre el mensaje, y una lista de todas las etiquetas definidas por el usuario que se encuentran en el buzón de correo se mantiene en la sección de opciones de Babyl.

Las instancias de Maildir tienen todos los métodos de Mailbox además de los siguientes:

get_labels()

Retorna una lista de los nombres de todas las etiquetas definidas por el usuario utilizadas en el buzón de correo.

Nota

Los mensajes actuales se inspeccionan para determinar qué etiquetas existen en el buzón de correo en lugar de consultar la lista de etiquetas en la sección de opciones de Babyl, pero la sección de Babyl se actualiza cada vez que se modifica el buzón de correo.

Algunos métodos de Mailbox implementados por Maildir merecen comentarios especiales:

get_file(key)

En los buzones de correos de Babyl, los encabezados de un mensaje no se almacenan contiguamente al cuerpo del mensaje. Para generar una representación tipo archivo, las cabeceras y el cuerpo se copian juntos en una instancia io.BytesIO, que tiene una API idéntica a la de un archivo. Como resultado, el objeto similar a un archivo es verdaderamente independiente del buzón de correo subyacente, pero no ahorra memoria en comparación con una representación en cadena.

lock()
unlock()

Se utilizan tres mecanismos de bloqueo… el bloqueo por puntos y, si está disponible, las llamadas del sistema flock() y lockf().

Ver también

«Formato de la versión 5 de los archivos de Babyl» <https://quimby.gnus.org/notes/BABYL>`_

Una especificación del formato Babyl.

Leyendo el correo con Rmail

El manual de Rmail, con cierta información sobre la semántica Babyl.

MMDF

class mailbox.MMDF(path, factory=None, create=True)

Una subclase de Mailbox para buzones de correos en formato MMDF. El parámetro factory es un objeto al que se puede llamar que acepta una representación de mensaje similar a un archivo (que se comporta como si se abriera en modo binario) y retorna una representación personalizada. Si factory es None, MMDFMessage se utiliza como representación de mensaje predeterminada. Si create es True, el buzón de correo se crea si no existe.

MMDF es un formato de buzón de correo de un solo archivo inventado para el centro de distribución de memorandos multicanal, un agente de transferencia de correo. Cada mensaje está en la misma forma que un mensaje de mbox, pero está entre corchetes antes y después por líneas que contienen cuatro caracteres Control-A ('\001'). Al igual que con el formato mbox, el principio de cada mensaje se indica mediante una línea cuyos primeros cinco caracteres son «From «, pero las apariciones adicionales de «From» no se transforman en «>From» al almacenar mensajes porque las líneas de separador de mensajes adicionales impiden confundir tales ocurrencias para los inicios de los mensajes posteriores.

Algunos métodos Mailbox implementados por MMDF merecen comentarios especiales:

get_file(key)

Usar el archivo después de llamar a flush() o close() en la instancia MMDF puede producir resultados impredecibles o generar una excepción.

lock()
unlock()

Se utilizan tres mecanismos de bloqueo… el bloqueo por puntos y, si está disponible, las llamadas del sistema flock() y lockf().

Ver también

Página web de mmdf de tin

Una especificación del formato MMDF de la documentación de tin, un lector de noticias.

MMDF

Un artículo de Wikipedia que describe el Centro de Distribución de Memorandos Multicanal.

Objetos Message

class mailbox.Message(message=None)

Una subclase del módulo email.message de Message. Las subclases de mailbox.Message añaden el estado y el comportamiento específicos del formato del buzón de correo.

Si se omite message, la nueva instancia se crea en un estado predeterminado, vacío. Si message es una instancia email.message.Message, se copian sus contenidos; además, cualquier información específica del formato se convierte en la medida de lo posible si message es una instancia Message. Si message es una cadena, una cadena de bytes, o un archivo, debe contener un mensaje conforme RFC 2822, que se lee y analiza. Los archivos deben estar abiertos en modo binario, pero los archivos en modo texto son aceptados para compatibilidad con versiones anteriores.

El estado y los comportamientos específicos del formato que ofrecen las subclases varían, pero en general sólo se admiten las propiedades que no son específicas de un buzón de correo concreto (aunque presumiblemente las propiedades son específicas de un formato de buzón de correo concreto). Por ejemplo, no se conservan las compensaciones de archivos para los formatos de buzón de correo de un solo archivo ni los nombres de archivo para los formatos de buzón de correo basados en directorios, porque sólo son aplicables al buzón de correo original. Pero sí se conservan las declaraciones tales como si un mensaje ha sido leído por el usuario o marcado como importante, porque se aplican al propio mensaje.

No hay ningún requisito de que las instancias de Message se usen para representar los mensajes recuperados usando las instancias de Mailbox. En algunas situaciones, el tiempo y la memoria necesarios para generar representaciones de Message podrían no ser aceptables. Para estas situaciones, las instancias de Mailbox también ofrecen representaciones en forma de cadenas y archivos, y se puede especificar una fábrica de mensajes personalizados cuando se inicializa una instancia de Mailbox.

MaildirMessage

class mailbox.MaildirMessage(message=None)

Un mensaje con comportamientos específicos de Maildir. El parámetro message tiene el mismo significado que con el constructor Message.

Típicamente, una aplicación de agente de usuario de correo mueve todos los mensajes del subdirectorio new al subdirectorio cur después de la primera vez que el usuario abre y cierra el buzón de coreo, registrando que los mensajes son antiguos, tanto si han sido leídos como si no. Cada mensaje en cur tiene una sección «info» añadida a su nombre de archivo para almacenar información sobre su estado. (Algunos lectores de correo también pueden añadir una sección «info» a los mensajes en new.) La sección «info» puede tomar una de dos formas: puede contener «2», seguido de una lista de flags estandarizados (por ejemplo, «2,FR») o puede contener «1», seguido de la llamada información experimental. Los flags normalizados para los mensajes de Maildir son los siguientes:

Flag

Significado

Explicación

D

Borrador

Bajo composición

F

Marcada

Marcado como importante

P

Aprobado

Enviado, reenviado o rebotado

R

Contestado

Contestado a

S

Visto

Leído

T

Destruido

Marcado para su posterior eliminación

Instancias de MaildirMessage ofrecen los siguientes métodos:

get_subdir()

Retorna «new» (si el mensaje debe ser almacenado en el subdirectorio new) o «cur» (si el mensaje debe ser almacenado en el subdirectorio cur).

Nota

Un mensaje es típicamente movido de nuevo a cur después de que su buzón de correo ha sido accedido, ya sea que el mensaje haya sido leído o no. Un mensaje msg ha sido leído si "S" in msg.get_flags() es True.

set_subdir(subdir)

Establece el subdirectorio en el que debe almacenarse el mensaje. El parámetro subdir debe ser «new» o «cur».

get_flags()

Retorna una cadena que especifica los flags que están actualmente establecidos. Si el mensaje cumple con el formato estándar de Maildir, el resultado es la concatenación en orden alfabético de cero o una ocurrencia de cada una de los flags 'D', 'F', 'P', 'R', 'S', y 'T'. La cadena vacía se retorna si no hay flags o si «info» contiene semántica experimental.

set_flags(flags)

Establece los flags especificados por flags y desactiva todas las demás.

add_flag(flag)

Establece lo(s) flag(s) especificado(s) por flags sin cambiar otros flags. Para añadir más de un indicador a la vez, flag puede ser una cadena de más de un carácter. La «info» actual se sobrescribe si contiene o no información experimental en lugar de flags.

remove_flag(flag)

Deshabilita lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para quitar más de un indicador a la vez, flag puede ser una cadena de más de un carácter. Si «info» contiene información experimental en lugar de flags, la «info» actual no se modifica.

get_date()

Retorna la fecha de entrega del mensaje como un número de punto flotante que representa los segundos desde la época.

set_date(date)

Establece la fecha de entrega del mensaje en date, un número de punto flotante que representa los segundos desde la época.

get_info()

Retorna una cadena que contiene la «info» de un mensaje. Esto es útil para acceder y modificar la «info» que es experimental (es decir, no una lista de flags).

set_info(info)

Establece «info» en info, que debería ser una cadena.

Cuando se crea una instancia MaildirMessage basada en una instancia mboxMessage o MMDFMessage, se omiten las cabeceras Status y X-Status y se producen las siguientes conversiones:

Estado resultante

Estado mboxMessage o MMDFMessage

subdirectorio «cur»

flag O

flag F

flag F

flag R

flag A

flag S

flag R

flag T

flag D

Cuando se crea una instancia MaildirMessage basada en una instancia MHMessage, se producen las siguientes conversiones:

Estado resultante

Estado MHMessage

subdirectorio «cur»

Secuencia «unseen» (no vista)

subdirectorio «cur» e indicador S

no hay una secuencia «unseen» (invisible)

flag F

secuencia «flagged» (marcada)

flag R

Secuencia «replied» (respondida)

Cuando se crea una instancia MaildirMessage basada en una instancia BabylMessage, se producen las siguientes conversiones:

Estado resultante

Estado BabylMessage

subdirectorio «cur»

etiqueta «unseen» (invisible)

subdirectorio «cur» e indicador S

no hay una etiqueta «unseen» (invisible)

flag P

etiqueta «forwarded» o «resent» (reenviado)

flag R

etiqueta de «answered» (contestado)

flag T

etiqueta «deleted» (borrado)

mboxMessage

class mailbox.mboxMessage(message=None)

Un mensaje con comportamientos específicos de mbox. El parámetro message tiene el mismo significado que con el constructor Message.

Los mensajes en un buzón de correo de mbox se almacenan juntos en un solo archivo. La dirección del sobre del remitente y la hora de entrega se almacenan normalmente en una línea que comienza con «From» que se utiliza para indicar el comienzo de un mensaje, aunque hay una variación considerable en el formato exacto de estos datos entre las implementaciones de mbox. Los flags del estado del mensaje, como por ejemplo si ha sido leído o marcado como importante, se almacenan típicamente en las cabeceras Status y X-Status.

Los flags convencionales para los mensajes de mbox son los siguientes:

Flag

Significado

Explicación

R

Leído

Leído

O

Antiguo

Anteriormente detectado por MUA

D

Borrado

Marcado para su posterior eliminación

F

Marcada

Marcado como importante

A

Respondido

Contestado a

Los flags «R» y «O» se almacenan en el encabezado Status y los flags «D», «F» y «A» se almacenan en el encabezado X-Status. Los flags y los encabezados aparecen típicamente en el orden mencionado.

Instancias de mboxMessage ofrecen los siguientes métodos:

get_from()

Retorna una cadena que representa la línea «From» que marca el inicio del mensaje en un buzón de correo de mbox. El «From» inicial y la nueva línea final están excluidas.

set_from(from_, time_=None)

Ponga la línea «From» en from_, que debe ser especificada sin una línea «From» o una nueva línea posterior. Para mayor comodidad, se puede especificar time_, que se formateará adecuadamente y se añadirá a from_. Si se especifica time_, debe ser una instancia time.struct_time, una tupla adecuada para pasar a time.strftime(), o True (para usar time.gmtime()).

get_flags()

Retorna una cadena que especifica los flags que están actualmente establecidos. Si el mensaje cumple con el formato convencional, el resultado es la concatenación en el siguiente orden de cero o una ocurrencia de cada uno de los flags “R”`, 'O', 'D', 'F', and 'A'.

set_flags(flags)

Establece los flags especificadas por flags y desactiva todos las demás. El parámetro flags debe ser la concatenación en cualquier orden de cero o más ocurrencias de cada uno de los flags 'R', 'O', 'D', 'F', and 'A'.

add_flag(flag)

Establece lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para añadir más de un indicador a la vez, flag puede ser una cadena de más de un carácter.

remove_flag(flag)

Deshabilita lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para quitar más de un indicador a la vez, flag puede ser una cadena de más de un carácter.

Cuando se crea una instancia mboxMessage basada en una instancia MaildirMessage, se genera una línea «From » basada en la fecha de entrega de la instancia MaildirMessage, y se realizan las siguientes conversiones:

Estado resultante

Estado de MaildirMessage

flag R

flag S

flag O

subdirectorio «cur»

flag D

flag T

flag F

flag F

flag A

flag R

Cuando se crea una instancia mboxMessage basada en una instancia MHMessage, se producen las siguientes conversiones:

Estado resultante

Estado MHMessage

flag R y flag O

no hay una secuencia «unseen» (invisible)

flag O

Secuencia «unseen» (no vista)

flag F

secuencia «flagged» (marcada)

flag A

Secuencia «replied» (respondida)

Cuando se crea una instancia mboxMessage basada en una instancia BabylMessage, se producen las siguientes conversiones:

Estado resultante

Estado BabylMessage

flag R y flag O

no hay una etiqueta «unseen» (invisible)

flag O

etiqueta «unseen» (invisible)

flag D

etiqueta «deleted» (borrado)

flag A

etiqueta de «answered» (contestado)

Cuando se crea una instancia Message basada en una instancia MMDFMessage, la línea «From» se copia y todas los flags se corresponden directamente:

Estado resultante

Estado de MMDFMessage

flag R

flag R

flag O

flag O

flag D

flag D

flag F

flag F

flag A

flag A

MHMessage

class mailbox.MHMessage(message=None)

Un mensaje con comportamientos específicos de la HM. El parámetro message tiene el mismo significado que con el constructor Message.

Los mensajes de MH no soportan marcas o flags en el sentido tradicional, pero sí secuencias, que son agrupaciones lógicas de mensajes arbitrarios. Algunos programas de lectura de correo (aunque no los estándares mh y nmh) usan secuencias de manera muy similar a los flags que se usan con otros formatos, como sigue:

Secuencia

Explicación

unseen (no visto)

No leído, pero previamente detectado por la MUA

replied (contestado)

Contestado a

flagged (marcado)

Marcado como importante

Instancias de MHMessage ofrecen los siguientes métodos:

get_sequences()

Retorna una lista de los nombres de las secuencias que incluyen este mensaje.

set_sequences(sequences)

Establece la lista de secuencias que incluyen este mensaje.

add_sequence(sequence)

Añade sequence a la lista de secuencias que incluyen este mensaje.

remove_sequence(sequence)

Elimina sequence de la lista de secuencias que incluyen este mensaje.

Cuando se crea una instancia MHMessage basada en una instancia MaildirMessage, se producen las siguientes conversiones:

Estado resultante

Estado de MaildirMessage

Secuencia «unseen» (no vista)

no hay indicador S

Secuencia «replied» (respondida)

flag R

secuencia «flagged» (marcada)

flag F

Cuando se crea una instancia MHMessage basada en una instancia mboxMessage o MMDFMessage, se omiten las cabeceras Status y X-Status y se producen las siguientes conversiones:

Estado resultante

Estado mboxMessage o MMDFMessage

Secuencia «unseen» (no vista)

sin indicador R

Secuencia «replied» (respondida)

flag A

secuencia «flagged» (marcada)

flag F

Cuando se crea una instancia MHMessage basada en una instancia BabylMessage, se producen las siguientes conversiones:

Estado resultante

Estado BabylMessage

Secuencia «unseen» (no vista)

etiqueta «unseen» (invisible)

Secuencia «replied» (respondida)

etiqueta de «answered» (contestado)

BabylMessage

class mailbox.BabylMessage(message=None)

Un mensaje con comportamientos específicos de Babyl. El parámetro message tiene el mismo significado que con el constructor Message.

Ciertas etiquetas de mensajes, llamadas attributes, están definidas por convención para tener significados especiales. Los atributos son los siguientes:

Etiqueta

Explicación

unseen (no visto)

No leído, pero previamente detectado por la MUA

deleted (borrado)

Marcado para su posterior eliminación

filed (archivado)

Copiado a otro archivo o buzón de correo

answered (contestado)

Contestado a

forwarded (reenviado)

Reenviado

edited (editado)

Modificado por el usuario

resent (reenviado)

Reenviado

De forma predeterminada, Rmail sólo muestra las cabeceras visibles. La clase BabylMessage, sin embargo, usa los encabezados originales porque son más completos. Se puede acceder a las cabeceras visibles explícitamente si se desea.

Instancias de BabylMessage ofrecen los siguientes métodos:

get_labels()

Retorna una lista de etiquetas en el mensaje.

set_labels(labels)

Establece la lista de etiquetas del mensaje en labels.

add_label(label)

Añade label a la lista de etiquetas del mensaje.

remove_label(label)

Eliminar label de la lista de etiquetas del mensaje.

get_visible()

Retorna una instancia de Message cuyos encabezados son los encabezados visibles del mensaje y cuyo cuerpo está vacío.

set_visible(visible)

Establece los encabezados visibles del mensaje para que sean los mismos que los del message. El parámetro visible debe ser una instancia Message, una instancia email.message.Message, una cadena, o un objeto tipo archivo (que debe estar abierto en modo texto).

update_visible()

Cuando se modifican los encabezados originales de una instancia BabylMessage, los encabezados visibles no se modifican automáticamente para que se correspondan. Este método actualiza los encabezados visibles de la siguiente manera: cada encabezado visible con un encabezado original correspondiente se establece como el valor del encabezado original, cada encabezado visible sin un encabezado original correspondiente se elimina, y cualquiera de Date, From, Reply-To, To, CC, y Subject que están presentes en las cabeceras originales pero no las cabeceras visibles se añaden a las cabeceras visibles.

Cuando se crea una instancia BabylMessage basada en una instancia MaildirMessage, se producen las siguientes conversiones:

Estado resultante

Estado de MaildirMessage

etiqueta «unseen» (invisible)

no hay indicador S

etiqueta «deleted» (borrado)

flag T

etiqueta de «answered» (contestado)

flag R

etiqueta «forwarded» (reenviado)

flag P

Cuando se crea una instancia BabylMessage basada en una instancia mboxMessage o MMDFMessage, se omiten los encabezados Status y X-Status y se producen las siguientes conversiones:

Estado resultante

Estado mboxMessage o MMDFMessage

etiqueta «unseen» (invisible)

sin indicador R

etiqueta «deleted» (borrado)

flag D

etiqueta de «answered» (contestado)

flag A

Cuando se crea una instancia BabylMessage basada en una instancia MHMessage, se producen las siguientes conversiones:

Estado resultante

Estado MHMessage

etiqueta «unseen» (invisible)

Secuencia «unseen» (no vista)

etiqueta de «answered» (contestado)

Secuencia «replied» (respondida)

MMDFMessage

class mailbox.MMDFMessage(message=None)

Un mensaje con comportamientos específicos de MMDF. El parámetro message tiene el mismo significado que con el constructor Message.

Al igual que los mensajes en un buzón de correo de mbox, los mensajes MMDF se almacenan con la dirección del remitente y la fecha de entrega en una línea inicial que comienza con «From». De la misma manera, los flags que indican el estado del mensaje se almacenan típicamente en las cabeceras Status y X-Status.

Los flags convencionales para los mensajes MMDF son idénticos a las de los mensajes de mbox y son los siguientes:

Flag

Significado

Explicación

R

Leído

Leído

O

Antiguo

Anteriormente detectado por MUA

D

Borrado

Marcado para su posterior eliminación

F

Marcada

Marcado como importante

A

Respondido

Contestado a

Los flags «R» y «O» se almacenan en el encabezado Status y los flags «D», «F» y «A» se almacenan en el encabezado X-Status. Los flags y los encabezados aparecen típicamente en el orden mencionado.

Las instancias de MMDFMessage ofrecen los siguientes métodos, que son idénticos a los ofrecidos por mboxMessage:

get_from()

Retorna una cadena que representa la línea «From» que marca el inicio del mensaje en un buzón de correo de mbox. El «From» inicial y la nueva línea final están excluidas.

set_from(from_, time_=None)

Ponga la línea «From» en from_, que debe ser especificada sin una línea «From» o una nueva línea posterior. Para mayor comodidad, se puede especificar time_, que se formateará adecuadamente y se añadirá a from_. Si se especifica time_, debe ser una instancia time.struct_time, una tupla adecuada para pasar a time.strftime(), o True (para usar time.gmtime()).

get_flags()

Retorna una cadena que especifica los flags que están actualmente establecidos. Si el mensaje cumple con el formato convencional, el resultado es la concatenación en el siguiente orden de cero o una ocurrencia de cada uno de los flags “R”`, 'O', 'D', 'F', and 'A'.

set_flags(flags)

Establece los flags especificadas por flags y desactiva todos las demás. El parámetro flags debe ser la concatenación en cualquier orden de cero o más ocurrencias de cada uno de los flags 'R', 'O', 'D', 'F', and 'A'.

add_flag(flag)

Establece lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para añadir más de un indicador a la vez, flag puede ser una cadena de más de un carácter.

remove_flag(flag)

Deshabilita lo(s) flag(s) especificado(s) por flag sin cambiar otros flags. Para quitar más de un indicador a la vez, flag puede ser una cadena de más de un carácter.

Cuando se crea una instancia MMDFMessage basada en una instancia MaildirMessage, se genera una línea «From » basada en la fecha de entrega de la instancia MaildirMessage, y se realizan las siguientes conversiones:

Estado resultante

Estado de MaildirMessage

flag R

flag S

flag O

subdirectorio «cur»

flag D

flag T

flag F

flag F

flag A

flag R

Cuando se crea una instancia MMDFMessage basada en una instancia MHMessage, se producen las siguientes conversiones:

Estado resultante

Estado MHMessage

flag R y flag O

no hay una secuencia «unseen» (invisible)

flag O

Secuencia «unseen» (no vista)

flag F

secuencia «flagged» (marcada)

flag A

Secuencia «replied» (respondida)

Cuando se crea una instancia MMDFMessage basada en una instancia BabylMessage, se producen las siguientes conversiones:

Estado resultante

Estado BabylMessage

flag R y flag O

no hay una etiqueta «unseen» (invisible)

flag O

etiqueta «unseen» (invisible)

flag D

etiqueta «deleted» (borrado)

flag A

etiqueta de «answered» (contestado)

Cuando se crea una instancia MMDFMessage basada en una instancia mboxMessage, la línea «From » se copia y todos los flags se corresponden directamente:

Estado resultante

Estado de mboxMessage

flag R

flag R

flag O

flag O

flag D

flag D

flag F

flag F

flag A

flag A

Excepciones

Las siguientes clases de excepción están definidas en el módulo mailbox:

exception mailbox.Error

La clase base para todas las demás excepciones específicas del módulo.

exception mailbox.NoSuchMailboxError

Se lanza cuando se espera un buzón de correo pero no se encuentra, como cuando se instancia una subclase Mailbox con una ruta que no existe (y con el parámetro create establecido en False), o cuando se abre una carpeta que no existe.

exception mailbox.NotEmptyError

Se lanza cuando un buzón de correo no está vacío, pero se espera que lo esté, como cuando se elimina una carpeta que contiene mensajes.

exception mailbox.ExternalClashError

Se lanza cuando alguna condición relacionada con el buzón de correo, fuera del control del programa, hace que éste no pueda proceder, como por ejemplo cuando se falla en la adquisición de un bloqueo que es mantenido por otro programa, o cuando ya existe un nombre de archivo generado de forma única.

exception mailbox.FormatError

Se lanza cuando los datos de un archivo no pueden ser analizados, como cuando una instancia MH intenta leer un archivo .mh_sequences corrupto.

Ejemplos

Un simple ejemplo de impresión de los temas de todos los mensajes en un buzón de correo que parecen interesantes:

import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Could possibly be None.
    if subject and 'python' in subject.lower():
        print(subject)

Para copiar todo el correo de un buzón de Babyl a un buzón de MH, convirtiendo toda la información de formato específico que puede ser convertida:

import mailbox
destination = mailbox.MH('~/Mail')
destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
    destination.add(mailbox.MHMessage(message))
destination.flush()
destination.unlock()

Este ejemplo clasifica el correo de varias listas de correo en diferentes buzones, teniendo cuidado de evitar la corrupción del correo debido a la modificación simultánea por otros programas, la pérdida de correo debido a la interrupción del programa, o la terminación prematura debido a mensajes malformados en el buzón:

import mailbox
import email.errors

list_names = ('python-list', 'python-dev', 'python-bugs')

boxes = {name: mailbox.mbox('~/email/%s' % name) for name in list_names}
inbox = mailbox.Maildir('~/Maildir', factory=None)

for key in inbox.iterkeys():
    try:
        message = inbox[key]
    except email.errors.MessageParseError:
        continue                # The message is malformed. Just leave it.

    for name in list_names:
        list_id = message['list-id']
        if list_id and name in list_id:
            # Get mailbox to use
            box = boxes[name]

            # Write copy to disk before removing original.
            # If there's a crash, you might duplicate a message, but
            # that's better than losing a message completely.
            box.lock()
            box.add(message)
            box.flush()
            box.unlock()

            # Remove original message
            inbox.lock()
            inbox.discard(key)
            inbox.flush()
            inbox.unlock()
            break               # Found destination, so stop looking.

for box in boxes.itervalues():
    box.close()