twisted.mail.pop3.POP3 : API documentation

class documentation

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

Known subclasses: twisted.mail.protocols.VirtualPOP3

Implements interfaces: twisted.internet.interfaces.IProducer

A POP3 server protocol.

Instance Variable	portal	A portal for authentication.
Instance Variable	factory	A server factory which provides an interface for querying capabilities of the server.
Instance Variable	timeOut	The number of seconds to wait for a command from the client before disconnecting.
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	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	state	The state which indicates what type of messages are expected from the client. Valid states are 'COMMAND' and 'AUTH'
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. Each list entry consists of the command and the arguments to the command.
Class Variable	AUTH_CMDS	Undocumented
Method	connectionMade	Send a greeting to the client after the connection has been made.
Method	connectionLost	Clean up when the connection has been lost.
Method	generateMagic	Generate an APOP challenge.
Method	successResponse	Send a response indicating success.
Method	failResponse	Send a response indicating failure.
Method	lineReceived	Pass a received line to a state machine function.
Method	state_COMMAND	Handle received lines for the COMMAND state in which commands from the client are expected.
Method	processCommand	Dispatch a command from the client for handling.
Method	listCapabilities	Return a list of server capabilities suitable for use in a CAPA response.
Method	do_CAPA	Handle a CAPA command.
Method	do_AUTH	Handle an AUTH command.
Method	state_AUTH	Handle received lines for the AUTH state in which an authentication challenge response from the client is expected.
Method	do_APOP	Handle an APOP command.
Method	do_USER	Handle a USER command.
Method	do_PASS	Handle a PASS command.
Method	do_STAT	Handle a STAT command.
Method	do_LIST	Handle a LIST command.
Method	do_UIDL	Handle a UIDL command.
Method	do_TOP	Handle a TOP command.
Method	do_RETR	Handle a RETR command.
Method	transformChunk	Transform a chunk of a message to POP3 message format.
Method	finishedFileTransfer	Send the termination sequence.
Method	do_DELE	Handle a DELE command.
Method	do_NOOP	Handle a NOOP command.
Method	do_RSET	Handle a RSET command.
Method	do_LAST	Handle a LAST command.
Method	do_RPOP	Handle an RPOP command.
Method	do_QUIT	Handle a QUIT command.
Method	authenticateUserAPOP	Perform APOP authentication.
Method	authenticateUserPASS	Perform authentication for a username/password login.
Method	stopProducing	Stop producing data.
Instance Variable	_userIs	The username sent with the USER command.
Instance Variable	_onLogout	The function to be executed when the connection is lost.
Instance Variable	_highest	The 1-based index of the highest message retrieved.
Instance Variable	_auth	Authorization credentials.
Method	_unblock	Process as many blocked commands as possible.
Method	_cbMailbox	Complete successful authentication.
Method	_ebMailbox	Handle an expected authentication failure.
Method	_ebUnexpected	Handle an unexpected authentication failure.
Method	_longOperation	Stop timeouts and block further command processing while a long operation completes.
Method	_coiterate	Direct the output of an iterator to the transport and arrange for iteration to take place.
Method	_getMessageFile	Retrieve the size and contents of a message.
Method	_sendMessageContent	Send the contents of a message.

Inherited from LineOnlyReceiver:

Class Variable	delimiter	The line-ending delimiter to use. By default this is `b'\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.
Method	lineLengthExceeded	Called when the maximum line length has been reached. Override if it needs to be dealt with in some special way.
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):

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

Inherited from TimeoutMixin:

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.
Instance Variable	__timeoutCall	Undocumented
Method	__timedOut	Undocumented

portal = (source)

A portal for authentication.

(type: Portal)

factory = (source)

overrides twisted.internet.protocol.Protocol.factory

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

(type: IServerFactory provider)

timeOut = (source)

overrides twisted.protocols.policies.TimeoutMixin.timeOut

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

(type: int)

schedule = (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.

(type: callable that takes interator and returns Deferred)

magic = (source)

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

(type: bytes or None)

_userIs = (source)

The username sent with the USER command.

(type: bytes or None)

_onLogout = (source)

The function to be executed when the connection is lost.

(type: no-argument callable or None)

mbox = (source)

The mailbox for the authenticated user.

(type: IMailbox provider)

state = (source)

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

(type: bytes)

blocked = (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.

(type: None or list of 2-tuple of (1) bytes (2) tuple of bytes)

_highest = (source)

The 1-based index of the highest message retrieved.

(type: int)

_auth = (source)

Authorization credentials.

(type: IUsernameHashedPassword provider)

AUTH_CMDS = (source)

Undocumented

(type: list[bytes])

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 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 The reason the connection was terminated. (type: Failure)

def generateMagic(self): (source)

Generate an APOP challenge.

Returns An RFC 822 message id format string. (type: bytes)

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

Send a response indicating success.

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

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

Send a response indicating failure.

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

def lineReceived(self, line): (source)

overrides twisted.protocols.basic.LineOnlyReceiver.lineReceived

Pass a received line to a state machine function.

Parameters line A received line. (type: bytes)

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 _ Ignored. (type: object)

def state_COMMAND(self, line): (source)

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

Parameters line A received command. (type: bytes)

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

Dispatch a command from the client for handling.

Parameters	command	A POP3 command. (type: `bytes`)
	args	Arguments to the command. (type: `tuple` of `bytes`)
Raises	POP3Error	When the command is invalid or the command requires prior authentication which hasn't been performed.

def listCapabilities(self): (source)

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

Returns A list of server capabilities. (type: list of bytes)

def do_CAPA(self): (source)

Handle a CAPA command.

Respond with the server capabilities.

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 The name of an authentication mechanism. (type: bytes or None)

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 The challenge response. (type: bytes)

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	A username. (type: `bytes`)
	digest	An MD5 digest string. (type: `bytes`)

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	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. (type: `tuple`)
	user	The user being authenticated. (type: `bytes`)

def _ebMailbox(self, failure): (source)

Handle an expected authentication failure.

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

Parameters failure The authentication error. (type: Failure)

def _ebUnexpected(self, failure): (source)

Handle an unexpected authentication failure.

Send an error response for an unexpected authentication failure.

Parameters failure The authentication error. (type: Failure)

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 A username. (type: bytes)

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	A password. (type: `bytes`)
	words	Other parts of the password split by spaces. (type: `tuple` of `bytes`)

def _longOperation(self, d): (source)

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

Parameters	d	A deferred which triggers at the completion of a long operation. (type: `Deferred`)
Returns	A deferred which triggers after command processing resumes and timeouts restart after the completion of a long operation. (type: `Deferred`)

def _coiterate(self, gen): (source)

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

Parameters	gen	An iterator over strings. (type: iterable which yields `bytes`)
Returns	A deferred which fires when the iterator finishes. (type: `Deferred`)

def do_STAT(self): (source)

Handle a STAT command.

Returns A deferred which triggers after the response to the STAT command has been issued. (type: Deferred)

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

Handle a LIST command.

Parameters	i	A 1-based message index. (type: `bytes` or `None`)
Returns	A deferred which triggers after the response to the LIST command has been issued. (type: `Deferred`)

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

Handle a UIDL command.

Parameters	i	A 1-based message index. (type: `bytes` or `None`)
Returns	A deferred which triggers after the response to the UIDL command has been issued. (type: `Deferred`)

def _getMessageFile(self, i): (source)

Retrieve the size and contents of a message.

Parameters	i	A 1-based message index. (type: `bytes`)
Returns	A deferred which successfully fires with the size of the message and a file containing the contents of the message. (type: `Deferred` which successfully fires with 2-`tuple` of (1) `int`, (2) file-like object)

def _sendMessageContent(self, i, fpWrapper, successResponse): (source)

Send the contents of a message.

Parameters	i	A 1-based message index. (type: `bytes`)
	fpWrapper	(type: callable that takes a file-like object and returns a file-like object)
	successResponse	(type: callable that takes `int` and returns `bytes`)
Returns	A deferred which triggers after the message has been sent. (type: `Deferred`)

def do_TOP(self, i, size): (source)

Handle a TOP command.

Parameters	i	A 1-based message index. (type: `bytes`)
	size	The number of lines of the message to retrieve. (type: `bytes`)
Returns	A deferred which triggers after the response to the TOP command has been issued. (type: `Deferred`)

def do_RETR(self, i): (source)

Handle a RETR command.

Parameters	i	A 1-based message index. (type: `bytes`)
Returns	A deferred which triggers after the response to the RETR command has been issued. (type: `Deferred`)

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	A string to transform. (type: `bytes`)
Returns	The transformed string. (type: `bytes`)

def finishedFileTransfer(self, lastsent): (source)

Send the termination sequence.

Parameters lastsent The last character of the file. (type: bytes)

def do_DELE(self, i): (source)

Handle a DELE command.

Mark a message for deletion and issue a successful response.

Parameters i A 1-based message index. (type: int)

def do_NOOP(self): (source)

Handle a NOOP command.

Do nothing but issue a successful response.

def do_RSET(self): (source)

Handle a RSET command.

Unmark any messages that have been flagged for deletion.

def do_LAST(self): (source)

Handle a LAST command.

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

def do_RPOP(self, user): (source)

Handle an RPOP command.

RPOP is not supported. Send an error response.

Parameters user A username. (type: bytes)

def do_QUIT(self): (source)

Handle a QUIT command.

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

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

overridden in twisted.mail.protocols.VirtualPOP3

Perform APOP authentication.

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

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.

API Documentation for Twisted, generated by pydoctor 20.12.1 at 2021-02-28 19:53:36.