class documentation

A POP3 server protocol.

Method authenticateUserAPOP Perform APOP authentication.
Method authenticateUserPASS Perform authentication for a username/password login.
Method connectionLost Clean up when the connection has been lost.
Method connectionMade Send a greeting to the client after the connection has been made.
Method do_APOP Handle an APOP command.
Method do_AUTH Handle an AUTH command.
Method do_CAPA Handle a CAPA command.
Method do_DELE Handle a DELE command.
Method do_LAST Handle a LAST command.
Method do_LIST Handle a LIST command.
Method do_NOOP Handle a NOOP command.
Method do_PASS Handle a PASS command.
Method do_QUIT Handle a QUIT command.
Method do_RETR Handle a RETR command.
Method do_RPOP Handle an RPOP command.
Method do_RSET Handle a RSET command.
Method do_STAT Handle a STAT command.
Method do_TOP Handle a TOP command.
Method do_UIDL Handle a UIDL command.
Method do_USER Handle a USER command.
Method failResponse Send a response indicating failure.
Method finishedFileTransfer Send the termination sequence.
Method generateMagic Generate an APOP challenge.
Method lineReceived Pass a received line to a state machine function.
Method listCapabilities Return a list of server capabilities suitable for use in a CAPA response.
Method processCommand Dispatch a command from the client for handling.
Method state_AUTH Handle received lines for the AUTH state in which an authentication challenge response from the client is expected.
Method state_COMMAND Handle received lines for the COMMAND state in which commands from the client are expected.
Method stopProducing Stop producing data.
Method successResponse Send a response indicating success.
Method transformChunk Transform a chunk of a message to POP3 message format.
Constant AUTH_CMDS Undocumented
Instance Variable blocked A list of blocked commands. While a response to a command is being generated by the server, other commands are blocked. When no command is outstanding, blocked is set to none. Otherwise, it contains a list of information about blocked commands...
Instance Variable factory A server factory which provides an interface for querying capabilities of the server.
Instance Variable magic An APOP challenge. If not set, an APOP challenge string will be generated when a connection is made.
Instance Variable mbox The mailbox for the authenticated user.
Instance Variable portal A portal for authentication.
Instance Variable schedule A callable that arranges for an iterator to be cooperatively iterated over along with all other iterators which have been passed to it such that runtime is divided between all of them. It returns a deferred which fires when the iterator finishes.
Instance Variable state The state which indicates what type of messages are expected from the client. Valid states are 'COMMAND' and 'AUTH'
Instance Variable timeOut The number of seconds to wait for a command from the client before disconnecting.
Method _cbMailbox Complete successful authentication.
Method _coiterate Direct the output of an iterator to the transport and arrange for iteration to take place.
Method _ebMailbox Handle an expected authentication failure.
Method _ebUnexpected Handle an unexpected authentication failure.
Method _getMessageFile Retrieve the size and contents of a message.
Method _longOperation Stop timeouts and block further command processing while a long operation completes.
Method _sendMessageContent Send the contents of a message.
Method _unblock Process as many blocked commands as possible.
Instance Variable _auth Authorization credentials.
Instance Variable _highest The 1-based index of the highest message retrieved.
Instance Variable _onLogout The function to be executed when the connection is lost.
Instance Variable _userIs The username sent with the USER command.

Inherited from LineOnlyReceiver:

Method dataReceived Translates bytes into lines, and calls lineReceived.
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.
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 _buffer Undocumented

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.
Instance Variable connected Undocumented
Instance Variable transport Undocumented

Inherited from TimeoutMixin (via LineOnlyReceiver, Protocol, BaseProtocol):

Method callLater Wrapper around reactor.callLater for test purpose.
Method resetTimeout Reset the timeout count down.
Method setTimeout Change the timeout period
Method timeoutConnection Called when the connection times out.
Method __timedOut Undocumented
Instance Variable __timeoutCall Undocumented
def authenticateUserAPOP(self, user, digest): (source)

Perform APOP authentication.

Parameters
user:bytesThe name of the user attempting to log in.
digest:bytesThe challenge response.
Returns
Deferred which successfully results in 3-tuple of (1) IMailbox, (2) IMailbox provider, (3) no-argument callableA deferred which fires when authentication is complete. If successful, it returns an IMailbox interface, a mailbox, and a function to be invoked with the session is terminated. If authentication fails, the deferred fails with an UnathorizedLogin error.
Raises
cred.error.UnauthorizedLoginWhen authentication fails.
def authenticateUserPASS(self, user, password): (source)

Perform authentication for a username/password login.

