Go to the latest version of this document.

# ``twisted`.`mail`.`imap4`.`IMAP4Client``

class documentation

`class IMAP4Client(basic.LineReceiver, policies.TimeoutMixin): (source)`

Constructor: `IMAP4Client(contextFactory)`

Implements interfaces: `twisted.mail.interfaces.IMailboxIMAPListener`

View In Hierarchy

IMAP4 client protocol implementation

Method | `__init__` | Undocumented
Method | `addFlags` | Add to the set flags for one or more messages.
Method | `append` | Add the given message to the given mailbox.
Method | `authenticate` | Attempt to enter the authenticated state with the server
Method | `check` | Tell the server to perform a checkpoint
Method | `close` | Return the connection to the Authenticated state.
Method | `connectionLost` | We are no longer connected
Method | `connectionMade` | Called when a connection is made.
Method | `copy` | Copy the specified messages to the specified mailbox.
Method | `create` | Create a new mailbox on the server
Method | `delete` | Delete a mailbox
Method | `dispatchCommand` | Undocumented
Method | `examine` | Select a mailbox in read-only mode
Method | `expunge` | Return the connection to the Authenticate state.
Method | `fetchAll` | Retrieve several different fields of one or more messages
Method | `fetchBody` | Retrieve body text of one or more messages
Method | `fetchBodyStructure` | Retrieve the structure of the body of one or more messages
Method | `fetchEnvelope` | Retrieve the envelope data for one or more messages
Method | `fetchFast` | Retrieve several different fields of one or more messages
Method | `fetchFlags` | Retrieve the flags for one or more messages
Method | `fetchFull` | Retrieve several different fields of one or more messages
Method | `fetchHeaders` | Retrieve headers of one or more messages
Method | `fetchInternalDate` | Retrieve the internal date associated with one or more messages
Method | `fetchMessage` | Retrieve one or more entire messages
Method | `fetchSimplifiedBody` | Retrieve the simplified body structure of one or more messages
Method | `fetchSize` | Retrieve the size, in octets, of one or more messages
Method | `fetchSpecific` | Retrieve a specific section of one or more messages
Method | `fetchUID` | Retrieve the unique identifier for one or more messages
Method | `flagsChanged` | Override me
Method | `getCapabilities` | Request the capabilities available on this server.
Method | `lineReceived` | Attempt to parse a single line from the server.
Method | `list` | List a subset of the available mailboxes
Method | `login` | Authenticate with the server using a username and password
Method | `logout` | Inform the server that we are done with the connection.
Method | `lsub` | List a subset of the subscribed available mailboxes
Method | `makeTag` | Undocumented
Method | `messageFile` | Create a file to which an incoming message may be written.
Method | `modeChanged` | Override me
Method | `namespace` | Retrieve information about the namespaces available to this account
Method | `newMessages` | Override me
Method | `noop` | Perform no operation.
Method | `rawDataReceived` | Override this for when raw data is received.
Method | `registerAuthenticator` | Register a new form of authentication
Method | `removeFlags` | Remove from the set flags for one or more messages.
Method | `rename` | Rename a mailbox
Method | `response_AUTH` | Undocumented
Method | `response_UNAUTH` | Undocumented
Method | `search` | Search messages in the currently selected mailbox
Method | `select` | Select a mailbox
Method | `sendCommand` | Undocumented
Method | `serverGreeting` | Called when the server has sent us a greeting.
Method | `setFlags` | Set the flags for one or more messages.
Method | `startTLS` | Initiates a 'STARTTLS' request and negotiates the TLS / SSL Handshake.
Method | `status` | Retrieve the status of the given mailbox
Method | `subscribe` | Add a mailbox to the subscription list
Method | `timeoutConnection` | Called when the connection times out.
Method | `unsubscribe` | Remove a mailbox from the subscription list
Constant | `STATUS_CODES` | Undocumented
Constant | `STATUS_TRANSFORMATIONS` | Undocumented
Class Variable | `tagID` | Undocumented
Class Variable | `timeout` | Undocumented
Instance Variable | `authenticators` | Undocumented
Instance Variable | `context` | Undocumented
Instance Variable | `queued` | Undocumented
Instance Variable | `startedTLS` | Undocumented
Instance Variable | `state` | A string representing the state the connection is currently in.
Instance Variable | `tags` | Undocumented
Instance Variable | `waiting` | Undocumented
Method | `__cbAuthenticate` | Undocumented
Method | `__cbAuthTLS` | Undocumented
Method | `__cbCapabilities` | Undocumented
Method | `__cbContinueAppend` | Undocumented
Method | `__cbContinueAuth` | Undocumented
Method | `__cbExpunge` | Undocumented
Method | `__cbFinishAppend` | Undocumented
Method | `__cbList` | Undocumented
Method | `__cbLoginCaps` | Undocumented
Method | `__cbLoginTLS` | Undocumented
Method | `__cbLogout` | Undocumented
Method | `__cbNamespace` | Undocumented
Method | `__cbNoop` | Undocumented
Method | `__cbSearch` | Undocumented
Method | `__cbSelect` | Handle lines received in response to a SELECT or EXAMINE command.
Method | `__cbStatus` | Undocumented
Method | `__ebLoginTLS` | Undocumented
Method | `_cbFetch` | Undocumented
Method | `_defaultHandler` | Undocumented
Method | `_extraInfo` | Undocumented
Method | `_fetch` | Undocumented
Method | `_flushQueue` | Undocumented
Method | `_getContextFactory` | Undocumented
Method | `_intOrRaise` | Parse `value` as an integer and return the result or raise `IllegalServerResponse` with `phrase` as an argument if `value` cannot be parsed as an integer.
Method | `_parseFetchPairs` | Given the result of parsing a single FETCH response, construct a `dict` mapping response keys to response values.
Method | `_regularDispatch` | Undocumented
Method | `_setupForLiteral` | Undocumented
Method | `_startedTLS` | Undocumented
Method | `_store` | Undocumented
Class Variable | `_memoryFileLimit` | Undocumented
Class Variable | `_statusNames` | Undocumented
Instance Variable | `_capCache` | Undocumented
Instance Variable | `_lastCmd` | Undocumented
Instance Variable | `_parts` | Undocumented
Instance Variable | `_pendingBuffer` | Undocumented
Instance Variable | `_pendingSize` | Undocumented
Instance Variable | `_tag` | Undocumented

