Internet Data Handling » mailbox

[Ben Finney]

Adam Jensen <hanzer at riseup.net> writes:

> import mailbox
> for message in mailbox.mbox('~/mbox'):
>     subject = message['subject']       # Could possibly be None.
>     if subject and 'python' in subject.lower():
>         print subject
>
> What is the structure of "message"?

You're binding that name to each item from the collection returned from
‘mailbox.mbox’. So, let's look at the documentation for that function:

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

    A subclass of ``Mailbox`` for mailboxes in mbox format. Parameter
    `factory` is a callable object that accepts a file-like message
    representation (which behaves as if opened in binary mode) and
    returns a custom representation. If `factory` is ``None``,
    ``mboxMessage`` is used as the default message representation. […]

    <URL:https://docs.python.org/2.7/library/mailbox.html#mailbox.mbox>

So the above usage doesn't specify a `factory` to create instances,
which means the instances will be instances of ``mboxMessage`` type.

> I guess it's a dictionary but what is its structure? What are the
> keys? Is the structure constant or does it change depending upon the
> content of the mbox?

>From the same documentation you can follow the link to the documentation
for ``mailbox.mboxMessage``. There you'll find it inherits from
``mailbox.Message``, which itself inherits ``email.message.Message``.

So each instance you're getting has (a superset of) the API of
``email.message.Message``, which is a lot of behaviour
<URL:https://docs.python.org/2.7/library/email.message.html#email.message.Message>
including being able to interrogate the message header for its fields,
by name, using the get-an-item ‘foo[bar]’ syntax.

(The message has exactly one header, the header has multiple fields. The
documentation and API erroneously refer to those fields as “headers”,
but that is a common confusion to a lot of software and the Python
standard library makes it too.)

> I'm a bit new to python documentation. How would a potential user of the
> "mailbox" library determine these things? Or did I miss something?

The library reference documentation must assume you at least know the
Python language, including that collections contain items, those items
are each objects, every object has a type, the types inherit in a tree,
etc.

So you'd need to read the in the knowledge that a return value's
behaviour is determined by its type, and that the behaviour of a type is
determined by other behaviour it inherits, etc.

-- 
 \      “Some forms of reality are so horrible we refuse to face them, |
  `\     unless we are trapped into it by comedy. To label any subject |
_o__)        unsuitable for comedy is to admit defeat.” —Peter Sellers |
Ben Finney