include_spam_trash unused

rosstex commented 3 years ago

I see that include_spam_trash is unused. Since SPAM and TRASH are labels, I assume this means that they are included by default? How do you specify messages which do not match a label?

jeremyephron commented 3 years ago

@rosstex

I see that include_spam_trash is unused.

Yes! This is a bug you've identified. It has now been fixed in version 3.1.6. You can run python3 -m pip install --upgrade simplegmail to upgrade to the newest version, and you can run pip3 show simplegmail | grep "Version" to confirm that the version is 3.1.6. Setting include_spam_trash=True in the various convenience functions will include messages in the spam and trash folders in your search.

Since SPAM and TRASH are labels, I assume this means that they are included by default?

You are correct that they are technically labels, but they are actually processed a little differently by Gmail, so they are never included by default in searches. You can include them by specifying the SPAM or TRASH labels, or by setting include_spam_trash=True. Simplegmail also provides get_spam_messages and get_trash_messages for convenience.

How do you specify messages which do not match a label?

You can accomplish this through the provided query constructor (I am thinking about updating this interface in the future), or by constructing the query strings yourself. The query constructor is useful for programmatically creating queries, but for short and simple query strings, manual construction may be suitable. Here are examples of three scenarios to help you out:

1. Search unread inbox messages, excluding those with the 'finance' label

from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail()
query_str = construct_query(labels=['finance'], exclude_labels=True)
# equivalent to query_str = '-label:finance'
# can also write labels='finance' if using a single label
# exclude_KEYWORD says to negate KEYWORD, more info can be found in query.py
msgs = gmail.get_unread_inbox(query=query_str)

2. Search unread messages, excluding messages with both 'homework' and 'cs' labels

If a message has only 'homework' or only 'cs' (or neither), it will be included.

from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail()
query_str = construct_query(labels=['homework', 'cs'], exclude_labels=True)
# equivalent to query_str = '-(label:homework label:cs)'
msgs = gmail.get_unread_messages(query=query_str)

3. Search unread messages, excluding messages with either 'bills' or 'applications' labels

A message needs neither 'bills' nor 'applications' to be included.

from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail()
query_str = construct_query(labels=[['bills'], ['applications']], exclude_labels=True)
# equivalent to query_str = '-{label:bills label:applications}'
msgs = gmail.get_unread_messages(query=query_str)

Again, the construct_query function is explained in detail in query.py. I plan to add a whole bunch of examples like these to the wiki.

jeremyephron commented 3 years ago

In writing those examples for you, I realized there is a situation that isn't well handled, so I will likely update the construct_query interface very soon. Will update you when that is done.

jeremyephron commented 3 years ago

@rosstex The construct_query method has been changed to be more expressive in v4.0.0. Here are the same 3 scenarios updated plus one additional scenario:

1. Search unread inbox messages, excluding those with the 'finance' label

from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail()
query_str = construct_query(exclude_labels=['finance'])
# equivalent to query_str = '-label:finance'
# can also write exclude_labels='finance' if using a single label
msgs = gmail.get_unread_inbox(query=query_str)

2. Search unread messages, excluding messages with both 'homework' and 'cs' labels

If a message has only 'homework' or only 'cs' (or neither), it will be included.

from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail()
query_str = construct_query(exclude_labels=['homework', 'cs'])
# equivalent to query_str = '-(label:homework label:cs)'
msgs = gmail.get_unread_messages(query=query_str)

3. Search unread messages, excluding messages with either 'bills' or 'applications' labels

A message needs neither 'bills' nor 'applications' to be included.

from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail()
query_str = construct_query(exclude_labels=[['bills'], ['applications']])
# equivalent to query_str = '-{label:bills label:applications}'
msgs = gmail.get_unread_messages(query=query_str)

4. Search unread messages that have 'homework' but not 'cs'

from simplegmail import Gmail
from simplegmail.query import construct_query

gmail = Gmail()
query_str = construct_query(labels='homework', exclude_labels='cs')
# equivalent to query_str = '(label:homework -label:cs)'
msgs = gmail.get_unread_messages(query=query_str)

Hope this helps, let me know if you have questions.

rosstex commented 3 years ago

Thank you so much for your incredibly quick and helpful support! Don't mind me if I ask a few more questions meanwhile :)

jeremyephron / simplegmail