Inherited from `LineReceiver`:

Method | `clearLineBuffer` | Clear buffered data.
Method | `dataReceived` | Protocol.dataReceived. Translates bytes into lines, and calls lineReceived (or rawDataReceived, depending on mode.)
Method | `lineLengthExceeded` | Called when the maximum line length has been reached. Override if it needs to be dealt with in some special way.
Method | `sendLine` | Sends a line to the other end of the connection.
Method | `setLineMode` | Sets the line-mode of this receiver.
Method | `setRawMode` | Sets the raw mode of this receiver. Further data received will be sent to rawDataReceived rather than lineReceived.
Constant | `MAX_LENGTH` | The maximum length of a line to allow (If a sent line is longer than this, the connection is dropped). Default is 16384.
Class Variable | `delimiter` | The line-ending delimiter to use. By default this is `b'\r\n'`.
Instance Variable | `line_mode` | Undocumented
Instance Variable | `_buffer` | Undocumented
Instance Variable | `_busyReceiving` | Undocumented

Inherited from `Protocol` (via `LineReceiver`):

Method | `logPrefix` | Return a prefix matching the class name, to identify log messages related to this protocol instance.
Class Variable | `factory` | Undocumented

Inherited from `BaseProtocol` (via `LineReceiver`, `Protocol`):

Method | `makeConnection` | Make a connection to a transport and a server.
Instance Variable | `connected` | Undocumented
Instance Variable | `transport` | Undocumented

Inherited from `_PauseableMixin` (via `LineReceiver`, `Protocol`, `BaseProtocol`):