Parameters
user:bytesThe name of the user attempting to log in.
password:bytesThe password to authenticate with.
Returns
Deferred which successfully results in 3-tuple of (1) IMailbox, (2) IMailbox provider, (3) no-argument callableA deferred which fires when authentication is complete. If successful, it returns a pop3.IMailbox interface, a mailbox, and a function to be invoked with the session is terminated. If authentication fails, the deferred fails with an UnathorizedLogin error.
Raises
cred.error.UnauthorizedLoginWhen authentication fails.
def connectionLost(self, reason): (source)

Clean up when the connection has been lost.

Parameters
reason:FailureThe reason the connection was terminated.
def connectionMade(self): (source)

Send a greeting to the client after the connection has been made.

def do_APOP(self, user, digest): (source)

Handle an APOP command.

Perform APOP authentication and complete the authorization process with the _cbMailbox callback function on success or the _ebMailbox and _ebUnexpected errback functions on failure.

Parameters
user:bytesA username.
digest:bytesAn MD5 digest string.
def do_AUTH(self, args=None): (source)

Handle an AUTH command.

If the AUTH extension is not supported, send an error response. If an authentication mechanism was not specified in the command, send a list of all supported authentication methods. Otherwise, send an authentication challenge to the client and transition to the AUTH state.

Parameters
args:bytes or NoneThe name of an authentication mechanism.
def do_CAPA(self): (source)

Handle a CAPA command.

Respond with the server capabilities.

def do_DELE(self, i): (source)

Handle a DELE command.

Mark a message for deletion and issue a successful response.

Parameters
i:intA 1-based message index.
def do_LAST(self): (source)

Handle a LAST command.

Respond with the 1-based index of the highest retrieved message.

def do_LIST(self, i=None): (source)

Handle a LIST command.

Parameters
i:bytes or NoneA 1-based message index.
Returns
DeferredA deferred which triggers after the response to the LIST command has been issued.
def do_NOOP(self): (source)

Handle a NOOP command.

Do nothing but issue a successful response.

def do_PASS(self, password, *words): (source)

Handle a PASS command.

If a USER command was previously received, authenticate the user and complete the authorization process with the _cbMailbox callback function on success or the _ebMailbox and _ebUnexpected errback functions on failure. If a USER command was not previously received, send an error response.

Parameters
password:bytesA password.
*words:tuple of bytesOther parts of the password split by spaces.
def do_QUIT(self): (source)

Handle a QUIT command.

Remove any messages marked for deletion, issue a successful response, and drop the connection.

def do_RETR(self, i): (source)

Handle a RETR command.

Parameters
i:bytesA 1-based message index.
Returns
DeferredA deferred which triggers after the response to the RETR command has been issued.
def do_RPOP(self, user): (source)

Handle an RPOP command.

RPOP is not supported. Send an error response.

Parameters
user:bytesA username.
def do_RSET(self): (source)

Handle a RSET command.

Unmark any messages that have been flagged for deletion.

def do_STAT(self): (source)

Handle a STAT command.

Returns
DeferredA deferred which triggers after the response to the STAT command has been issued.
def do_TOP(self, i, size): (source)

Handle a TOP command.

Parameters
i:bytesA 1-based message index.
size:bytesThe number of lines of the message to retrieve.
Returns
DeferredA deferred which triggers after the response to the TOP command has been issued.
def do_UIDL(self, i=None): (source)

Handle a UIDL command.

Parameters
i:bytes or NoneA 1-based message index.
Returns
DeferredA deferred which triggers after the response to the UIDL command has been issued.
def do_USER(self, user): (source)

Handle a USER command.

Save the username and send a successful response prompting the client for the password.

Parameters
user:bytesA username.
def failResponse(self, message=b''): (source)

Send a response indicating failure.

Parameters
message:stringifyable objectAn object whose string representation should be included in the response.
def finishedFileTransfer(self, lastsent): (source)

Send the termination sequence.

Parameters
lastsent:bytesThe last character of the file.
def generateMagic(self): (source)

Generate an APOP challenge.

Returns
bytesAn RFC 822 message id format string.
def lineReceived(self, line): (source)

Pass a received line to a state machine function.

Parameters
line:bytesA received line.
def listCapabilities(self): (source)

Return a list of server capabilities suitable for use in a CAPA response.

Returns
list of bytesA list of server capabilities.
def processCommand(self, command, *args): (source)

Dispatch a command from the client for handling.

Parameters
command:bytesA POP3 command.
*args:tuple of bytesArguments to the command.
Raises
POP3ErrorWhen the command is invalid or the command requires prior authentication which hasn't been performed.
def state_AUTH(self, line): (source)

