t.m.p.POP3Client(basic.LineOnlyReceiver, policies.TimeoutMixin) : class documentation

Part of twisted.mail.pop3client View Source View In Hierarchy

POP3 client protocol implementation class

Instances of this class provide a convenient, efficient API for retrieving and deleting messages from a POP3 server.

Instance Variable startedTLS Whether TLS has been negotiated successfully. (type: bool)
Instance Variable allowInsecureLogin Indicate whether login() should be allowed if the server offers no authentication challenge and if our transport does not offer any protection via encryption. (type: bool)
Instance Variable serverChallenge Challenge received from the server (type: str or None)
Instance Variable timeout Number of seconds to wait before timing out a connection. If the number is <= 0, no timeout checking will be performed. (type: int)
Method sendShort Undocumented
Method sendLong Undocumented
Method connectionMade Called when a connection is made.
Method timeoutConnection Called when the connection times out.
Method connectionLost Called when the connection is shut down.
Method lineReceived Override this for when each line is received.
Method lineLengthExceeded Called when the maximum line length has been reached. Override if it needs to be dealt with in some special way.
Method state_WELCOME Undocumented
Method state_WAITING Undocumented
Method state_SHORT Undocumented
Method state_LONG_INITIAL Undocumented
Method state_LONG Undocumented
Method serverGreeting Called when the server has sent us a greeting.
Method startTLS Initiates a 'STLS' request and negotiates the TLS / SSL Handshake.
Method login Log into the server.
Method apop Perform APOP login.
Method user Send the user command.
Method password Send the password command.
Method delete Delete a message from the server.
Method capabilities Retrieve the capabilities supported by this server.
Method noop Do nothing, with the help of the server.
Method reset Remove the deleted flag from any messages which have it.
Method retrieve Retrieve a message from the server.
Method stat Get information about the size of this mailbox.
Method listSize Retrieve a list of the size of all messages on the server.
Method listUID Retrieve a list of the UIDs of all messages on the server.
Method quit Disconnect from the server.
Method _blocked Undocumented
Method _unblock Undocumented
Method _startTLS Undocumented
Method _startedTLS Undocumented
Method _getContextFactory Undocumented
Method _login Undocumented
Method _loginTLS Undocumented
Method _plaintext Undocumented
Method _apop Undocumented
Method _consumeOrSetItem Undocumented
Method _consumeOrAppend Undocumented

Inherited from LineOnlyReceiver:

Class Variable delimiter The line-ending delimiter to use. By default this is '\r\n'.
Class Variable 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.
Method dataReceived Translates bytes into lines, and calls lineReceived.
Method sendLine Sends a line to the other end of the connection.

Inherited from Protocol (via LineOnlyReceiver):

Method logPrefix Return a prefix matching the class name, to identify log messages related to this protocol instance.

Inherited from BaseProtocol (via LineOnlyReceiver, Protocol):

Method makeConnection Make a connection to a transport and a server.

Inherited from TimeoutMixin:

Class Variable timeOut The number of seconds after which to timeout the connection.
Method callLater Wrapper around reactor.callLater for test purpose.
Method resetTimeout Reset the timeout count down.
Method setTimeout Change the timeout period
Method __timedOut Undocumented
startedTLS =
Whether TLS has been negotiated successfully. (type: bool)
allowInsecureLogin =
Indicate whether login() should be allowed if the server offers no authentication challenge and if our transport does not offer any protection via encryption. (type: bool)
serverChallenge =
Challenge received from the server (type: str or None)
timeout =
Number of seconds to wait before timing out a connection. If the number is <= 0, no timeout checking will be performed. (type: int)
def _blocked(self, f, *a): (source)
Undocumented
def _unblock(self): (source)
Undocumented
def sendShort(self, cmd, args): (source)
Undocumented
def sendLong(self, cmd, args, consumer, xform): (source)
Undocumented
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 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 connectionLost(self, reason): (source)
from twisted.internet.interfaces.IProtocol
overrides twisted.internet.protocol.Protocol.connectionLost
Called when the connection is shut down.

Clear any circular references here, and any external references to this Protocol. The connection has been closed.

def lineReceived(self, line): (source)
overrides twisted.protocols.basic.LineOnlyReceiver.lineReceived
Override this for when each line is received.
ParameterslineThe line which was received with the delimiter removed. (type: str)
def lineLengthExceeded(self, buffer): (source)
overrides twisted.protocols.basic.LineOnlyReceiver.lineLengthExceeded
Called when the maximum line length has been reached. Override if it needs to be dealt with in some special way.
def state_WELCOME(self, line): (source)
Undocumented
def state_WAITING(self, line): (source)
Undocumented
def state_SHORT(self, line): (source)
Undocumented
def state_LONG_INITIAL(self, line): (source)
Undocumented
def state_LONG(self, line): (source)
Undocumented
def serverGreeting(self, greeting): (source)
Called when the server has sent us a greeting.
ParametersgreetingThe status message sent with the server greeting. For servers implementing APOP authentication, this will be a challenge string. . (type: str or None)
def startTLS(self, contextFactory=None): (source)
Initiates a 'STLS' request and negotiates the TLS / SSL Handshake.
ReturnsA Deferred which fires when the transport has been secured according to the given contextFactory, or which fails if the transport cannot be secured.
def _startTLS(self, caps, contextFactory, tls): (source)
Undocumented
def _startedTLS(self, result, context, tls): (source)
Undocumented
def _getContextFactory(self): (source)
Undocumented
def login(self, username, password): (source)
Log into the server.