Method | `pauseProducing` | Undocumented
Method | `resumeProducing` | Undocumented
Method | `stopProducing` | Undocumented
Instance Variable | `paused` | Undocumented

Inherited from `TimeoutMixin` (via `LineReceiver`, `Protocol`, `BaseProtocol`, `_PauseableMixin`):

Method | `callLater` | Wrapper around `reactor.callLater` for test purpose.
Method | `resetTimeout` | Reset the timeout count down.
Method | `setTimeout` | Change the timeout period
Instance Variable | `timeOut` | The number of seconds after which to timeout the connection.
Method | `__timedOut` | Undocumented
Instance Variable | `__timeoutCall` | Undocumented

def __init__(self, contextFactory=None): (source)

Undocumented

def addFlags(self, messages, flags, silent=1, uid=0): (source)

Add to the set flags for one or more messages.

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
flags:Any iterable of `str` | The flags to set
silent:`bool` | If true, cause the server to suppress its verbose response.
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a list of the server's responses (`[]` if `silent` is true) or whose errback is invoked if there is an error.

def append(self, mailbox, message, flags=(), date=None): (source)

Add the given message to the given mailbox.

This command is allowed in the Authenticated and Selected states.

Parameters
mailbox:`str` | The mailbox to which to add this message.
message:Any file-like object opened in binary mode. | The message to add, in RFC822 format. Newlines in this file should be \r\n-style.
flags:Any iterable of `str` | The flags to associated with this message.
date:`str` | The date to associate with this message. This should be of the format DD-MM-YYYY HH:MM:SS +/-HHMM. For example, in Eastern Standard Time, on July 1st 2004 at half past 1 PM, "01-07-2004 13:30:00 -0500".

Returns
`Deferred` | A deferred whose callback is invoked when this command succeeds or whose errback is invoked if it fails.

def authenticate(self, secret): (source)

Attempt to enter the authenticated state with the server

This command is allowed in the Non-Authenticated state.

Returns
`Deferred` | A deferred whose callback is invoked if the authentication succeeds and whose errback will be invoked otherwise.

def check(self): (source)

Tell the server to perform a checkpoint

This command is allowed in the Selected state.

Returns
`Deferred` | A deferred whose callback is invoked when this command succeeds or whose errback is invoked if it fails.

def close(self): (source)

Return the connection to the Authenticated state.

This command is allowed in the Selected state.

Issuing this command will also remove all messages flagged \Deleted from the selected mailbox if it is opened in read-write mode, otherwise it indicates success by no messages are removed.

Returns
`Deferred` | A deferred whose callback is invoked when the command completes successfully or whose errback is invoked if it fails.

def connectionLost(self, reason): (source)
from `twisted.internet.interfaces.IProtocol`
overrides `twisted.internet.protocol.Protocol.connectionLost`

We are no longer connected

def connectionMade(self): (source)
from `twisted.internet.interfaces.IProtocol`
overrides `twisted.internet.protocol.BaseProtocol.connectionMade`

Called when a connection is made.

This may be considered the initializer of the protocol, because it is called when the connection is completed. For clients, this is called once the connection to the server has been established; for servers, this is called after an accept() call stops blocking and a socket has been received. If you need to send any greeting or initial message, do it here.

def copy(self, messages, mailbox, uid): (source)

Copy the specified messages to the specified mailbox.

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
mailbox:`str` | The mailbox to which to copy the messages
uid:`bool` | If true, the `messages` refers to message UIDs, rather than message sequence numbers.

Returns
`Deferred` | A deferred whose callback is invoked with a true value when the copy is successful, or whose errback is invoked if there is an error.

def create(self, name): (source)

Create a new mailbox on the server

This command is allowed in the Authenticated and Selected states.

Parameters
name:`str` | The name of the mailbox to create.

Returns
`Deferred` | A deferred whose callback is invoked if the mailbox creation is successful and whose errback is invoked otherwise.

def delete(self, name): (source)

Delete a mailbox

This command is allowed in the Authenticated and Selected states.

Parameters
name:`str` | The name of the mailbox to delete.

