pymap.search

Utilities for managing IMAP searches.

class pymap.search.SearchParams(selected, *, disabled=None)[source]

Defines certain parameters and routines necessary to process any kind of search criteria. If a parameter is not supplied, or a method not implemented, any search keys that require it will fail.

Parameters:

  • selected (SelectedMailbox) – The active mailbox session.

  • max_seq – The highest message sequence ID in the mailbox.

  • max_uid – The highest message UID in the mailbox.

  • disabled (Iterable[bytes] | None) – Search keys that should be disabled.

class pymap.search.SearchCriteria(params)[source]

Base class for different types of search criteria.

Parameters:

params (SearchParams) – The parameters that may be used by some searches.

abstract matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

classmethod of(key, params)[source]

Factory method for producing a search criteria sub-class from a search key.

Parameters:

  • key (SearchKey) – The search key defining the criteria.

  • params (SearchParams) – The parameters that may be used by some searches.

Return type:

SearchCriteria

class pymap.search.SearchCriteriaSet(keys, params)[source]

Search criteria composed of a set of search criteria that must all match. If the set is empty, nothing will match.

Parameters:

  • keys (Iterable[SearchKey]) – The set of search keys that must match.

  • params (SearchParams) – The parameters that may be used by some searches.

property sequence_set: SequenceSet

The sequence set to use when finding the messages to match against. This will default to all messages unless the search criteria set contains a sequence set.

matches(msg_seq, msg, loaded_msg)[source]

The message matches if all the defined search key criteria match.

Parameters:
Return type:

bool

class pymap.search.InverseSearchCriteria(key, params)[source]

Matches only if the given search criteria does not match.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.AllSearchCriteria(params)[source]

Always matches anything.

Parameters:

params (SearchParams)

matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.OrSearchCriteria(left, right, params)[source]

Matches if either of the search criteria match.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.SequenceSetSearchCriteria(seq_set, params)[source]

Matches if the message is contained in the sequence set.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.HasEmailIdSearchCriteria(email_id, params)[source]

Matches if the message has the same email_id value.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.HasThreadIdSearchCriteria(thread_id, params)[source]

Matches if the message has the same thread_id value.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.HasFlagSearchCriteria(flag, expected, params)[source]

Matches if the message has the given flag in their permanent or session flag sets.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.NewSearchCriteria(params)[source]

Matches if the message is considered “new”, i.e. recent and unseen.

Parameters:

params (SearchParams)

matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.DateSearchCriteria(when, op, params)[source]

Matches by comparing against the internal date of the message.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.HeaderDateSearchCriteria(when, op, params)[source]

Matches by comparing against the Date: header of the message.

Parameters:
class pymap.search.SizeSearchCriteria(size, op, params)[source]

Matches by comparing against the size of the message.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.EnvelopeSearchCriteria(key, value, params)[source]

Matches by checking for strings within various fields of the envelope structure.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.HeaderSearchCriteria(name, value, params)[source]

Matches if the message has a header containing a value.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool

class pymap.search.BodySearchCriteria(value, params)[source]

Matches if the message body contains a value.

Parameters:
matches(msg_seq, msg, loaded_msg)[source]

Implemented by sub-classes to define the search criteria.

Parameters:
Return type:

bool