ftplib — FTP 프로토콜 클라이언트
ftplib — FTP 프로토콜 클라이언트
이 모듈은 FTP 클래스와 몇 가지 관련 항목을 정의해요. FTP 클래스는 FTP 프로토콜의 클라이언트 쪽을 구현해요. 이것을 사용해 다른 FTP 서버 미러링 같은 다양한 자동화 FTP 작업을 수행하는 Python 프로그램을 작성할 수 있어요. urllib.request 모듈이 FTP를 쓰는 URL을 처리할 때도 사용돼요. FTP(File Transfer Protocol)에 대한 더 많은 정보는 인터넷 RFC 959를 참고하세요.
기본 인코딩은 RFC 2640에 따라 UTF-8이에요.
가용성: WASI가 아님. 이 모듈은 WebAssembly에서 동작하지 않거나 사용할 수 없어요.
출처: Python 표준 라이브러리
본문
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.'
참조
FTP 객체
class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')
FTP 클래스의 새 인스턴스를 돌려줘요.
매개변수:
host(str) — 연결할 호스트 이름. 주어지면 생성자가connect(host)를 암시적으로 호출해요.user(str) — 로그인할 사용자 이름(기본값:'anonymous'). 주어지면 생성자가login(host, passwd, acct)을 암시적으로 호출해요.passwd(str) — 로그인할 때 쓸 비밀번호. 주어지지 않고passwd가 빈 문자열이나"-"이면 비밀번호가 자동 생성돼요.acct(str) —ACCTFTP 명령에 쓸 계정 정보. 이것을 구현하는 시스템은 거의 없어요. 자세한 내용은 RFC-959를 참고하세요.timeout(float | None) —connect()같은 블로킹 연산의 초 단위 타임아웃(기본값: 전역 기본 타임아웃 설정).source_address(tuple | None) — 연결 전에 소켓이 소스 주소로 바인딩할(host, port)2-튜플.encoding(str) — 디렉터리와 파일명의 인코딩(기본값:'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 매개변수가 추가되고 기본값이 RFC 2640을 따르도록 Latin-1에서 UTF-8로 바뀜.
여러 FTP 메서드는 텍스트 파일용과 이진 파일용의 두 가지 형태로 제공돼요. 메서드 이름은 사용된 명령 뒤에 텍스트 버전은 lines, 이진 버전은 binary가 붙어요.
FTP 인스턴스는 다음 메서드들을 가져요.
set_debuglevel(level)
인스턴스의 디버깅 레벨을 int로 설정해요. 이것이 출력되는 디버깅 출력의 양을 제어해요.
0(기본값): 디버그 출력 없음.1: 보통 요청당 한 줄씩의 적당한 양의 디버그 출력.2이상: 최대 디버깅 출력으로, 제어 연결에서 보내고 받는 각 줄을 기록.
connect(host='', port=0, timeout=None, source_address=None)
주어진 호스트와 포트에 연결해요. 이 함수는 인스턴스당 한 번만 호출해야 해요. FTP 인스턴스를 만들 때 host 인자가 주어졌으면 호출하지 말아야 해요. 다른 모든 FTP 메서드는 연결이 성공적으로 이루어진 후에만 호출할 수 있어요.
매개변수:
host(str) — 연결할 호스트.port(int) — 연결할 TCP 포트(기본값: FTP 프로토콜 명세가 지정한 대로 21). 다른 포트 번호를 지정할 일은 거의 없어요.timeout(float | None) — 연결 시도의 초 단위 타임아웃(기본값: 전역 기본 타임아웃 설정).source_address(tuple | None) — 연결 전에 소켓이 소스 주소로 바인딩할(host, port)2-튜플.
인자 self, host, port와 함께 감사 이벤트 ftplib.connect를 발생시켜요.
버전 3.3에서 변경: source_address 매개변수 추가.
getwelcome()
초기 연결에 대한 응답으로 서버가 보낸 환영 메시지를 돌려줘요. (이 메시지는 사용자에게 관련 있을 수 있는 부인 또는 도움말 정보를 담을 때가 있어요.)
login(user='anonymous', passwd='', acct='')
연결된 FTP 서버에 로그온해요. 이 함수는 인스턴스당 한 번만, 연결이 이루어진 후에 호출해야 해요. FTP 인스턴스를 만들 때 host와 user 인자가 주어졌으면 호출하지 말아야 해요. 대부분의 FTP 명령은 클라이언트가 로그인한 후에만 허용돼요.
매개변수:
user(str) — 로그인할 사용자 이름(기본값:'anonymous').passwd(str) — 로그인할 때 쓸 비밀번호. 주어지지 않고passwd가 빈 문자열이나"-"이면 비밀번호가 자동 생성돼요.acct(str) —ACCTFTP 명령에 쓸 계정 정보. 이것을 구현하는 시스템은 거의 없어요. 자세한 내용은 RFC-959를 참고하세요.
abort()
진행 중인 파일 전송을 중단해요. 이것이 항상 동작하는 것은 아니지만 시도해 볼 가치가 있어요.
sendcmd(cmd)
간단한 명령 문자열을 서버로 보내고 응답 문자열을 돌려줘요.
인자 self, cmd와 함께 감사 이벤트 ftplib.sendcmd를 발생시켜요.
voidcmd(cmd)
간단한 명령 문자열을 서버로 보내고 응답을 처리해요. 응답 코드가 성공에 해당하면(200–299 범위의 코드) 응답 문자열을 돌려줘요. 그렇지 않으면 error_reply를 발생시켜요.
인자 self, cmd와 함께 감사 이벤트 ftplib.sendcmd를 발생시켜요.
retrbinary(cmd, callback, blocksize=8192, rest=None)
이진 전송 모드로 파일을 검색해요.
매개변수:
cmd(str) — 적절한RETR명령:"RETR filename".callback(callable) — 받은 각 데이터 블록마다 호출되는 단일 매개변수 callable로, 단일 인자는bytes로서의 데이터예요.blocksize(int) — 실제 전송을 위해 만든 저수준 소켓 객체에서 읽을 최대 청크 크기. 이것은callback에 전달될 최대 데이터 크기에도 해당해요. 기본값은 8192.rest(int) — 서버로 보낼REST명령.transfercmd()메서드의rest매개변수 문서를 참고하세요.
retrlines(cmd, callback=None)
초기화 시 지정한 encoding 매개변수의 인코딩으로 파일·디렉터리 목록을 검색해요. cmd는 적절한 RETR 명령(retrbinary() 참고) 또는 LIST나 NLST 같은 명령(보통 그냥 'LIST')이어야 해요. LIST는 파일과 그 파일에 대한 정보의 목록을 검색하고, NLST는 파일 이름 목록을 검색해요. callback 함수는 끝 CRLF가 제거된 줄을 담은 문자열 인자로 각 줄마다 호출돼요. 기본 콜백은 줄을 sys.stdout에 출력해요.
set_pasv(val)
val이 참이면 "수동(passive)" 모드를 활성화하고, 아니면 수동 모드를 비활성화해요. 수동 모드는 기본적으로 켜져 있어요.
storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)
이진 전송 모드로 파일을 저장해요.
매개변수:
cmd(str) — 적절한STOR명령:"STOR filename".fp(file object) — 이진 모드에서 열린 파일 객체로, EOF까지blocksize크기의 블록 단위로read()메서드를 사용해 저장할 데이터를 제공해요.blocksize(int) — 읽기 블록 크기. 기본값은 8192.callback(callable) — 보낸 각 데이터 블록마다 호출되는 단일 매개변수 callable로, 단일 인자는bytes로서의 데이터예요.rest(int) — 서버로 보낼REST명령.transfercmd()메서드의rest매개변수 문서를 참고하세요.
버전 3.2에서 변경: rest 매개변수 추가.
storlines(cmd, fp, callback=None)
줄 모드로 파일을 저장해요. cmd는 적절한 STOR 명령(storbinary() 참고)이어야 해요. 파일 객체 fp(이진 모드에서 열림)에서 EOF까지 readline() 메서드를 사용해 줄을 읽어 저장할 데이터를 제공해요. callback은 각 줄이 보내진 후 호출되는 선택적 단일 매개변수 callable이에요.
transfercmd(cmd, rest=None)
데이터 연결을 통해 전송을 시작해요. 전송이 능동(active)이면 EPRT 또는 PORT 명령과 cmd가 지정한 전송 명령을 보내고 연결을 받아들여요. 서버가 수동이면 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"]). path에서 찾은 각 파일에 대해 두 요소의 튜플을 생성하는 제너레이터 객체를 돌려줘요. 첫 요소는 파일 이름, 두 번째는 파일 이름에 대한 사실을 담은 딕셔너리예요. 이 딕셔너리의 내용은 facts 인자로 제한될 수 있지만 서버가 모든 요청 사실을 돌려준다고 보장되지는 않아요.
버전 3.3에 추가됨.
nlst(argument[, ...])
NLST 명령이 돌려주는 파일 이름 리스트를 돌려줘요. 선택적 인자는 나열할 디렉터리(기본값은 현재 서버 디렉터리)예요. 여러 인자를 사용해 비표준 옵션을 NLST 명령에 전달할 수 있어요.
참고 — 서버가 명령을 지원하면
mlsd()가 더 나은 API를 제공해요.
dir(argument[, ...])
LIST 명령이 돌려주는 대로 디렉터리 목록을 생성해 표준 출력으로 출력해요. 선택적 인자는 나열할 디렉터리(기본값은 현재 서버 디렉터리)예요. 여러 인자를 사용해 비표준 옵션을 LIST 명령에 전달할 수 있어요. 마지막 인자가 함수면 retrlines()에서처럼 콜백 함수로 사용되고, 기본값은 sys.stdout에 출력해요. 이 메서드는 None을 돌려줘요.
참고 — 서버가 명령을 지원하면
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 명령은 표준화되지 않았지만 많은 일반 서버 구현이 지원한다는 점에 주의하세요.
quit()
서버로 QUIT 명령을 보내고 연결을 닫아요. 이것은 연결을 닫는 "정중한" 방법이지만, 서버가 QUIT 명령에 오류로 응답하면 예외를 발생시킬 수 있어요. 이것은 close() 메서드 호출을 의미하며, 이후 호출에 FTP 인스턴스를 쓸모없게 만들어요(아래 참고).
close()
연결을 일방적으로 닫아요. quit()이 성공한 후 같은 이미 닫힌 연결에 적용하면 안 돼요. 이 호출 후에는 FTP 인스턴스를 더 이상 사용하면 안 돼요(close()나 quit() 호출 후에는 다른 login() 메서드를 발행해서 연결을 다시 열 수 없어요).
FTP_TLS 객체
class ftplib.FTP_TLS(host='', user='', passwd='', acct='', *, context=None, timeout=None, source_address=None, encoding='utf-8')
RFC 4217에 설명된 대로 FTP에 TLS 지원을 추가하는 FTP 하위 클래스예요. 포트 21에 연결해 인증 전에 FTP 제어 연결을 암시적으로 보호해요.
참고 — 사용자는
prot_p()메서드를 호출해 데이터 연결을 명시적으로 보호해야 해요.
매개변수:
host(str) — 연결할 호스트 이름. 주어지면 생성자가connect(host)를 암시적으로 호출해요.user(str) — 로그인할 사용자 이름(기본값:'anonymous'). 주어지면 생성자가login(host, passwd, acct)을 암시적으로 호출해요.passwd(str) — 로그인할 때 쓸 비밀번호. 주어지지 않고passwd가 빈 문자열이나"-"이면 비밀번호가 자동 생성돼요.acct(str) —ACCTFTP 명령에 쓸 계정 정보. 이것을 구현하는 시스템은 거의 없어요. 자세한 내용은 RFC-959를 참고하세요.context(ssl.SSLContext) — SSL 구성 옵션, 인증서, 개인 키를 하나의 잠재적으로 장수 구조로 묶을 수 있는 SSL 컨텍스트 객체. 모범 사례는 보안 고려 사항을 읽어 보세요.timeout(float | None) —connect()같은 블로킹 연산의 초 단위 타임아웃(기본값: 전역 기본 타임아웃 설정).source_address(tuple | None) — 연결 전에 소켓이 소스 주소로 바인딩할(host, port)2-튜플.encoding(str) — 디렉터리와 파일명의 인코딩(기본값:'utf-8').
버전 3.2에 추가됨.
버전 3.3에서 변경: source_address 매개변수 추가.
버전 3.4에서 변경: 클래스가 이제 ssl.SSLContext.check_hostname과 Server Name Indication(ssl.HAS_SNI 참고)으로 호스트 이름 검사를 지원함.
버전 3.9에서 변경: timeout 매개변수가 0으로 설정되면 비블로킹 소켓 생성을 막기 위해 ValueError를 발생시킴. encoding 매개변수가 추가되고 기본값이 RFC 2640을 따르도록 Latin-1에서 UTF-8로 바뀜.
버전 3.12에서 변경: 폐기된 keyfile과 certfile 매개변수가 제거됨.
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 클래스는 FTP에서 상속하며, 다음 추가 메서드·속성을 정의해요.
ssl_version
사용할 SSL 버전(기본값은 ssl.PROTOCOL_SSLv23).
auth()
ssl_version 속성에 지정된 것에 따라 TLS 또는 SSL을 사용해 보안 제어 연결을 설정해요.
버전 3.4에서 변경: 메서드가 이제 ssl.SSLContext.check_hostname과 Server Name Indication(ssl.HAS_SNI 참고)으로 호스트 이름 검사를 지원함.
ccc()
제어 채널을 평문으로 되돌려요. 고정 포트를 열지 않고 비보안 FTP로 NAT를 처리하는 법을 아는 방화벽을 활용하는 데 유용할 수 있어요.
버전 3.3에 추가됨.
prot_p()
보안 데이터 연결을 설정해요.
prot_c()
평문 데이터 연결을 설정해요.
모듈 변수
exception ftplib.error_reply
서버에서 예기치 않은 응답을 받으면 발생하는 예외.
exception ftplib.error_temp
일시적 오류를 나타내는 오류 코드(400–499 범위의 응답 코드)를 받으면 발생하는 예외.
exception ftplib.error_perm
영구 오류를 나타내는 오류 코드(500–599 범위의 응답 코드)를 받으면 발생하는 예외.
exception ftplib.error_proto
FTP 응답 명세에 맞지 않는(즉 1–5 범위의 숫자로 시작하지 않는) 응답을 서버에서 받으면 발생하는 예외.
ftplib.all_errors
FTP 인스턴스 메서드가 FTP 연결 문제(호출자가 만든 프로그래밍 오류가 아니라)로 발생시킬 수 있는 모든 예외의 집합(튜플). 이 집합은 위에 나열된 네 예외와 OSError, EOFError를 포함해요.
더 알아보기
netrc—.netrc파일 형식의 파서..netrc파일은 보통 FTP 클라이언트가 사용자에게 묻기 전에 사용자 인증 정보를 로드하는 데 쓰여요.