Returns
`Deferred` | A deferred whose calblack is invoked if the mailbox is deleted successfully and whose errback is invoked otherwise.

def dispatchCommand(self, tag, rest): (source)

Undocumented

def examine(self, mailbox): (source)

Select a mailbox in read-only mode

This command is allowed in the Authenticated and Selected states.

Parameters
mailbox:`str` | The name of the mailbox to examine

Returns

`Deferred`

A deferred whose callback is invoked with mailbox information if the examine is successful and whose errback is invoked otherwise. Mailbox information consists of a dictionary with the following keys and values:

        'FLAGS': A list of strings containing the flags settable on
                    messages in this mailbox.

        'EXISTS': An integer indicating the number of messages in this
                    mailbox.

        'RECENT': An integer indicating the number of "recent"
                    messages in this mailbox.

        'UNSEEN': An integer indicating the number of messages not
                    flagged \Seen in this mailbox.

        'PERMANENTFLAGS': A list of strings containing the flags that
                    can be permanently set on messages in this mailbox.

        'UIDVALIDITY': An integer uniquely identifying this mailbox.

def expunge(self): (source)

Return the connection to the Authenticate state.

This command is allowed in the Selected state.

Issuing this command will perform the same actions as issuing the close command, but will also generate an 'expunge' response for every message deleted.

Returns
`Deferred` | A deferred whose callback is invoked with a list of the 'expunge' responses when this command is successful or whose errback is invoked otherwise.

def fetchAll(self, messages, uid=0): (source)

Retrieve several different fields of one or more messages

This command is allowed in the Selected state. This is equivalent to issuing all of the `fetchFlags`, `fetchInternalDate`, `fetchSize`, and `fetchEnvelope` functions.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to dict of the retrieved data values, or whose errback is invoked if there is an error. They dictionary keys are "flags", "date", "size", and "envelope".

def fetchBody(self, messages, uid=0): (source)

Retrieve body text of one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to file-like objects containing body text, or whose errback is invoked if there is an error.

def fetchBodyStructure(self, messages, uid=0): (source)

Retrieve the structure of the body of one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | The messages for which to retrieve body structure data.
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns

`Deferred`

A deferred whose callback is invoked with a dict mapping message numbers to body structure data, or whose errback is invoked if there is an error. Body structure data describes the MIME-IMB format of a message and consists of a sequence of mime type, mime subtype, parameters, content id, description, encoding, and size. The fields following the size field are variable: if the mime type/subtype is message/rfc822, the contained message's envelope information, body structure data, and number of lines of text; if the mime type is text, the number of lines of text. Extension fields may also be included; if present, they are: the MD5 hash of the body, body disposition, body language.

def fetchEnvelope(self, messages, uid=0): (source)

Retrieve the envelope data for one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | The messages for which to retrieve envelope data.
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns

`Deferred`

A deferred whose callback is invoked with a dict mapping message numbers to envelope data, or whose errback is invoked if there is an error. Envelope data consists of a sequence of the date, subject, from, sender, reply-to, to, cc, bcc, in-reply-to, and message-id header fields. The date, subject, in-reply-to, and message-id fields are `str`, while the from, sender, reply-to, to, cc, and bcc fields contain address data as `str`s. Address data consists of a sequence of name, source route, mailbox name, and hostname. Fields which are not present for a particular address may be `None`.

def fetchFast(self, messages, uid=0): (source)

Retrieve several different fields of one or more messages

This command is allowed in the Selected state. This is equivalent to issuing all of the `fetchFlags`, `fetchInternalDate`, and `fetchSize` functions.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to dict of the retrieved data values, or whose errback is invoked if there is an error. They dictionary keys are "flags", "date", and "size".

def fetchFlags(self, messages, uid=0): (source)

Retrieve the flags for one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | The messages for which to retrieve flags.
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to lists of flags, or whose errback is invoked if there is an error.

def fetchFull(self, messages, uid=0): (source)

Retrieve several different fields of one or more messages

