Package twisted :: Package protocols :: Module imap4 :: Class IMAP4Client
[show private | hide private]
[frames | no frames]

Class IMAP4Client

BaseProtocol --+        
               |        
        Protocol --+    
                   |    
        LineReceiver --+
                       |
                      IMAP4Client


IMAP4 client protocol implementation
Method Summary
  __init__(self)
Deferred addFlags(self, messages, flags, silent, uid)
Add to the set flags for one or more messages.
Deferred append(self, mailbox, message, flags, date)
Add the given message to the currently selected mailbox
Deferred authenticate(self, secret)
Attempt to enter the authenticated state with the server
Deferred check(self)
Tell the server to perform a checkpoint
Deferred close(self)
Return the connection to the Authenticated state.
  connectionFailed(self)
(Deprecated) (inherited from Protocol)
  connectionLost(self, reason)
Called when the connection is shut down. (inherited from Protocol)
Deferred copy(self, messages, mailbox)
Copy the specified messages to the specified mailbox.
Deferred create(self, name)
Create a new mailbox on the server
  dataReceived(self, data)
Protocol.dataReceived. (inherited from LineReceiver)
Deferred delete(self, name)
Delete a mailbox
  dispatchCommand(self, tag, rest)
Deferred examine(self, mailbox)
Select a mailbox in read-only mode
Deferred expunge(self)
Return the connection to the Authenticate state.
Deferred fetchAll(self, messages, uid)
Retrieve several different fields of one or more messages
Deferred fetchBody(self, messages, uid)
Retrieve body text of one or more messages
Deferred fetchBodyStructure(self, messages, uid)
Retrieve the structure of the body of one or more messages
Deferred fetchEnvelope(self, messages, uid)
Retrieve the envelope data for one or more messages
Deferred fetchFast(self, messages, uid)
Retrieve several different fields of one or more messages
Deferred fetchFlags(self, messages, uid)
Retrieve the flags for one or more messages
Deferred fetchFull(self, messages, uid)
Retrieve several different fields of one or more messages
Deferred fetchHeaders(self, messages, uid)
Retrieve headers of one or more messages
Deferred fetchInternalDate(self, messages, uid)
Retrieve the internal date associated with one or more messages
Deferred fetchMessage(self, messages, uid)
Retrieve one or more entire messages
Deferred fetchSimplifiedBody(self, messages, uid)
Retrieve the simplified body structure of one or more messages
Deferred fetchSize(self, messages, uid)
Retrieve the size, in octets, of one or more messages
Deferred fetchSpecific(self, messages, uid, headerType, headerNumber, headerArgs, peek, offset, length)
Retrieve a specific section of one or more messages
Deferred fetchUID(self, messages)
Retrieve the unique identifier for one or more messages
  flagsChanged(self, newFlags)
Override me
Deferred getCapabilities(self)
Request the capabilities available on this server.
  lineLengthExceeded(self, line)
Called when the maximum line length has been reached. (inherited from LineReceiver)
  lineReceived(self, line)
Override this for when each line is received.
Deferred list(self, reference, wildcard)
List a subset of the available mailboxes
Deferred login(self, username, password)
Authenticate with the server using a username and password
Deferred logout(self)
Inform the server that we are done with the connection.
  lsub(self, reference, wildcard)
List a subset of the subscribed available mailboxes
  makeTag(self)
Any object which implements write(string) and seek(int, int) messageFile(self, octets)
Create a file to which an incoming message may be written.
  modeChanged(self, writeable)
Override me
  newMessages(self, exists, recent)
Override me
Deferred noop(self)
Perform no operation.
  rawDataReceived(self, data)
Override this for when raw data is received.
  registerAuthenticator(self, auth)
Register a new form of authentication
Deferred removeFlags(self, messages, flags, silent, uid)
Remove from the set flags for one or more messages.
Deferred rename(self, oldname, newname)
Rename a mailbox
  response_AUTH(self, tag, rest)
  response_UNAUTH(self, tag, rest)