If APOP is available it will be used. Otherwise, if TLS is available an 'STLS' session will be started and plaintext login will proceed. Otherwise, if the instance attribute allowInsecureLogin is set to True, insecure plaintext login will proceed. Otherwise, InsecureAuthenticationDisallowed will be raised (asynchronously).

ParametersusernameThe username with which to log in.
passwordThe password with which to log in.
ReturnsA deferred which fires when login has completed. (type: Deferred)
def _login(self, caps, username, password): (source)
Undocumented
def _loginTLS(self, res, username, password): (source)
Undocumented
def _plaintext(self, username, password): (source)
Undocumented
def _apop(self, username, password, challenge): (source)
Undocumented
def apop(self, username, digest): (source)
Perform APOP login.

This should be used in special circumstances only, when it is known that the server supports APOP authentication, and APOP authentication is absolutely required. For the common case, use login instead.

ParametersusernameThe username with which to log in.
digestThe challenge response to authenticate with.
def user(self, username): (source)
Send the user command.

This performs the first half of plaintext login. Unless this is absolutely required, use the login method instead.

ParametersusernameThe username with which to log in.
def password(self, password): (source)
Send the password command.

This performs the second half of plaintext login. Unless this is absolutely required, use the login method instead.

ParameterspasswordThe plaintext password with which to authenticate.
def delete(self, index): (source)
Delete a message from the server.
ParametersindexThe index of the message to delete. This is 0-based. (type: int)
ReturnsA deferred which fires when the delete command is successful, or fails if the server returns an error. (type: Deferred)
def _consumeOrSetItem(self, cmd, args, consumer, xform): (source)
Undocumented
def _consumeOrAppend(self, cmd, args, consumer, xform): (source)
Undocumented
def capabilities(self, useCache=True): (source)
Retrieve the capabilities supported by this server.

Not all servers support this command. If the server does not support this, it is treated as though it returned a successful response listing no capabilities. At some future time, this may be changed to instead seek out information about a server's capabilities in some other fashion (only if it proves useful to do so, and only if there are servers still in use which do not support CAPA but which do support POP3 extensions that are useful).

ParametersuseCacheIf set, and if capabilities have been retrieved previously, just return the previously retrieved results. (type: bool)
ReturnsA Deferred which fires with a dict mapping str to None or lists of str. For example: 
   C: CAPA
   S: +OK Capability list follows
   S: TOP
   S: USER
   S: SASL CRAM-MD5 KERBEROS_V4
   S: RESP-CODES
   S: LOGIN-DELAY 900
   S: PIPELINING
   S: EXPIRE 60
   S: UIDL
   S: IMPLEMENTATION Shlemazle-Plotz-v302
   S: .

will be lead to a result of:

   | {'TOP': None,
   |  'USER': None,
   |  'SASL': ['CRAM-MD5', 'KERBEROS_V4'],
   |  'RESP-CODES': None,
   |  'LOGIN-DELAY': ['900'],
   |  'PIPELINING': None,
   |  'EXPIRE': ['60'],
   |  'UIDL': None,
   |  'IMPLEMENTATION': ['Shlemazle-Plotz-v302']}
def noop(self): (source)
Do nothing, with the help of the server.

No operation is performed. The returned Deferred fires when the server responds.

def reset(self): (source)
Remove the deleted flag from any messages which have it.

The returned Deferred fires when the server responds.

def retrieve(self, index, consumer=None, lines=None): (source)
Retrieve a message from the server.

If consumer is not None, it will be called with each line of the message as it is received. Otherwise, the returned Deferred will be fired with a list of all the lines when the message has been completely received.

def stat(self): (source)
Get information about the size of this mailbox.

The returned Deferred will be fired with a tuple containing the number or messages in the mailbox and the size (in bytes) of the mailbox.

def listSize(self, consumer=None): (source)
Retrieve a list of the size of all messages on the server.

If consumer is not None, it will be called with two-tuples of message index number and message size as they are received. Otherwise, a Deferred which will fire with a list of only message sizes will be returned. For messages which have been deleted, None will be used in place of the message size.

def listUID(self, consumer=None): (source)
Retrieve a list of the UIDs of all messages on the server.

If consumer is not None, it will be called with two-tuples of message index number and message UID as they are received. Otherwise, a Deferred which will fire with of list of only message UIDs will be returned. For messages which have been deleted, None will be used in place of the message UID.

def quit(self): (source)
Disconnect from the server.
API Documentation for Twisted, generated by pydoctor at 2012-09-01 11:44:56.