This command is allowed in the Selected state. This is equivalent to issuing all of the `fetchFlags`, `fetchInternalDate`, `fetchSize`, `fetchEnvelope`, and `fetchSimplifiedBody` functions.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to dict of the retrieved data values, or whose errback is invoked if there is an error. They dictionary keys are "flags", "date", "size", "envelope", and "body".

def fetchHeaders(self, messages, uid=0): (source)

Retrieve headers of one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to dicts of message headers, or whose errback is invoked if there is an error.

def fetchInternalDate(self, messages, uid=0): (source)

Retrieve the internal date associated with one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | The messages for which to retrieve the internal date.
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to date strings, or whose errback is invoked if there is an error. Date strings take the format of "day-month-year time timezone".

def fetchMessage(self, messages, uid=0): (source)

Retrieve one or more entire messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A `Deferred` which will fire with a `dict` mapping message sequence numbers to `dict`s giving message data for the corresponding message. If `uid` is true, the inner dictionaries have a `'UID'` key mapped to a `str` giving the UID for the message. The text of the message is a `str` associated with the `'RFC822'` key in each dictionary.

def fetchSimplifiedBody(self, messages, uid=0): (source)

Retrieve the simplified body structure of one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to body data, or whose errback is invoked if there is an error. The simplified body structure is the same as the body structure, except that extension fields will never be present.

def fetchSize(self, messages, uid=0): (source)

Retrieve the size, in octets, of one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message numbers to sizes, or whose errback is invoked if there is an error.

def fetchSpecific(self, messages, uid=0, headerType=None, headerNumber=None, headerArgs=None, peek=None, offset=None, length=None): (source)

Retrieve a specific section of one or more messages

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.
headerType:`str` | If specified, must be one of HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, MIME, or TEXT, and will determine which part of the message is retrieved. For HEADER.FIELDS and HEADER.FIELDS.NOT, `headerArgs` must be a sequence of header names. For MIME, `headerNumber` must be specified.
headerNumber:`int` or `int` sequence | The nested rfc822 index specifying the entity to retrieve. For example, `1` retrieves the first entity of the message, and `(2, 1, 3`) retrieves the 3rd entity inside the first entity inside the second entity of the message.
headerArgs:A sequence of `str` | If `headerType` is HEADER.FIELDS, these are the headers to retrieve. If it is HEADER.FIELDS.NOT, these are the headers to exclude from retrieval.
peek:`bool` | If true, cause the server to not set the \Seen flag on this message as a result of this command.
offset:`int` | The number of octets at the beginning of the result to skip.
length:`int` | The number of octets to retrieve.

Returns
`Deferred` | A deferred whose callback is invoked with a mapping of message numbers to retrieved data, or whose errback is invoked if there is an error.

def fetchUID(self, messages, uid=0): (source)

Retrieve the unique identifier for one or more messages

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a dict mapping message sequence numbers to unique message identifiers, or whose errback is invoked if there is an error.

def flagsChanged(self, newFlags): (source)
from `twisted.mail.interfaces.IMailboxIMAPListener`

Override me

def getCapabilities(self, useCache=1): (source)

Request the capabilities available on this server.

This command is allowed in any state of connection.

Parameters
useCache:`bool` | Specify whether to use the capability-cache or to re-retrieve the capabilities from the server. Server capabilities should never change, so for normal use, this flag should never be false.

Returns
`Deferred` | A deferred whose callback will be invoked with a dictionary mapping capability types to lists of supported mechanisms, or to None if a support list is not applicable.

def lineReceived(self, line): (source)
overrides `twisted.protocols.basic.LineReceiver.lineReceived`

Attempt to parse a single line from the server.

Parameters
line:`bytes` | The line from the server, without the line delimiter.

Raises
`IllegalServerResponse` | If the line or some part of the line does not represent an allowed message from the server at this time.

def list(self, reference, wildcard): (source)

List a subset of the available mailboxes

This command is allowed in the Authenticated and Selected states.

Parameters
reference:`str` | The context in which to interpret `wildcard`
wildcard:`str` | The pattern of mailbox names to match, optionally including either or both of the '*' and '%' wildcards. '*' will match zero or more characters and cross hierarchical boundaries. '%' will also match zero or more characters, but is limited to a single hierarchical level.