Deferred search(self, *queries)
Search messages in the currently selected mailbox
Deferred select(self, mailbox)
Select a mailbox
  sendCommand(self, cmd)
  sendLine(self, line)
Sends a line to the other end of the connection. (inherited from LineReceiver)
Deferred setFlags(self, messages, flags, silent, uid)
Set the flags for one or more messages.
  setLineMode(self, extra)
Sets the line-mode of this receiver. (inherited from LineReceiver)
  setRawMode(self)
Sets the raw mode of this receiver. (inherited from LineReceiver)
Deferred status(self, mailbox, *names)
Retrieve the status of the given mailbox
Deferred subscribe(self, name)
Add a mailbox to the subscription list
Deferred unsubscribe(self, name)
Remove a mailbox from the subscription list

Instance Variable Summary
  state - A string representing the state the connection is currently in.

Class Variable Summary
tuple __implements__
NoneType authenticators
NoneType queued
NoneType state
tuple STATUS_CODES
dict STATUS_TRANSFORMATIONS
int tagID
NoneType tags
NoneType waiting

Method Details

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

Add to the set flags for one or more messages.

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
flags - The flags to set
           (type=Any iterable of str)
silent - If true, cause the server to supress its verbose response.
           (type=bool)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
A deferred whose callback is invoked with a list of the the server's responses ([] if silent is true) or whose errback is invoked if there is an error.
           (type=Deferred)

append(self, mailbox, message, flags=(), date=None)

Add the given message to the currently selected mailbox

This command is allowed in the Authenticated and Selected states.
Parameters:
mailbox - The mailbox to which to add this message.
           (type=str)
message - The message to add, in RFC822 format.
           (type=Any file-like object)
flags - The flags to associated with this message.
           (type=Any iterable of str)
date
           (type=str)
Returns:
A deferred whose callback is invoked when this command succeeds or whose errback is invoked if it fails.
           (type=Deferred)

authenticate(self, secret)

Attempt to enter the authenticated state with the server

This command is allowed in the Non-Authenticated state.
Returns:
A deferred whose callback is invoked if the authentication succeeds and whose errback will be invoked otherwise.
           (type=Deferred)

check(self)

Tell the server to perform a checkpoint

This command is allowed in the Selected state.
Returns:
A deferred whose callback is invoked when this command succeeds or whose errback is invoked if it fails.
           (type=Deferred)

close(self)

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:
A deferred whose callback is invoked when the command completes successfully or whose errback is invoked if it fails.
           (type=Deferred)

copy(self, messages, mailbox)

Copy the specified messages to the specified mailbox.

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
mailbox - The mailbox to which to copy the messages
           (type=str)
Returns:
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.
           (type=Deferred)

create(self, name)

Create a new mailbox on the server

This command is allowed in the Authenticated and Selected states.
Parameters:
name - The name of the mailbox to create.
           (type=str)
Returns:
A deferred whose callback is invoked if the mailbox creation is successful and whose errback is invoked otherwise.
           (type=Deferred)

delete(self, name)

Delete a mailbox

This command is allowed in the Authenticated and Selected states.
Parameters:
name - The name of the mailbox to delete.
           (type=str)
Returns:
A deferred whose calblack is invoked if the mailbox is deleted successfully and whose errback is invoked otherwise.
           (type=Deferred)

examine(self, mailbox)

Select a mailbox in read-only mode

This command is allowed in the Authenticated and Selected states.
Parameters:
mailbox - The name of the mailbox to examine
Returns:
A deferred whose callback is invoked with mailbox information if the examine is successful and whose errback is invoked otherwise.
           (type=Deferred)

expunge(self)

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:
A deferred whose callback is invoked with a list of the 'expunge' responses when this command is successful or whose errback is invoked otherwise.
           (type=Deferred)

fetchAll(self, messages, uid=0)

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 - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
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".
           (type=Deferred)

fetchBody(self, messages, uid=0)

Retrieve body text of one or more messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
A deferred whose callback is invoked with a dict mapping message numbers to body text, or whose errback is invoked if there is an error.
           (type=Deferred)