Handle received lines for the AUTH state in which an authentication challenge response from the client is expected.

Transition back to the COMMAND state. Check the credentials and complete the authorization process with the _cbMailbox callback function on success or the _ebMailbox and _ebUnexpected errback functions on failure.

Parameters
line:bytesThe challenge response.
def state_COMMAND(self, line): (source)

Handle received lines for the COMMAND state in which commands from the client are expected.

Parameters
line:bytesA received command.
def stopProducing(self): (source)

Stop producing data.

This tells a producer that its consumer has died, so it must stop producing data for good.

def successResponse(self, message=''): (source)

Send a response indicating success.

Parameters
message:stringifyable objectAn object whose string representation should be included in the response.
def transformChunk(self, chunk): (source)

Transform a chunk of a message to POP3 message format.

Make sure each line ends with '\r\n' and byte-stuff the termination character ('.') by adding an extra one when one appears at the beginning of a line.

Parameters
chunk:bytesA string to transform.
Returns
bytesThe transformed string.

Undocumented

Value
[b'CAPA', b'USER', b'PASS', b'APOP', b'AUTH', b'RPOP', b'QUIT']
blocked: None or list of 2-tuple of (1) bytes (2) tuple of bytes = (source)

A list of blocked commands. While a response to a command is being generated by the server, other commands are blocked. When no command is outstanding, blocked is set to none. Otherwise, it contains a list of information about blocked commands. Each list entry consists of the command and the arguments to the command.

factory: IServerFactory provider = (source)

A server factory which provides an interface for querying capabilities of the server.

An APOP challenge. If not set, an APOP challenge string will be generated when a connection is made.

mbox: IMailbox provider = (source)

The mailbox for the authenticated user.

A portal for authentication.

schedule: callable that takes interator and returns Deferred = (source)

A callable that arranges for an iterator to be cooperatively iterated over along with all other iterators which have been passed to it such that runtime is divided between all of them. It returns a deferred which fires when the iterator finishes.

The state which indicates what type of messages are expected from the client. Valid states are 'COMMAND' and 'AUTH'

The number of seconds to wait for a command from the client before disconnecting.

def _cbMailbox(self, result, user): (source)

Complete successful authentication.

Save the mailbox and logout function for the authenticated user and send a successful response to the client.

Parameters
result:tupleThe first item of the tuple is a zope.interface.Interface which is the interface supported by the avatar. The second item of the tuple is a IMailbox provider which is the mailbox for the authenticated user. The third item of the tuple is a no-argument callable which is a function to be invoked when the session is terminated.
user:bytesThe user being authenticated.
def _coiterate(self, gen): (source)

Direct the output of an iterator to the transport and arrange for iteration to take place.

Parameters
gen:iterable which yields bytesAn iterator over strings.
Returns
DeferredA deferred which fires when the iterator finishes.
def _ebMailbox(self, failure): (source)

Handle an expected authentication failure.

Send an appropriate error response for a LoginDenied or LoginFailed authentication failure.

Parameters
failure:FailureThe authentication error.
def _ebUnexpected(self, failure): (source)

Handle an unexpected authentication failure.

Send an error response for an unexpected authentication failure.

Parameters
failure:FailureThe authentication error.
def _getMessageFile(self, i): (source)

Retrieve the size and contents of a message.

Parameters
i:bytesA 1-based message index.
Returns
Deferred which successfully fires with 2-tuple of (1) int, (2) file-like objectA deferred which successfully fires with the size of the message and a file containing the contents of the message.
def _longOperation(self, d): (source)

Stop timeouts and block further command processing while a long operation completes.

Parameters
d:DeferredA deferred which triggers at the completion of a long operation.
Returns
DeferredA deferred which triggers after command processing resumes and timeouts restart after the completion of a long operation.
def _sendMessageContent(self, i, fpWrapper, successResponse): (source)

Send the contents of a message.

Parameters
i:bytesA 1-based message index.
fpWrapper:callable that takes a file-like object and returns a file-like object
successResponse:callable that takes int and returns bytes
Returns
DeferredA deferred which triggers after the message has been sent.
def _unblock(self, _): (source)

Process as many blocked commands as possible.

If there are no more blocked commands, set up for the next command to be sent immediately.

Parameters
_:objectIgnored.

Authorization credentials.

_highest: int = (source)

The 1-based index of the highest message retrieved.

_onLogout: no-argument callable or None = (source)

The function to be executed when the connection is lost.

The username sent with the USER command.