Returns
`Deferred` | A deferred whose callback is invoked with a list of `tuple`s, the first element of which is a `tuple` of mailbox flags, the second element of which is the hierarchy delimiter for this mailbox, and the third of which is the mailbox name; if the command is unsuccessful, the deferred's errback is invoked instead. NB: the delimiter and the mailbox name are `str`s.

def login(self, username, password): (source)

Authenticate with the server using a username and password

This command is allowed in the Non-Authenticated state. If the server supports the STARTTLS capability and our transport supports TLS, TLS is negotiated before the login command is issued.

A more secure way to log in is to use `startTLS` or `authenticate` or both.

Parameters
username:`str` | The username to log in with
password:`str` | The password to log in with

Returns
`Deferred` | A deferred whose callback is invoked if login is successful and whose errback is invoked otherwise.

def logout(self): (source)

Inform the server that we are done with the connection.

This command is allowed in any state of connection.

Returns
`Deferred` | A deferred whose callback will be invoked with None when the proper server acknowledgement has been received.

def lsub(self, reference, wildcard): (source)

List a subset of the subscribed available mailboxes

This command is allowed in the Authenticated and Selected states.

The parameters and returned object are the same as for the `list` method, with one slight difference: Only mailboxes which have been subscribed can be included in the resulting list.

def makeTag(self): (source)

Undocumented

def messageFile(self, octets): (source)

Create a file to which an incoming message may be written.

Parameters
octets:`int` | The number of octets which will be written to the file

Returns
Any object which implements `write(string)` and `seek(int, int)` | A file-like object

def modeChanged(self, writeable): (source)
from `twisted.mail.interfaces.IMailboxIMAPListener`

Override me

def namespace(self): (source)

Retrieve information about the namespaces available to this account

This command is allowed in the Authenticated and Selected states.

Returns

`Deferred`

A deferred whose callback is invoked with namespace information. An example of this information is:

        [[['', '/']], [], []]

which indicates a single personal namespace called '' with '/' as its hierarchical delimiter, and no shared or user namespaces.

def newMessages(self, exists, recent): (source)
from `twisted.mail.interfaces.IMailboxIMAPListener`

Override me

def noop(self): (source)

Perform no operation.

This command is allowed in any state of connection.

Returns
`Deferred` | A deferred whose callback will be invoked with a list of untagged status updates the server responds with.

def rawDataReceived(self, data): (source)
overrides `twisted.protocols.basic.LineReceiver.rawDataReceived`

Override this for when raw data is received.

def registerAuthenticator(self, auth): (source)

Register a new form of authentication

When invoking the authenticate() method of IMAP4Client, the first matching authentication scheme found will be used. The ordering is that in which the server lists support authentication schemes.

Parameters
auth:Implementor of `IClientAuthentication` | The object to use to perform the client side of this authentication scheme.

def removeFlags(self, messages, flags, silent=1, uid=0): (source)

Remove from the set flags for one or more messages.

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
flags:Any iterable of `str` | The flags to set
silent:`bool` | If true, cause the server to suppress its verbose response.
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a list of the server's responses (`[]` if `silent` is true) or whose errback is invoked if there is an error.

def rename(self, oldname, newname): (source)

Rename a mailbox

This command is allowed in the Authenticated and Selected states.

Parameters
oldname:`str` | The current name of the mailbox to rename.
newname:`str` | The new name to give the mailbox.

Returns
`Deferred` | A deferred whose callback is invoked if the rename is successful and whose errback is invoked otherwise.

def response_AUTH(self, tag, rest): (source)

Undocumented

def response_UNAUTH(self, tag, rest): (source)

Undocumented

def search(self, *queries, uid=False): (source)

Search messages in the currently selected mailbox

This command is allowed in the Selected state.

Any non-zero number of queries are accepted by this method, as returned by the `Query`, `Or`, and `Not` functions.

Parameters
*queries | Undocumented
uid:`bool` | if true, the server is asked to return message UIDs instead of message sequence numbers.

