twisted.protocols.ftp.FTPClient

class documentation

class FTPClient(FTPClientBasic): (source)

Constructor: FTPClient(username, password, passive)

FTPClient is a client implementation of the FTP protocol which exposes FTP commands as methods which return Deferreds.

Each command method returns a Deferred which is called back when a successful response code (2xx or 3xx) is received from the server or which is error backed if an error response code (4xx or 5xx) is received from the server or if a protocol violation occurs. If an error response code is received, the Deferred fires with a Failure wrapping a CommandFailed instance. The CommandFailed instance is created with a list of the response lines received from the server.

See RFC 959 for error code definitions.

Both active and passive transfers are supported.

Method	`__init__`	Constructor.
Method	`cdup`	Issues the CDUP (Change Directory UP) command.
Method	`cwd`	Issues the CWD (Change Working Directory) command.
Method	`escapePath`	Returns a FTP escaped path (replace newlines with nulls).
Method	`fail`	Disconnect, and also give an error to any queued deferreds.
Method	`generatePortCommand`	(Private) Generates the text of a given PORT command.
Method	`getDirectory`	Returns the current remote directory.
Method	`list`	Retrieve a file listing into the given protocol instance.
Method	`makeDirectory`	Make a directory
Method	`nlst`	Retrieve a short file listing into the given protocol instance.
Method	`pwd`	Issues the PWD (Print Working Directory) command.
Method	`queueLogin`	Login: send the username, send the password, and set retrieval mode to binary
Method	`quit`	Issues the QUIT command.
Method	`receiveFromConnection`	Retrieves a file or listing generated by the given command, feeding it to the given protocol.
Method	`removeDirectory`	Delete a directory on the server.
Method	`removeFile`	Delete a file on the server.
Method	`rename`	Rename a file.
Method	`retrieveFile`	Retrieve a file from the given path
Method	`sendToConnection`	XXX
Method	`storeFile`	Store a file at the given path.
Instance Variable	`passive`	See description in __init__.
Method	`_openDataConnection`	This method returns a DeferredList.

Inherited from FTPClientBasic:

Method	`connectionLost`	Called when the connection is shut down.
Method	`lineReceived`	(Private) Parses the response messages from the FTP server.
Method	`popCommandQueue`	Return the front element of the command queue, or None if empty.
Method	`queueCommand`	Add an FTPCommand object to the queue.
Method	`queueStringCommand`	Queues a string to be issued as an FTP command
Method	`sendLine`	Sends a line, unless line is None.
Method	`sendNextCommand`	(Private) Processes the next command in the queue.
Class Variable	`debug`	Undocumented
Instance Variable	`actionQueue`	Undocumented
Instance Variable	`greeting`	Undocumented
Instance Variable	`nextDeferred`	Undocumented
Instance Variable	`response`	Undocumented
Method	`_cb_greeting`	Undocumented
Method	`_fail`	Errback all queued deferreds.
Class Variable	`_encoding`	Undocumented
Instance Variable	`_failed`	Undocumented

Inherited from LineReceiver (via FTPClientBasic):

Method	`clearLineBuffer`	Clear buffered data.
Method	`dataReceived`	Protocol.dataReceived. Translates bytes into lines, and calls lineReceived (or rawDataReceived, depending on mode.)
Method	`lineLengthExceeded`	Called when the maximum line length has been reached. Override if it needs to be dealt with in some special way.
Method	`rawDataReceived`	Override this for when raw data is received.
Method	`setLineMode`	Sets the line-mode of this receiver.
Method	`setRawMode`	Sets the raw mode of this receiver. Further data received will be sent to rawDataReceived rather than lineReceived.
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	`line_mode`	Undocumented
Instance Variable	`_buffer`	Undocumented
Instance Variable	`_busyReceiving`	Undocumented

Inherited from Protocol (via FTPClientBasic, LineReceiver):

Method	`logPrefix`	Return a prefix matching the class name, to identify log messages related to this protocol instance.
Class Variable	`factory`	Undocumented

Inherited from BaseProtocol (via FTPClientBasic, LineReceiver, Protocol):

Method	`connectionMade`	Called when a connection is made.
Method	`makeConnection`	Make a connection to a transport and a server.
Instance Variable	`connected`	Undocumented
Instance Variable	`transport`	Undocumented

Inherited from _PauseableMixin (via FTPClientBasic, LineReceiver, Protocol, BaseProtocol):

Method	`pauseProducing`	Undocumented
Method	`resumeProducing`	Undocumented
Method	`stopProducing`	Undocumented
Instance Variable	`paused`	Undocumented

def __init__(self, username='anonymous', password='twisted@twistedmatrix.com', passive=1): (source) ¶

overrides twisted.protocols.ftp.FTPClientBasic.__init__

Constructor.

I will login as soon as I receive the welcome message from the server.

Parameters
username	FTP username
password	FTP password
passive	flag that controls if I use active or passive data connections. You can also change this after construction by assigning to `self.passive`.

def cdup(self): (source) ¶

Issues the CDUP (Change Directory UP) command.

Returns
a `Deferred` that will be called when done.

def cwd(self, path): (source) ¶

Issues the CWD (Change Working Directory) command.

Returns
a `Deferred` that will be called when done.

