class documentation

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

Known subclasses: twisted.mail.protocols.VirtualPOP3

Implements interfaces: twisted.internet.interfaces.IProducer

View In Hierarchy

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)
A server factory which provides an interface for querying capabilities of the server.
(type: IServerFactory provider)
timeOut = (source)
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)

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

def connectionLost(self, reason): (source)

Clean up when the connection has been lost.

ParametersreasonThe reason the connection was terminated. (type: Failure)
def generateMagic(self): (source)

Generate an APOP challenge.

ReturnsAn RFC 822 message id format string. (type: bytes)
def successResponse(self, message=''): (source)

Send a response indicating success.

ParametersmessageAn object whose string representation should be included in the response. (type: stringifyable object)
def failResponse(self, message=b''): (source)

Send a response indicating failure.

ParametersmessageAn object whose string representation should be included in the response. (type: stringifyable object)
def lineReceived(self, line): (source)

Pass a received line to a state machine function.

ParameterslineA 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.

ParameterslineA received command. (type: bytes)
def processCommand(self, command, *args): (source)

Dispatch a command from the client for handling.

ParameterscommandA POP3 command. (type: bytes)
argsArguments to the command. (type: tuple of bytes)
RaisesPOP3ErrorWhen 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.

ReturnsA 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.

ParametersargsThe 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.

ParameterslineThe 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.

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

ParametersresultThe 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)
userThe 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.

ParametersfailureThe authentication error. (type: Failure)
def _ebUnexpected(self, failure): (source)

Handle an unexpected authentication failure.

Send an error response for an unexpected authentication failure.

ParametersfailureThe 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.

ParametersuserA 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.

ParameterspasswordA password. (type: bytes)
wordsOther 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.

ParametersdA deferred which triggers at the completion of a long operation. (type: Deferred)
ReturnsA 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.

ParametersgenAn iterator over strings. (type: iterable which yields bytes)
ReturnsA deferred which fires when the iterator finishes. (type: Deferred)
def do_STAT(self): (source)

Handle a STAT command.

ReturnsA 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.

ParametersiA 1-based message index. (type: bytes or None)
ReturnsA 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.

ParametersiA 1-based message index. (type: bytes or None)
ReturnsA 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.

ParametersiA 1-based message index. (type: bytes)
ReturnsA 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.

ParametersiA 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)
ReturnsA deferred which triggers after the message has been sent. (type: Deferred)
def do_TOP(self, i, size): (source)

Handle a TOP command.

ParametersiA 1-based message index. (type: bytes)
sizeThe number of lines of the message to retrieve. (type: bytes)
ReturnsA 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.

ParametersiA 1-based message index. (type: bytes)
ReturnsA 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.

ParameterschunkA string to transform. (type: bytes)
ReturnsThe transformed string. (type: bytes)
def finishedFileTransfer(self, lastsent): (source)

Send the termination sequence.

ParameterslastsentThe 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.

ParametersiA 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.

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

Perform APOP authentication.

ParametersuserThe name of the user attempting to log in. (type: bytes)
digestThe challenge response. (type: bytes)
ReturnsA 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)
Raisescred.error.UnauthorizedLoginWhen authentication fails.
def authenticateUserPASS(self, user, password): (source)

Perform authentication for a username/password login.

ParametersuserThe name of the user attempting to log in. (type: bytes)
passwordThe password to authenticate with. (type: bytes)
ReturnsA 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)
Raisescred.error.UnauthorizedLoginWhen authentication fails.
def stopProducing(self): (source)

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.