Movatterモバイル変換

18.8.1 FTP Objects

Several methods are available in two flavors: one for handling textfiles and another for binary files. These are named for the commandwhich is used followed by "lines" for the text version or"binary" for the binary version.

FTP instances have the following methods:

set_debuglevel( level): Set the instance's debugging level. This controls the amount ofdebugging output printed. The default,0, produces nodebugging output. A value of1 produces a moderate amount ofdebugging output, generally a single line per request. A value of2 or higher produces the maximum amount of debugging output,logging each line sent and received on the control connection.

connect( host[, port]): Connect to the given host and port. The default port number is21, asspecified by the FTP protocol specification. It is rarely needed tospecify a different port number. This function should be called onlyonce for each instance; it should not be called at all if a host wasgiven when the instance was created. All other methods can only beused after a connection has been made.

getwelcome( ): Return the welcome message sent by the server in reply to the initialconnection. (This message sometimes contains disclaimers or helpinformation that may be relevant to the user.)

login( [user[, passwd[, acct]]]): Log in as the givenuser. Thepasswd andacctparameters are optional and default to the empty string. If nouser is specified, it defaults to'anonymous'. Ifuser is'anonymous', the defaultpasswd is'anonymous@'. This function should be called onlyonce for each instance, after a connection has been established; itshould not be called at all if a host and user were given when theinstance was created. Most FTP commands are only allowed after theclient has logged in.

abort( ): Abort a file transfer that is in progress. Using this does not alwayswork, but it's worth a try.

sendcmd( command): Send a simple command string to the server and return the responsestring.

voidcmd( command): Send a simple command string to the server and handle the response.Return nothing if a response code in the range 200-299 is received.Raise an exception otherwise.

retrbinary( command, callback[, maxblocksize[, rest]]): Retrieve a file in binary transfer mode.command should be anappropriate "RETR" command:'RETRfilename'.Thecallback function is called for each block of data received,with a single string argument giving the data block.The optionalmaxblocksize argument specifies the maximum chunk size toread on the low-level socket object created to do the actual transfer(which will also be the largest size of the data blocks passed tocallback). A reasonable default is chosen.rest means thesame thing as in thetransfercmd() method.

retrlines( command[, callback]): Retrieve a file or directory listing in ASCII transfer mode.command should be an appropriate "RETR" command (seeretrbinary()) or a "LIST" command (usually just the string'LIST'). Thecallback function is called for each line,with the trailing CRLF stripped. The defaultcallback printsthe line tosys.stdout.

set_pasv( boolean): Enable ``passive'' mode ifboolean is true, other disablepassive mode. (In Python 2.0 and before, passive mode was off bydefault; in Python 2.1 and later, it is on by default.)

storbinary( command, file[, blocksize]): Store a file in binary transfer mode.command should be anappropriate "STOR" command:"STORfilename".file is an open file object which is read until EOF using itsread() method in blocks of sizeblocksize to provide thedata to be stored. Theblocksize argument defaults to 8192.Changed in version 2.1:default forblocksize added.

storlines( command, file): Store a file in ASCII transfer mode.command should be anappropriate "STOR" command (seestorbinary()). Lines areread until EOF from the open file objectfile using itsreadline() method to provide the data to be stored.

transfercmd( cmd[, rest]): Initiate a transfer over the data connection. If the transfer isactive, send a "EPRT" or "PORT" command and the transfer command specifiedbycmd, and accept the connection. If the server is passive,send a "EPSV" or "PASV" command, connect to it, and start the transfercommand. Either way, return the socket for the connection.
If optionalrest is given, a "REST" command issent to the server, passingrest as an argument.rest isusually a byte offset into the requested file, telling the server torestart sending the file's bytes at the requested offset, skippingover the initial bytes. Note however that RFC959 requires only thatrest be a string containing charactersin the printable range from ASCII code 33 to ASCII code 126. Thetransfercmd() method, therefore, convertsrest to a string, but no check isperformed on the string's contents. If the server doesnot recognize the "REST" command, anerror_reply exception will be raised. If this happens,simply calltransfercmd() without arest argument.

ntransfercmd( cmd[, rest]): Liketransfercmd(), but returns a tuple of the dataconnection and the expected size of the data. If the expected sizecould not be computed,None will be returned as the expectedsize.cmd andrest means the same thing as intransfercmd().

nlst( argument[, ...]): Return a list of files as returned by the "NLST" command. Theoptionalargument is a directory to list (default is the currentserver directory). Multiple arguments can be used to passnon-standard options to the "NLST" command.

dir( argument[, ...]): Produce a directory listing as returned by the "LIST" command,printing it to standard output. The optionalargument is adirectory to list (default is the current server directory). Multiplearguments can be used to pass non-standard options to the "LIST"command. If the last argument is a function, it is used as acallback function as forretrlines(); the defaultprints tosys.stdout. This method returnsNone.

rename( fromname, toname): Rename filefromname on the server totoname.

delete( filename): Remove the file namedfilename from the server. If successful,returns the text of the response, otherwise raiseserror_perm on permission errors orerror_reply on other errors.

cwd( pathname): Set the current directory on the server.

mkd( pathname): Create a new directory on the server.

pwd( ): Return the pathname of the current directory on the server.

rmd( dirname): Remove the directory nameddirname on the server.

size( filename): Request the size of the file namedfilename on the server. Onsuccess, the size of the file is returned as an integer, otherwiseNone is returned. Note that the "SIZE" command is not standardized, but is supported by many common server implementations.

quit( ): Send a "QUIT" command to the server and close the connection.This is the ``polite'' way to close a connection, but it may raise anexception of the server reponds with an error to the"QUIT" command. This implies a call to theclose()method which renders theFTP instance useless for subsequentcalls (see below).

close( ): Close the connection unilaterally. This should not be applied to analready closed connection such as after a successful call toquit(). After this call theFTP instance should notbe used any more (after a call toclose() orquit() you cannot reopen the connection by issuing anotherlogin() method).

Release 2.5.2, documentation updated on 21st February, 2008.

SeeAbout this document... for information on suggesting changes.

[8]ページ先頭