Returns
`Deferred` | A deferred whose callback will be invoked with a list of all the message sequence numbers return by the search, or whose errback will be invoked if there is an error.

def select(self, mailbox): (source)

Select a mailbox

This command is allowed in the Authenticated and Selected states.

Parameters
mailbox:`str` | The name of the mailbox to select

Returns

`Deferred`

A deferred whose callback is invoked with mailbox information if the select is successful and whose errback is invoked otherwise. Mailbox information consists of a dictionary with the following `str` keys and values:

            FLAGS: A list of strings containing the flags settable on
                    messages in this mailbox.

            EXISTS: An integer indicating the number of messages in this
                    mailbox.

            RECENT: An integer indicating the number of "recent"
                    messages in this mailbox.

            UNSEEN: The message sequence number (an integer) of the
                    first unseen message in the mailbox.

            PERMANENTFLAGS: A list of strings containing the flags that
                    can be permanently set on messages in this mailbox.

            UIDVALIDITY: An integer uniquely identifying this mailbox.

def sendCommand(self, cmd): (source)

Undocumented

def serverGreeting(self, caps): (source)

Called when the server has sent us a greeting.

Parameters
caps:`dict` | Capabilities the server advertised in its greeting.

def setFlags(self, messages, flags, silent=1, uid=0): (source)

Set the flags for one or more messages.

This command is allowed in the Selected state.

Parameters
messages:`MessageSet` or `str` | A message sequence set
flags:Any iterable of `str` | The flags to set
silent:`bool` | If true, cause the server to suppress its verbose response.
uid:`bool` | Indicates whether the message sequence set is of message numbers or of unique message IDs.

Returns
`Deferred` | A deferred whose callback is invoked with a list of the server's responses (`[]` if `silent` is true) or whose errback is invoked if there is an error.

def startTLS(self, contextFactory=None): (source)

Initiates a 'STARTTLS' request and negotiates the TLS / SSL Handshake.

Parameters
contextFactory:`ssl.ClientContextFactory` | The TLS / SSL Context Factory to leverage. If the contextFactory is None the IMAP4Client will either use the current TLS / SSL Context Factory or attempt to create a new one.

Returns
A Deferred which fires when the transport has been secured according to the given contextFactory, or which fails if the transport cannot be secured.

def status(self, mailbox, *names): (source)

Retrieve the status of the given mailbox

This command is allowed in the Authenticated and Selected states.

Parameters
mailbox:`str` | The name of the mailbox to query
*names:`bytes` | The status names to query. These may be any number of: `'MESSAGES'`, `'RECENT'`, `'UIDNEXT'`, `'UIDVALIDITY'`, and `'UNSEEN'`.

Returns
`Deferred` | A deferred which fires with the status information if the command is successful and whose errback is invoked otherwise. The status information is in the form of a `dict`. Each element of `names` is a key in the dictionary. The value for each key is the corresponding response from the server.

def subscribe(self, name): (source)

Add a mailbox to the subscription list

This command is allowed in the Authenticated and Selected states.

Parameters
name:`str` | The mailbox to mark as 'active' or 'subscribed'

Returns
`Deferred` | A deferred whose callback is invoked if the subscription is successful and whose errback is invoked otherwise.

def timeoutConnection(self): (source)
overrides `twisted.protocols.policies.TimeoutMixin.timeoutConnection`

Called when the connection times out.

Override to define behavior other than dropping the connection.

def unsubscribe(self, name): (source)

Remove a mailbox from the subscription list

This command is allowed in the Authenticated and Selected states.

Parameters
name:`str` | The mailbox to unsubscribe

Returns
`Deferred` | A deferred whose callback is invoked if the unsubscription is successful and whose errback is invoked otherwise.

STATUS_CODES: `tuple[str, ...]` = (source)

Undocumented

Value

    ('OK', 'NO', 'BAD', 'PREAUTH', 'BYE')

STATUS_TRANSFORMATIONS = (source)

Undocumented

Value

    {'MESSAGES': int, 'RECENT': int, 'UNSEEN': int}

