Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`mail`.`imap4`.`MessageSet``

class documentation

`class MessageSet: (source)`

View In Hierarchy

A set of message identifiers usable by both `IMAP4Client` and `IMAP4Server` via `IMailboxIMAP.store` and `IMailboxIMAP.fetch`.

These identifiers can be either message sequence numbers or unique identifiers. See Section 2.3.1, "Message Numbers", RFC 3501.

This represents the `sequence-set` described in Section 9, "Formal Syntax" of RFC 3501:

- A `MessageSet` can describe a single identifier, e.g. `MessageSet(1)`
- A `MessageSet` can describe `*` via `None`, e.g. `MessageSet(None)`
- A `MessageSet` can describe a range of identifiers, e.g. `MessageSet(1, 2)`. The range is inclusive and unordered (see `seq-range` in RFC 3501, Section 9), so that `Message(2, 1)` is equivalent to `MessageSet(1, 2)`, and both describe messages 1 and 2. Ranges can include `*` by specifying `None`, e.g. `MessageSet(None, 1)`. In all cases ranges are normalized so that the smallest identifier comes first, and `None` always comes last; `Message(2, 1)` becomes `MessageSet(1, 2)` and `MessageSet(None, 1)` becomes `MessageSet(1, None)`
- A `MessageSet` can describe a sequence of single identifiers and ranges, constructed by addition. `MessageSet(1) + MessageSet(5, 10)` refers the message identified by `1` and the messages identified by `5` through `10`.

NB: The meaning of * varies, but it always represents the largest number in use.

For servers: Your `IMailboxIMAP` provider must set `MessageSet.last` to the highest-valued identifier (unique or message sequence) before iterating over it.

For clients: `*` consumes ranges smaller than it, e.g. `MessageSet(1, 100) + MessageSet(50, None)` is equivalent to `1:*`.

Method | `__add__` | Undocumented
Method | `__contains__` | May raise TypeError if we encounter an open-ended range
Method | `__eq__` | Undocumented
Method | `__init__` | Create a new MessageSet()
Method | `__iter__` | Undocumented
Method | `__len__` | Undocumented
Method | `__repr__` | Undocumented
Method | `__str__` | Undocumented
Method | `add` | Add another range
Method | `clean` | Clean ranges list, combining adjacent ranges
Method | `extend` | Extend our messages with another message or set of messages.
Method | `last.setter` | Replaces all occurrences of "*". This should be the largest number in use. Must be set before attempting to use the MessageSet as a container.
Instance Variable | `getnext` | A function that returns the next message number, used when iterating through the `MessageSet`. By default, a function returning the next integer is supplied, but as this can be rather inefficient for sparse UID iterations, it is recommended to supply one when messages are requested by UID...
Instance Variable | `ranges` | Undocumented
Property | `last` | The largest number in use. This is undefined until it has been set by assigning to this property.
Method | `_iterator` | Undocumented
Method | `_noneInRanges` | Is there a `None` in our ranges?
Class Variable | `_empty` | Undocumented
Class Variable | `_infinity` | Undocumented
Instance Variable | `_last` | Undocumented

def __add__(self, other): (source)

Undocumented

def __contains__(self, value): (source)

May raise TypeError if we encounter an open-ended range

Parameters
value:`int` | Is this in our ranges?

def __eq__(self, other): (source)

Undocumented

Parameters
other:`object` | Undocumented
Returns
`bool` | Undocumented

def __init__(self, start=_empty, end=_empty): (source)

Create a new MessageSet()

Parameters
start:Optional `int` | Start of range, or only message number
end:Optional `int` | End of range.

def __iter__(self): (source)

Undocumented

def __len__(self): (source)

Undocumented

def __repr__(self): (source)

Undocumented

Returns
`str` | Undocumented

def __str__(self): (source)

Undocumented

Returns
`str` | Undocumented

def add(self, start, end=_empty): (source)

Add another range

Parameters
start:`int` | Start of range, or only message number
end:Optional `int` | End of range.

def clean(self): (source)

Clean ranges list, combining adjacent ranges

def extend(self, other): (source)

Extend our messages with another message or set of messages.

Parameters
other:`MessageSet`, `tuple` of two `int`s, or a single `int` | The messages to include.

@last.setter
def last(self, value): (source)

Replaces all occurrences of "*". This should be the largest number in use. Must be set before attempting to use the MessageSet as a container.

Raises
`ValueError` | if a largest value has already been set.

getnext: Function taking `int` returning `int` = (source)

A function that returns the next message number, used when iterating through the `MessageSet`. By default, a function returning the next integer is supplied, but as this can be rather inefficient for sparse UID iterations, it is recommended to supply one when messages are requested by UID. The argument is provided as a hint to the implementation and may be ignored if it makes sense to do so (eg, if an iterator is being used that maintains its own state, it is guaranteed that it will not be called out-of-order).

ranges = (source)

Undocumented

@property
last = (source)

The largest number in use. This is undefined until it has been set by assigning to this property.

def _iterator(self): (source)

Undocumented

def _noneInRanges(self): (source)

Is there a `None` in our ranges?

`MessageSet.clean` merges overlapping or consecutive ranges. None is represents a value larger than any number. There are thus two cases:

1. `(x, *) + (y, z)` such that `x` is smaller than `y`
2. `(z, *) + (x, y)` such that `z` is larger than `y`

(Other cases, such as `y < x < z`, can be split into these two cases; for example `(y - 1, y)` + `(x, x) + (z, z + 1)`)

In case 1, `* > y` and `* > z`, so `(x, *) + (y, z) = (x, *)`

In case 2, `z > x and z > y`, so the intervals do not merge, and the ranges are sorted as `[(x, y), (z, *)]`. `*` is represented as `(*, *)`, so this is the same as 2. but with a `z` that is greater than everything.

The result is that there is a maximum of two `None`s, and one of them has to be the high element in the last tuple in `self.ranges`. That means checking if `self.ranges[-1][-1]` is `None` suffices to check if any element is `None`.

Returns
`True` if `None` is in some range in ranges and `False` if otherwise.

_empty: `List[Any]` = (source)

Undocumented

_infinity = (source)

Undocumented

_last = (source)

Undocumented