def escapePath(self, path): (source) ¶

Returns a FTP escaped path (replace newlines with nulls).

def fail(self, error): (source) ¶

overrides twisted.protocols.ftp.FTPClientBasic.fail

Disconnect, and also give an error to any queued deferreds.

def generatePortCommand(self, portCmd): (source) ¶

(Private) Generates the text of a given PORT command.

def getDirectory(self): (source) ¶

Returns the current remote directory.

Returns
a `Deferred` that will be called back with a `str` giving the remote directory or which will errback with `CommandFailed` if an error response is returned.

def list(self, path, protocol): (source) ¶

Retrieve a file listing into the given protocol instance.

This method issues the 'LIST' FTP command.

Parameters
path	path to get a file listing for.
protocol	a `Protocol` instance, probably a `FTPFileListProtocol` instance. It can cope with most common file listing formats.
Returns
`Deferred`

def makeDirectory(self, path): (source) ¶

Make a directory

This method issues the MKD command.

Parameters
path:`str`	The path to the directory to create.
Returns
`Deferred`	A `Deferred` which fires when the server responds. If the directory is created, the `Deferred` is called back with the server response. If the server response indicates the directory was not created, the `Deferred` is errbacked with a `Failure` wrapping `CommandFailed` or `BadResponse`.
Present Since
8.2

def nlst(self, path, protocol): (source) ¶

Retrieve a short file listing into the given protocol instance.

This method issues the 'NLST' FTP command.

NLST (should) return a list of filenames, one per line.

Parameters
path	path to get short file listing for.
protocol	a `Protocol` instance.

def pwd(self): (source) ¶

Issues the PWD (Print Working Directory) command.

The getDirectory does the same job but automatically parses the result.

Returns
a `Deferred` that will be called when done. It is up to the caller to interpret the response, but the `parsePWDResponse` method in this module should work.

def queueLogin(self, username, password): (source) ¶

overrides twisted.protocols.ftp.FTPClientBasic.queueLogin

def quit(self): (source) ¶

Issues the QUIT command.

Returns
A `Deferred` that fires when the server acknowledges the QUIT command. The transport should not be disconnected until this `Deferred` fires.

def receiveFromConnection(self, commands, protocol): (source) ¶

Retrieves a file or listing generated by the given command, feeding it to the given protocol.

Parameters
commands	list of strings of FTP commands to execute then receive the results of (e.g. `LIST`, `RETR`)
protocol	A `Protocol` instance e.g. an `FTPFileListProtocol`, or something that can be adapted to one. Typically this will be an `IConsumer` implementation.
Returns
`Deferred`.

def removeDirectory(self, path): (source) ¶

Delete a directory on the server.

removeDirectory issues a RMD command to the server to remove the indicated directory. Described in RFC959.

Parameters
path:`str`	The path to the directory to delete. May be relative to the current working directory.
Returns
`Deferred`	A `Deferred` which fires when the server responds. On error, it is errbacked with either `CommandFailed` or `BadResponse`. On success, it is called back with a list of response lines.
Present Since
11.1

def removeFile(self, path): (source) ¶

Delete a file on the server.

removeFile issues a DELE command to the server to remove the indicated file. Note that this command cannot remove a directory.

Parameters
path:`str`	The path to the file to delete. May be relative to the current dir.
Returns
`Deferred`	A `Deferred` which fires when the server responds. On error, it is errbacked with either `CommandFailed` or `BadResponse`. On success, it is called back with a list of response lines.
Present Since
8.2

def rename(self, pathFrom, pathTo): (source) ¶

Rename a file.

This method issues the RNFR/RNTO command sequence to rename pathFrom to pathTo.

Parameters
pathFrom:`str`	the absolute path to the file to be renamed
pathTo:`str`	the absolute path to rename the file to.
Returns
`Deferred`	A `Deferred` which fires when the rename operation has succeeded or failed. If it succeeds, the `Deferred` is called back with a two-tuple of lists. The first list contains the responses to the RNFR command. The second list contains the responses to the RNTO command. If either RNFR or RNTO fails, the `Deferred` is errbacked with `CommandFailed` or `BadResponse`.
Present Since
8.2

def retrieveFile(self, path, protocol, offset=0): (source) ¶

Retrieve a file from the given path

This method issues the 'RETR' FTP command.

The file is fed into the given Protocol instance. The data connection will be passive if self.passive is set.

Parameters
path	path to file that you wish to receive.
protocol	a `Protocol` instance.
offset	offset to start downloading from
Returns
`Deferred`

def sendToConnection(self, commands): (source) ¶

XXX

Returns

A tuple of two Deferreds:

Deferred IFinishableConsumer. You must call the finish method on the IFinishableConsumer when the file is completely transferred.
Deferred list of control-connection responses.

def storeFile(self, path, offset=0): (source) ¶

Store a file at the given path.

This method issues the 'STOR' FTP command.

Returns

A tuple of two Deferreds:

Deferred IFinishableConsumer. You must call the finish method on the IFinishableConsumer when the file is completely transferred.
Deferred list of control-connection responses.

passive = (source) ¶

See description in __init__.

def _openDataConnection(self, commands, protocol): (source) ¶

This method returns a DeferredList.