"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   | Signific  | Explicación                      |
   |        | ado       |                                  |
   |========|===========|==================================|
   | D      | Borrador  | Bajo composición                 |
   +--------+-----------+----------------------------------+
   | F      | Marcada   | Marcado como importante          |
   +--------+-----------+----------------------------------+
   | P      | Aprobado  | Enviado, reenviado o rebotado    |
   +--------+-----------+----------------------------------+
   | R      | Contesta  | Contestado a                     |
   |        | do        |                                  |
   +--------+-----------+----------------------------------+
   | 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 | no hay una secuencia       |
| S                               | "*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 | no hay una etiqueta "*unseen*"  |
| S                               | (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   | Significa  | Explicación                      |
   |        | do         |                                  |
   |========|============|==================================|
   | 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 leído, pero previamente detectado por   |
   | (no visto) | la MUA                                     |
   +------------+--------------------------------------------+
   | *replied*  | Contestado a                               |
   | (contesta  |                                            |
   | do)        |                                            |
   +------------+--------------------------------------------+
   | *flagged*  | Marcado como importante                    |
   | (marcado)  |                                            |
   +------------+--------------------------------------------+

   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 hay indicador S              |
| (no vista)           |                                 |
+----------------------+---------------------------------+
| Secuencia            | flag R                          |
| "*replied*"          |                                 |
| (respondida)         |                                 |
+----------------------+---------------------------------+
| secuencia            | flag F                          |
| "*flagged*"          |                                 |
| (marcada)            |                                 |
+----------------------+---------------------------------+

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*" | sin indicador R                                |
| (no vista)           |                                                |
+----------------------+------------------------------------------------+
| Secuencia            | flag A                                         |
| "*replied*"          |                                                |
| (respondida)         |                                                |
+----------------------+------------------------------------------------+
| secuencia            | flag F                                         |
| "*flagged*"          |                                                |
| (marcada)            |                                                |
+----------------------+------------------------------------------------+

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

+----------------------+-------------------------------+
| Estado resultante    | Estado "BabylMessage"         |
|======================|===============================|
| Secuencia "*unseen*" | etiqueta "*unseen*"           |
| (no vista)           | (invisible)                   |
+----------------------+-------------------------------+
| Secuencia            | etiqueta de "*answered*"      |
| "*replied*"          | (contestado)                  |
| (respondida)         |                               |
+----------------------+-------------------------------+


"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 leído, pero previamente detectado por   |
   | (no visto)  | la MUA                                     |
   +-------------+--------------------------------------------+
   | *deleted*   | Marcado para su posterior eliminación      |
   | (borrado)   |                                            |
   +-------------+--------------------------------------------+
   | *filed*     | Copiado a otro archivo o buzón de correo   |
   | (archivado) |                                            |
   +-------------+--------------------------------------------+
   | *answered*  | Contestado a                               |
   | (contestad  |                                            |
   | o)          |                                            |
   +-------------+--------------------------------------------+
   | *forwarded* | Reenviado                                  |
   | (reenviado) |                                            |
   +-------------+--------------------------------------------+
   | *edited*    | Modificado por el usuario                  |
   | (editado)   |                                            |
   +-------------+--------------------------------------------+
   | *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*" | no hay indicador S              |
| (invisible)         |                                 |
+---------------------+---------------------------------+
| etiqueta "deleted"  | flag T                          |
| (borrado)           |                                 |
+---------------------+---------------------------------+
| etiqueta de         | flag R                          |
| "*answered*"        |                                 |
| (contestado)        |                                 |
+---------------------+---------------------------------+
| etiqueta            | flag P                          |
| "*forwarded*"       |                                 |
| (reenviado)         |                                 |
+---------------------+---------------------------------+

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           | sin indicador R                                |
| "*unseen*"         |                                                |
| (invisible)        |                                                |
+--------------------+------------------------------------------------+
| etiqueta "deleted" | flag D                                         |
| (borrado)          |                                                |
+--------------------+------------------------------------------------+
| etiqueta de        | flag A                                         |
| "*answered*"       |                                                |
| (contestado)       |                                                |
+--------------------+------------------------------------------------+

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

+--------------------+----------------------------+
| Estado resultante  | Estado "MHMessage"         |
|====================|============================|
| etiqueta           | Secuencia "*unseen*" (no   |
| "*unseen*"         | vista)                     |
| (invisible)        |                            |
+--------------------+----------------------------+
| etiqueta de        | Secuencia "*replied*"      |
| "*answered*"       | (respondida)               |
| (contestado)       |                            |
+--------------------+----------------------------+


"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   | Significa  | Explicación                      |
   |        | do         |                                  |
   |========|============|==================================|
   | 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()
