twisted.mail.pop3.POP3

class documentation

class POP3(basic.LineOnlyReceiver, policies.TimeoutMixin): (source)

Known subclasses: twisted.mail.protocols.VirtualPOP3

Implements interfaces: twisted.internet.interfaces.IProducer

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) ¶

overridden in twisted.mail.protocols.VirtualPOP3

Perform APOP authentication.

Parameters
user:`bytes`	The name of the user attempting to log in.
digest:`bytes`	The challenge response.
Returns
`Deferred` which successfully results in 3-`tuple` of (1) `IMailbox`, (2) `IMailbox` provider, (3) no-argument callable	A 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.UnauthorizedLogin`	When authentication fails.

def authenticateUserPASS(self, user, password): (source) ¶

overridden in twisted.mail.protocols.VirtualPOP3

Perform authentication for a username/password login.

Parameters
user:`bytes`	The name of the user attempting to log in.
password:`bytes`	The password to authenticate with.
Returns
`Deferred` which successfully results in 3-`tuple` of (1) `IMailbox`, (2) `IMailbox` provider, (3) no-argument callable	A 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.UnauthorizedLogin`	When authentication fails.

def connectionLost(self, reason): (source) ¶

from twisted.internet.interfaces.IProtocol

overrides twisted.internet.protocol.Protocol.connectionLost

Clean up when the connection has been lost.

Parameters
reason:`Failure`	The reason the connection was terminated.

def connectionMade(self): (source) ¶

from twisted.internet.interfaces.IProtocol

overrides twisted.internet.protocol.BaseProtocol.connectionMade

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:`bytes`	A username.
digest:`bytes`	An 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 `None`	The 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:`int`	A 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 `None`	A 1-based message index.
Returns
`Deferred`	A 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:`bytes`	A password.
*words:`tuple` of `bytes`	Other 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:`bytes`	A 1-based message index.
Returns
`Deferred`	A 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:`bytes`	A 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
`Deferred`	A 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:`bytes`	A 1-based message index.
size:`bytes`	The number of lines of the message to retrieve.
Returns
`Deferred`	A 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 `None`	A 1-based message index.
Returns
`Deferred`	A 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:`bytes`	A username.

def failResponse(self, message=b''): (source) ¶

Send a response indicating failure.

Parameters
message:stringifyable `object`	An object whose string representation should be included in the response.

def finishedFileTransfer(self, lastsent): (source) ¶

Send the termination sequence.

Parameters
lastsent:`bytes`	The last character of the file.

def generateMagic(self): (source) ¶

Generate an APOP challenge.

Returns
`bytes`	An RFC 822 message id format string.

def lineReceived(self, line): (source) ¶

overrides twisted.protocols.basic.LineOnlyReceiver.lineReceived

Pass a received line to a state machine function.

Parameters
line:`bytes`	A received line.

def listCapabilities(self): (source) ¶

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

Returns
`list` of `bytes`	A list of server capabilities.

def processCommand(self, command, *args): (source) ¶

Dispatch a command from the client for handling.

Parameters
command:`bytes`	A POP3 command.
*args:`tuple` of `bytes`	Arguments to the command.
Raises
`POP3Error`	When 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:`bytes`	The 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:`bytes`	A received command.

def stopProducing(self): (source) ¶

from twisted.internet.interfaces.IProducer

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 `object`	An 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:`bytes`	A string to transform.
Returns
`bytes`	The transformed string.

AUTH_CMDS: list[bytes] = (source) ¶

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) ¶

overrides twisted.internet.protocol.Protocol.factory

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

magic: bytes or None = (source) ¶

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.

portal: Portal = (source) ¶

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.

state: bytes = (source) ¶

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

timeOut: int = (source) ¶

overrides twisted.protocols.policies.TimeoutMixin.timeOut

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:`tuple`	The 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:`bytes`	The 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 `bytes`	An iterator over strings.
Returns
`Deferred`	A 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:`Failure`	The authentication error.

def _ebUnexpected(self, failure): (source) ¶

Handle an unexpected authentication failure.

Send an error response for an unexpected authentication failure.

Parameters
failure:`Failure`	The authentication error.

def _getMessageFile(self, i): (source) ¶

Retrieve the size and contents of a message.

Parameters
i:`bytes`	A 1-based message index.
Returns
`Deferred` which successfully fires with 2-`tuple` of (1) `int`, (2) file-like object	A 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:`Deferred`	A deferred which triggers at the completion of a long operation.
Returns
`Deferred`	A 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:`bytes`	A 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
`Deferred`	A 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
_:`object`	Ignored.

_auth: IUsernameHashedPassword provider = (source) ¶

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.

_userIs: bytes or None = (source) ¶

The username sent with the USER command.