zevav
86cf1fbf9b
added `authentication_error_message` as a class attribute to `Imbox`. If `Imbox.vendor` is not None, look for a custom authentication error string, and raise it if there's a problem logging in. The default error value is raised if there is no custom string. created `name_authentication_string_dict` from all subclasses of `Messages` in `vendors/__init__.py`, for the lookup mentioned above. Implement architecture discussed in #131, deciding whether to use `Messages` or a subclass of it in `Imbox.messages` based on the `Imbox.vendor` value. Use the `folder_lookup` dict, present on `Messages` but only filled in on its subclasses, to select the right folder based on a lowercased "standard" name given as the value of `folder`. created a blank `folder_lookup` on `Messages`. filled in the first vendor that subclasses `Messages`, `GmailMessages`. It contains class attributes `authentication_error_message`, `hostname`, `name`, used for purposes described above, as well as `folder_lookup` which is a dict containing aliases, sometimes several, for Gmail's unique folder naming scheme. These aliases are meant to be "human-friendly" for intuitive `folder` selection in calls to `Imbox.messages`. fixes #131. prevent too much bookkeeping in vendors/__init__.py by adding each vendor.__name__ to __all__ from the vendors list.
Imbox - Python IMAP for Humans
==============================
.. image:: https://travis-ci.org/martinrusev/imbox.svg?branch=master
:target: https://travis-ci.org/martinrusev/imbox
:alt: Build Status
Python library for reading IMAP mailboxes and converting email content to machine readable data
Requirements
------------
Python (3.3, 3.4, 3.5, 3.6)
Installation
------------
``pip install imbox``
Usage
-----
.. code:: python
from imbox import Imbox
# SSL Context docs https://docs.python.org/3/library/ssl.html#ssl.create_default_context
with Imbox('imap.gmail.com',
username='username',
password='password',
ssl=True,
ssl_context=None,
starttls=False) as imbox:
# Get all folders
status, folders_with_additional_info = imbox.folders()
# Gets all messages from the inbox
all_inbox_messages = imbox.messages()
# Unread messages
unread_inbox_messages = imbox.messages(unread=True)
# Flagged messages
inbox_flagged_messages = imbox.messages(flagged=True)
# Un-flagged messages
inbox_unflagged_messages = imbox.messages(unflagged=True)
# Flagged messages
flagged_messages = imbox.messages(flagged=True)
# Un-flagged messages
unflagged_messages = imbox.messages(unflagged=True)
# Messages sent FROM
inbox_messages_from = imbox.messages(sent_from='sender@example.org')
# Messages sent TO
inbox_messages_to = imbox.messages(sent_to='receiver@example.org')
# Messages received before specific date
inbox_messages_received_before = imbox.messages(date__lt=datetime.date(2018, 7, 31))
# Messages received after specific date
inbox_messages_received_after = imbox.messages(date__gt=datetime.date(2018, 7, 30))
# Messages received on a specific date
inbox_messages_received_on_date = imbox.messages(date__on=datetime.date(2018, 7, 30))
# Messages whose subjects contain a string
inbox_messages_subject_christmas = imbox.messages(subject='Christmas')
# Messages from a specific folder
messages_in_folder_social = imbox.messages(folder='Social')
for uid, message in all_inbox_messages:
# Every message is an object with the following keys
message.sent_from
message.sent_to
message.subject
message.headers
message.message_id
message.date
message.body.plain
message.body.html
message.attachments
# To check all available keys
print(message.keys())
# To check the whole object, just write
print(message)
{
'headers':
[{
'Name': 'Received-SPF',
'Value': 'pass (google.com: domain of ......;'
},
{
'Name': 'MIME-Version',
'Value': '1.0'
}],
'body': {
'plain': ['ASCII'],
'html': ['HTML BODY']
},
'attachments': [{
'content': <StringIO.StringIO instance at 0x7f8e8445fa70>,
'filename': "avatar.png",
'content-type': 'image/png',
'size': 80264
}],
'date': u 'Fri, 26 Jul 2013 10:56:26 +0300',
'message_id': u '51F22BAA.1040606',
'sent_from': [{
'name': u 'Martin Rusev',
'email': 'martin@amon.cx'
}],
'sent_to': [{
'name': u 'John Doe',
'email': 'john@gmail.com'
}],
'subject': u 'Hello John, How are you today'
}
# With the message id, several actions on the message are available:
# delete the message
imbox.delete(uid)
# mark the message as read
imbox.mark_seen(uid)
Changelog
---------
`Changelog <https://github.com/martinrusev/imbox/blob/master/CHANGELOG.md>`_
Running the tests
-----------------
You can run the imbox tests with ``tox``.
Requirements:
* the supported python versions
* ``tox``. Tox is packaged in Debian and derivatives distributions.
On Ubuntu, you can install several python versions with:
.. code:: sh
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.X