tagID: `int` = (source)

Undocumented

timeout: `int` = (source)

Undocumented

authenticators: `dict` = (source)

Undocumented

context = (source)

Undocumented

queued = (source)

Undocumented

startedTLS: `bool` = (source)

Undocumented

state: `str` = (source)

A string representing the state the connection is currently in.

tags = (source)

Undocumented

waiting = (source)

Undocumented

def __cbAuthenticate(self, caps, secret): (source)

Undocumented

def __cbAuthTLS(self, caps, secret): (source)

Undocumented

def __cbCapabilities(self, result): (source)

Undocumented

def __cbContinueAppend(self, lines, message): (source)

Undocumented

def __cbContinueAuth(self, rest, scheme, secret): (source)

Undocumented

def __cbExpunge(self, result): (source)

Undocumented

def __cbFinishAppend(self, foo): (source)

Undocumented

def __cbList(self, result, command): (source)

Undocumented

def __cbLoginCaps(self, capabilities, username, password): (source)

Undocumented

def __cbLoginTLS(self, result, username, password): (source)

Undocumented

def __cbLogout(self, result): (source)

Undocumented

def __cbNamespace(self, result): (source)

Undocumented

def __cbNoop(self, result): (source)

Undocumented

def __cbSearch(self, result): (source)

Undocumented

def __cbSelect(self, result, rw): (source)

Handle lines received in response to a SELECT or EXAMINE command.

See RFC 3501, section 6.3.1.

def __cbStatus(self, result): (source)

Undocumented

def __ebLoginTLS(self, failure): (source)

Undocumented

def _cbFetch(self, result, requestedParts, structured): (source)

Undocumented

def _defaultHandler(self, tag, rest): (source)

Undocumented

def _extraInfo(self, lines): (source)

Undocumented

def _fetch(self, messages, useUID=0, **terms): (source)

Undocumented

def _flushQueue(self): (source)

Undocumented

def _getContextFactory(self): (source)

Undocumented

def _intOrRaise(self, value, phrase): (source)

Parse `value` as an integer and return the result or raise `IllegalServerResponse` with `phrase` as an argument if `value` cannot be parsed as an integer.

def _parseFetchPairs(self, fetchResponseList): (source)

Given the result of parsing a single FETCH response, construct a `dict` mapping response keys to response values.

Parameters

fetchResponseList

The result of parsing a FETCH response with `parseNestedParens` and extracting just the response data (that is, just the part that comes after `"FETCH"`). The form of this input (and therefore the output of this method) is very disagreeable. A valuable improvement would be to enumerate the possible keys (representing them as structured objects of some sort) rather than using strings and tuples of tuples of strings and so forth. This would allow the keys to be documented more easily and would allow for a much simpler application-facing API (one not based on looking up somewhat hard to predict keys in a dict). Since `fetchResponseList` notionally represents a flattened sequence of pairs (identifying keys followed by their associated values), collapsing such complex elements of this list as `["BODY", ["HEADER.FIELDS", ["SUBJECT"]]]` into a single object would also greatly simplify the implementation of this method.

Returns
A `dict` of the response data represented by `pairs`. Keys in this dictionary are things like `"RFC822.TEXT"`, `"FLAGS"`, or `("BODY", ("HEADER.FIELDS", ("SUBJECT",)))`. Values are entirely dependent on the key with which they are associated, but retain the same structured as produced by `parseNestedParens`.

def _regularDispatch(self, line): (source)

Undocumented

def _setupForLiteral(self, rest, octets): (source)

Undocumented

def _startedTLS(self, result, context): (source)

Undocumented

def _store(self, messages, cmd, silent, flags, uid): (source)

Undocumented

_memoryFileLimit = (source)

Undocumented

_statusNames = (source)

Undocumented

_capCache = (source)

Undocumented

_lastCmd = (source)

Undocumented

_parts = (source)

Undocumented

_pendingBuffer = (source)

Undocumented

_pendingSize = (source)

Undocumented

_tag = (source)

Undocumented