fetchBodyStructure(self, messages, uid=0)

Retrieve the structure of the body of one or more messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
A deferred whose callback is invoked with a dict mapping message numbers to structure data, or whose errback is invoked if there is an error.
           (type=Deferred)

fetchEnvelope(self, messages, uid=0)

Retrieve the envelope data for one or more messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
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.
           (type=Deferred)

fetchFast(self, messages, uid=0)

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 - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
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".
           (type=Deferred)

fetchFlags(self, messages, uid=0)

Retrieve the flags for one or more messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set (e.g., '1,3,4' or '2:5,11')
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
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.
           (type=Deferred)

fetchFull(self, messages, uid=0)

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 - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
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".
           (type=Deferred)

fetchHeaders(self, messages, uid=0)

Retrieve headers of one or more messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
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.
           (type=Deferred)

fetchInternalDate(self, messages, uid=0)

Retrieve the internal date associated with one or more messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
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.
           (type=Deferred)

fetchMessage(self, messages, uid=0)

Retrieve one or more entire messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
A deferred whose callback is invoked with a dict mapping message numbers to messages objects, or whose errback is invoked if there is an error.
           (type=Deferred)

fetchSimplifiedBody(self, messages, uid=0)

Retrieve the simplified body structure of one or more messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
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.
           (type=Deferred)

fetchSize(self, messages, uid=0)

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

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
A deferred whose callback is invoked with a dict mapping message numbers to sizes, or whose errback is invoked if there is an error.
           (type=Deferred)

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

Retrieve a specific section of one or more messages
Parameters:
messages - A message sequence set
           (type=str)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
headerType - 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 - 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.
           (type=int or int sequence)
headerArgs - 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.
           (type=A sequence of str)
peek - If true, cause the server to not set the \Seen flag on this message as a result of this command.
           (type=bool)
offset - The number of octets at the beginning of the result to skip.
           (type=int)
length - The number of octets to retrieve.
           (type=int)
Returns:
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.
           (type=Deferred)

fetchUID(self, messages)

Retrieve the unique identifier for one or more messages

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
Returns:
A deferred whose callback is invoked with a dict mapping message numbers to message identifiers, or whose errback is invoked if there is an error.
           (type=Deferred)

flagsChanged(self, newFlags)

Override me

getCapabilities(self)

Request the capabilities available on this server.

This command is allowed in any state of connection.
Returns:
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.
           (type=Deferred)

lineReceived(self, line)

Override this for when each line is received.
Overrides:
twisted.protocols.basic.LineReceiver.lineReceived (inherited documentation)

list(self, reference, wildcard)

List a subset of the available mailboxes

This command is allowed in the Authenticated and Selected states.
Parameters:
reference - The context in which to interpret wildcard
           (type=str)
wildcard - 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.
           (type=str)
Returns:
A deferred whose callback is invoked with a list of tuples, 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.
           (type=Deferred)

login(self, username, password)

Authenticate with the server using a username and password

This command is allowed in the Non-Authenticated state.
Parameters:
username - The username to log in with
           (type=str)
password - The password to log in with
           (type=str)
Returns:
A deferred whose callback is invoked if login is successful and whose errback is invoked otherwise.
           (type=Deferred)

logout(self)

Inform the server that we are done with the connection.

This command is allowed in any state of connection.
Returns:
A deferred whose callback will be invoked with None when the proper server acknowledgement has been received.
           (type=Deferred)

lsub(self, reference, wildcard)

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.

messageFile(self, octets)

Create a file to which an incoming message may be written.
Parameters:
octets - The number of octets which will be written to the file
           (type=int)
Returns:
A file-like object
           (type=Any object which implements write(string) and seek(int, int))

modeChanged(self, writeable)

Override me

newMessages(self, exists, recent)

Override me

noop(self)

Perform no operation.

This command is allowed in any state of connection.
Returns:
A deferred whose callback will be invoked with a list of untagged status updates the server responds with.
           (type=Deferred)

