ftplib
— FTP 프로토콜 클라이언트¶
소스 코드: Lib/ftplib.py
This module defines the class FTP
and a few related items. The
FTP
class implements the client side of the FTP protocol. You can use
this to write Python programs that perform a variety of automated FTP jobs, such
as mirroring other FTP servers. It is also used by the module
urllib.request
to handle URLs that use FTP. For more information on FTP
(File Transfer Protocol), see internet RFC 959.
RFC 2640에 따라, 기본 인코딩은 UTF-8입니다.
Availability: not Emscripten, not WASI.
This module does not work or is not available on WebAssembly platforms
wasm32-emscripten
and wasm32-wasi
. See
WebAssembly platforms for more information.
ftplib
모듈을 사용한 샘플 세션은 다음과 같습니다:
>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org') # connect to host, default port
>>> ftp.login() # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian') # change into "debian" directory
'250 Directory successfully changed.'
>>> ftp.retrlines('LIST') # list directory contents
-rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README
...
drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool
drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project
drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools
'226 Directory send OK.'
>>> with open('README', 'wb') as fp:
>>> ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()
'221 Goodbye.'
Reference¶
FTP objects¶
- class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')¶
Return a new instance of the
FTP
class.- 매개변수:
host (str) – The hostname to connect to. If given,
connect(host)
is implicitly called by the constructor.user (str) – The username to log in with (default:
'anonymous'
). If given,login(host, passwd, acct)
is implicitly called by the constructor.passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or
"-"
, a password will be automatically generated.acct (str) – Account information to be used for the
ACCT
FTP command. Few systems implement this. See RFC-959 for more details.timeout (float | None) – A timeout in seconds for blocking operations like
connect()
(default: the global default timeout setting).source_address (tuple | None) – A 2-tuple
(host, port)
for the socket to bind to as its source address before connecting.encoding (str) – The encoding for directories and filenames (default:
'utf-8'
).
FTP
클래스는with
문을 지원합니다, 예를 들어:>>> from ftplib import FTP >>> with FTP("ftp1.at.proftpd.org") as ftp: ... ftp.login() ... ftp.dir() ... '230 Anonymous login ok, restrictions apply.' dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 . dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 .. dr-xr-xr-x 5 ftp ftp 4096 May 6 10:43 CentOS dr-xr-xr-x 3 ftp ftp 18 Jul 10 2008 Fedora >>>
버전 3.2에서 변경:
with
문에 대한 지원이 추가되었습니다.버전 3.3에서 변경: source_address 매개 변수가 추가되었습니다.
버전 3.9에서 변경: timeout 매개 변수가 0으로 설정되면, 비 블로킹 소켓이 만들어지지 않도록
ValueError
를 발생시킵니다. encoding 매개 변수가 추가되었으며, 기본값은 Latin-1 에서 UTF-8로 변경되어 RFC 2640을 따릅니다.Several
FTP
methods are available in two flavors: one for handling text files and another for binary files. The methods are named for the command which is used followed bylines
for the text version orbinary
for the binary version.FTP
인스턴스에는 다음과 같은 메서드가 있습니다:- set_debuglevel(level)¶
Set the instance’s debugging level as an
int
. This controls the amount of debugging output printed. The debug levels are:0
(default): No debug output.1
: Produce a moderate amount of debug output, generally a single line per request.2
or higher: Produce the maximum amount of debugging output, logging each line sent and received on the control connection.
- connect(host='', port=0, timeout=None, source_address=None)¶
Connect to the given host and port. This function should be called only once for each instance; it should not be called if a host argument was given when the
FTP
instance was created. All otherFTP
methods can only be called after a connection has successfully been made.- 매개변수:
host (str) – The host to connect to.
port (int) – The TCP port to connect to (default:
21
, as specified by the FTP protocol specification). It is rarely needed to specify a different port number.timeout (float | None) – A timeout in seconds for the connection attempt (default: the global default timeout setting).
source_address (tuple | None) – A 2-tuple
(host, port)
for the socket to bind to as its source address before connecting.
인자
self
,host
,port
로 감사 이벤트ftplib.connect
를 발생시킵니다.버전 3.3에서 변경: source_address 매개 변수가 추가되었습니다.
- getwelcome()¶
초기 연결에 대한 응답으로 서버에서 보낸 환영 메시지를 반환합니다. (이 메시지에는 때때로 사용자와 관련될 수 있는 고지 사항이나 도움말 정보가 포함되어 있습니다.)
- login(user='anonymous', passwd='', acct='')¶
Log on to the connected FTP server. This function should be called only once for each instance, after a connection has been established; it should not be called if the host and user arguments were given when the
FTP
instance was created. Most FTP commands are only allowed after the client has logged in.- 매개변수:
user (str) – The username to log in with (default:
'anonymous'
).passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or
"-"
, a password will be automatically generated.acct (str) – Account information to be used for the
ACCT
FTP command. Few systems implement this. See RFC-959 for more details.
- abort()¶
진행 중인 파일 전송을 중단합니다. 이것을 사용하는 것이 항상 동작하지는 않지만, 시도해 볼 가치가 있습니다.
- voidcmd(cmd)¶
Send a simple command string to the server and handle the response. Return the response string if the response code corresponds to success (codes in the range 200–299). Raise
error_reply
otherwise.인자
self
,cmd
로 감사 이벤트ftplib.sendcmd
를 발생시킵니다.
- retrbinary(cmd, callback, blocksize=8192, rest=None)¶
Retrieve a file in binary transfer mode.
- 매개변수:
cmd (str) – An appropriate
STOR
command:"STOR filename"
.callback (callable) – A single parameter callable that is called for each block of data received, with its single argument being the data as
bytes
.blocksize (int) – The maximum chunk size to read on the low-level
socket
object created to do the actual transfer. This also corresponds to the largest size of data that will be passed to callback. Defaults to8192
.rest (int) – A
REST
command to be sent to the server. See the documentation for the rest parameter of thetransfercmd()
method.
- retrlines(cmd, callback=None)¶
Retrieve a file or directory listing in the encoding specified by the encoding parameter at initialization. cmd should be an appropriate
RETR
command (seeretrbinary()
) or a command such asLIST
orNLST
(usually just the string'LIST'
).LIST
retrieves a list of files and information about those files.NLST
retrieves a list of file names. The callback function is called for each line with a string argument containing the line with the trailing CRLF stripped. The default callback prints the line tosys.stdout
.
- set_pasv(val)¶
val이 참이면 “수동(passive)” 모드를 활성화하고, 그렇지 않으면 수동 모드를 비활성화합니다. 수동 모드는 기본적으로 켜져 있습니다.
- storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)¶
Store a file in binary transfer mode.
- 매개변수:
cmd (str) – An appropriate
STOR
command:"STOR filename"
.fp (file object) – A file object (opened in binary mode) which is read until EOF, using its
read()
method in blocks of size blocksize to provide the data to be stored.blocksize (int) – The read block size. Defaults to
8192
.callback (callable) – A single parameter callable that is called for each block of data sent, with its single argument being the data as
bytes
.rest (int) – A
REST
command to be sent to the server. See the documentation for the rest parameter of thetransfercmd()
method.
버전 3.2에서 변경: The rest parameter was added.
- storlines(cmd, fp, callback=None)¶
줄 모드로 파일을 저장합니다. cmd는 적절한
STOR
명령이어야 합니다 (storbinary()
를 참조하십시오). 저장될 데이터를 제공하기 위해readline()
메서드를 사용하여 (바이너리 모드로 열린) 파일 객체 fp에서 EOF까지 줄을 읽어 들입니다. callback은 줄마다 보내진 다음에 호출되는 선택적 단일 매개 변수 콜러블입니다.
- transfercmd(cmd, rest=None)¶
데이터 연결을 통해 전송을 시작합니다. 전송이 활성화되면,
EPRT
나PORT
명령과 cmd로 지정한 전송 명령을 보내고 연결을 받아들입니다. 서버가 수동(passive)이면,EPSV
나PASV
명령을 전송하고, 서버에 연결한 다음 전송 명령을 시작합니다. 어느 쪽이든, 연결 소켓을 반환합니다.선택적 rest가 제공되면,
REST
명령이 서버로 전송되고 rest를 인자로 전달합니다. rest는 일반적으로 요청된 파일에 대한 바이트 오프셋으로, 요청된 오프셋에서 파일 바이트 전송을 다시 시작하고 초기 바이트를 건너뛰도록 서버에 지시합니다. 그러나transfercmd()
메서드는 초기화 때 지정된 encoding 매개 변수를 사용하여 rest를 문자열로 변환하지만, 문자열의 내용은 점검하지 않음에 유의하십시오. 서버가REST
명령을 인식하지 못하면,error_reply
예외가 발생합니다. 이 경우, 단순히 rest 인자 없이transfercmd()
를 호출하십시오.
- ntransfercmd(cmd, rest=None)¶
transfercmd()
와 비슷하지만, 데이터 연결과 데이터의 예상 크기의 튜플을 반환합니다. 예상 크기를 계산할 수 없으면,None
이 예상 크기로 반환됩니다. cmd와 rest는transfercmd()
에서와 같은 의미입니다.
- mlsd(path='', facts=[])¶
MLSD
명령(RFC 3659)을 사용하여 표준화된 형식으로 디렉터리를 나열합니다. path가 생략되면 현재 디렉터리를 가정합니다. facts는 원하는 정보 유형을 나타내는 문자열의 리스트입니다 (예를 들어["type", "size", "perm"]
). 경로에서 발견된 모든 파일에 대해 두 요소의 튜플을 산출하는 제너레이터 객체를 반환합니다. 첫 번째 요소는 파일 이름이고, 두 번째 요소는 파일 이름에 대한 사실(facts)을 포함하는 딕셔너리입니다. 이 딕셔너리의 내용은 facts 인자에 의해 제한될 수 있지만, 서버가 요청된 모든 사실을 반환한다고 보장하지는 않습니다.버전 3.3에 추가.
- nlst(argument[, ...])¶
NLST
명령이 반환한 파일 이름 리스트를 반환합니다. 선택적 argument는 나열할 디렉터리입니다 (기본값은 현재 서버 디렉터리입니다). 비표준 옵션을NLST
명령에 전달하기 위해 여러 인자를 사용할 수 있습니다.참고
서버가 명령을 지원한다면,
mlsd()
가 더 나은 API를 제공합니다.
- dir(argument[, ...])¶
Produce a directory listing as returned by the
LIST
command, printing it to standard output. The optional argument is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to theLIST
command. If the last argument is a function, it is used as a callback function as forretrlines()
; the default prints tosys.stdout
. This method returnsNone
.참고
서버가 명령을 지원한다면,
mlsd()
가 더 나은 API를 제공합니다.
- rename(fromname, toname)¶
서버의 파일 fromname을 toname으로 이름을 바꿉니다.
- delete(filename)¶
서버에서 filename이라는 파일을 제거합니다. 성공하면, 응답 텍스트를 반환하고, 그렇지 않으면 권한 에러면
error_perm
을, 다른 에러면error_reply
를 발생시킵니다.
- cwd(pathname)¶
서버에서 현재 디렉터리를 설정합니다.
- mkd(pathname)¶
서버에서 새 디렉터리를 만듭니다.
- pwd()¶
서버에서 현재 디렉터리의 경로명을 반환합니다.
- rmd(dirname)¶
서버에서 dirname이라는 디렉터리를 제거합니다.
- size(filename)¶
서버에서 filename이라는 파일의 크기를 요청합니다. 성공하면, 파일 크기가 정수로 반환되고, 그렇지 않으면
None
이 반환됩니다.SIZE
명령은 표준화되어 있지 않지만, 많은 일반적인 서버 구현에서 지원됨에 유의하십시오.
FTP_TLS objects¶
- class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')¶
An
FTP
subclass which adds TLS support to FTP as described in RFC 4217. Connect to port 21 implicitly securing the FTP control connection before authenticating.참고
The user must explicitly secure the data connection by calling the
prot_p()
method.- 매개변수:
host (str) – The hostname to connect to. If given,
connect(host)
is implicitly called by the constructor.user (str) – The username to log in with (default:
'anonymous'
). If given,login(host, passwd, acct)
is implicitly called by the constructor.passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or
"-"
, a password will be automatically generated.acct (str) – Account information to be used for the
ACCT
FTP command. Few systems implement this. See RFC-959 for more details.context (
ssl.SSLContext
) – An SSL context object which allows bundling SSL configuration options, certificates and private keys into a single, potentially long-lived, structure. Please read 보안 고려 사항 for best practices.timeout (float | None) – A timeout in seconds for blocking operations like
connect()
(default: the global default timeout setting).source_address (tuple | None) – A 2-tuple
(host, port)
for the socket to bind to as its source address before connecting.encoding (str) – The encoding for directories and filenames (default:
'utf-8'
).
keyfile과 certfile은 context에 대한 레거시 대안입니다 – SSL 연결을 위한 (각각) PEM 형식 개인 키와 인증서 체인 파일을 가리킬 수 있습니다.
버전 3.2에 추가.
버전 3.3에서 변경: Added the source_address parameter.
버전 3.4에서 변경: The class now supports hostname check with
ssl.SSLContext.check_hostname
and Server Name Indication (seessl.HAS_SNI
).버전 3.6부터 폐지됨: keyfile과 certfile은 context로 대체되어 폐지되었습니다. 대신
ssl.SSLContext.load_cert_chain()
을 사용하거나,ssl.create_default_context()
가 시스템의 신뢰할 수 있는 CA 인증서를 선택하도록 하십시오.버전 3.9에서 변경: timeout 매개 변수가 0으로 설정되면, 비 블로킹 소켓이 만들어지지 않도록
ValueError
를 발생시킵니다. encoding 매개 변수가 추가되었으며, 기본값은 Latin-1 에서 UTF-8로 변경되어 RFC 2640을 따릅니다.FTP_TLS
클래스를 사용한 샘플 세션은 다음과 같습니다:>>> ftps = FTP_TLS('ftp.pureftpd.org') >>> ftps.login() '230 Anonymous user logged in' >>> ftps.prot_p() '200 Data protection level set to "private"' >>> ftps.nlst() ['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']
FTP_TLS
class inherits fromFTP
, defining these additional methods and attributes:- ssl_version¶
The SSL version to use (defaults to
ssl.PROTOCOL_SSLv23
).
- auth()¶
ssl_version
어트리뷰트에 지정된 내용에 따라, TLS나 SSL을 사용하여 보안 제어 연결을 설정합니다.버전 3.4에서 변경: The method now supports hostname check with
ssl.SSLContext.check_hostname
and Server Name Indication (seessl.HAS_SNI
).
- ccc()¶
제어 채널을 일반 텍스트로 되돌립니다. 고정 포트를 열지 않고 비보안 FTP로 NAT을 다루는 방법을 알고 있는 방화벽을 활용하는 데 유용할 수 있습니다.
버전 3.3에 추가.
- prot_p()¶
보안 데이터 연결을 설정합니다.
- prot_c()¶
일반 텍스트 데이터 연결을 설정합니다.
Module variables¶
- exception ftplib.error_reply¶
서버에서 예기치 않은 응답이 수신될 때 발생하는 예외.
- exception ftplib.error_temp¶
일시적 에러(400–499 범위의 응답 코드)를 나타내는 에러 코드가 수신될 때 발생하는 예외.
- exception ftplib.error_perm¶
영구 에러(500–599 범위의 응답 코드)를 나타내는 에러 코드가 수신될 때 발생하는 예외.
- exception ftplib.error_proto¶
서버로부터 FTP(File Transfer Protocol)의 응답 규격(즉, 1–5 범위의 숫자로 시작)에 맞지 않는 응답을 수신할 때 발생하는 예외.
- ftplib.all_errors¶
FTP
인스턴스의 메서드가 (호출자로 인한 프로그래밍 에러가 아니라) FTP 연결 문제로 인해 발생시킬 수 있는 모든 예외의 집합 (튜플). 이 집합에는 위에 나열된 네 가지 예외뿐만 아니라OSError
와EOFError
가 포함됩니다.
더 보기
- 모듈
netrc
.netrc
파일 형식의 구문 분석기..netrc
파일은 일반적으로 FTP 클라이언트가 사용자에게 프롬프트 하기 전에 사용자 인증 정보를 로드하는 데 사용됩니다.