rawDataReceived(self, data)

Override this for when raw data is received.
Overrides:
twisted.protocols.basic.LineReceiver.rawDataReceived (inherited documentation)

registerAuthenticator(self, auth)

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 - The object to use to perform the client side of this authentication scheme.
           (type=Implementor of IClientAuthentication)

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

Remove from the set flags for one or more messages.

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
flags - The flags to set
           (type=Any iterable of str)
silent - If true, cause the server to supress its verbose response.
           (type=bool)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
A deferred whose callback is invoked with a list of the the server's responses ([] if silent is true) or whose errback is invoked if there is an error.
           (type=Deferred)

rename(self, oldname, newname)

Rename a mailbox

This command is allowed in the Authenticated and Selected states.
Parameters:
oldname - The current name of the mailbox to rename.
           (type=str)
newname - The new name to give the mailbox.
           (type=str)
Returns:
A deferred whose callback is invoked if the rename is successful and whose errback is invoked otherwise.
           (type=Deferred)

search(self, *queries)

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.
Returns:
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.
           (type=Deferred)

select(self, mailbox)

Select a mailbox

This command is allowed in the Authenticated and Selected states.
Parameters:
mailbox - The name of the mailbox to select
           (type=str)
Returns:
A deferred whose callback is invoked with mailbox information if the select is successful and whose errback is invoked otherwise.
           (type=Deferred)

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

Set the flags for one or more messages.

This command is allowed in the Selected state.
Parameters:
messages - A message sequence set
           (type=str)
flags - The flags to set
           (type=Any iterable of str)
silent - If true, cause the server to supress its verbose response.
           (type=bool)
uid - Indicates whether the message sequence set is of message numbers or of unique message IDs.
           (type=bool)
Returns:
A deferred whose callback is invoked with a list of the the server's responses ([] if silent is true) or whose errback is invoked if there is an error.
           (type=Deferred)

status(self, mailbox, *names)

Retrieve the status of the given mailbox

This command is allowed in the Authenticated and Selected states.
Parameters:
mailbox - The name of the mailbox to query
           (type=str)
names - The status names to query. These may be any number of: MESSAGES, RECENT, UIDNEXT, UIDVALIDITY, and UNSEEN.
           (type=str)
Returns:
A deferred whose callback is invoked with the status information if the command is successful and whose errback is invoked otherwise.
           (type=Deferred)

subscribe(self, name)

Add a mailbox to the subscription list

This command is allowed in the Authenticated and Selected states.
Parameters:
name - The mailbox to mark as 'active' or 'subscribed'
           (type=str)
Returns:
A deferred whose callback is invoked if the subscription is successful and whose errback is invoked otherwise.
           (type=Deferred)

unsubscribe(self, name)

Remove a mailbox from the subscription list

This command is allowed in the Authenticated and Selected states.
Parameters:
name - The mailbox to unsubscribe
           (type=str)
Returns:
A deferred whose callback is invoked if the unsubscription is successful and whose errback is invoked otherwise.
           (type=Deferred)

Instance Variable Details

state

A string representing the state the connection is currently in.

Class Variable Details

__implements__

Type:
tuple
Value:
(<class 'twisted.protocols.imap4.IMailboxListener'>,)                  

authenticators

Type:
NoneType
Value:
None                                                                   

queued

Type:
NoneType
Value:
None                                                                   

state

Type:
NoneType
Value:
None                                                                   

STATUS_CODES

Type:
tuple
Value:
('OK', 'NO', 'BAD', 'PREAUTH', 'BYE')                                  

STATUS_TRANSFORMATIONS

Type:
dict
Value:
{'MESSAGES': <type 'int'>, 'UNSEEN': <type 'int'>, 'RECENT': <type 'in\
t'>}                                                                   

tagID

Type:
int
Value:
1                                                                      

tags

Type:
NoneType
Value:
None                                                                   

waiting

Type:
NoneType
Value:
None                                                                   

Generated by Epydoc 1.1 on Thu May 8 13:16:38 2003 http://epydoc.sf.net