"ftplib" --- FTP 프로토콜 클라이언트
************************************

**소스 코드:** Lib/ftplib.py

======================================================================

이 모듈은 "FTP" 클래스와 몇 가지 관련 항목을 정의합니다. "FTP" 클래스
는 FTP 프로토콜의 클라이언트 쪽을 구현합니다. 이것을 사용하여 다른 FTP
서버 미러링과 같은 다양한 자동화된 FTP 작업을 수행하는 파이썬 프로그램
을 작성할 수 있습니다. 또한 "urllib.request" 모듈에서 FTP를 사용하는
URL을 처리하는 데 사용됩니다. FTP(File Transfer Protocol)에 대한 자세
한 내용은 인터넷 **RFC 959**를 참조하십시오.

"ftplib" 모듈을 사용한 샘플 세션은 다음과 같습니다:

   >>> from ftplib import FTP
   >>> ftp = FTP('ftp.debian.org')     # connect to host, default port
   >>> ftp.login()                     # user anonymous, passwd anonymous@
   '230 Login successful.'
   >>> ftp.cwd('debian')               # change into "debian" directory
   >>> 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()

모듈은 다음 항목을 정의합니다:

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None)

   Return a new instance of the "FTP" class.  When *host* is given,
   the method call "connect(host)" is made.  When *user* is given,
   additionally the method call "login(user, passwd, acct)" is made
   (where *passwd* and *acct* default to the empty string when not
   given).  The optional *timeout* parameter specifies a timeout in
   seconds for blocking operations like the connection attempt (if is
   not specified, the global default timeout setting will be used).
   *source_address* is a 2-tuple "(host, port)" for the socket to bind
   to as its source address before connecting.

   "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* 매개 변수가 추가되었습니다.

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)

   **RFC 4217**에 설명된 대로 FTP에 TLS 지원을 추가하는 "FTP" 서브 클
   래스. 인증하기 전에 FTP 제어 연결을 묵시적으로 보안을 유지하면서 포
   트 21에 평소와 같이 연결합니다. 데이터 연결의 보안을 유지하려면 사
   용자가 "prot_p()" 메서드를 호출하여 명시적으로 요청해야 합니다.
   *context*는 SSL 구성 옵션, 인증서 및 개인 키를 단일 (잠재적으로 오
   래 유지되는) 구조로 번들링 할 수 있는 "ssl.SSLContext" 객체입니다.
   모범 사례를 보려면 보안 고려 사항을 읽으십시오.

   *keyfile*과 *certfile*은 *context*에 대한 레거시 대안입니다 -- SSL
   연결을 위한 (각각) PEM 형식 개인 키와 인증서 체인 파일을 가리킬 수
   있습니다.

   버전 3.2에 추가.

   버전 3.3에서 변경: *source_address* 매개 변수가 추가되었습니다.

   버전 3.4에서 변경: 이 클래스는 이제 "ssl.SSLContext.check_hostname"
   과 *서버 이름 표시(Server Name Indication)*("ssl.HAS_SNI"를 참조하
   십시오)으로 호스트명 확인을 지원합니다.

   버전 3.6부터 폐지: *keyfile*과 *certfile*은 *context*로 대체되어 폐
   지되었습니다. 대신 "ssl.SSLContext.load_cert_chain()"을 사용하거나,
   "ssl.create_default_context()"가 시스템의 신뢰할 수 있는 CA 인증서
   를 선택하도록 하십시오.

   "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']

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
     클라이언트가 사용자에게 프롬프트 하기 전에 사용자 인증 정보를 로
     드하는 데 사용됩니다.


FTP 객체
========

여러 메서드가 두 가지 스타일로 제공됩니다: 텍스트 파일을 처리하는 것과
바이너리 파일을 위한 것. 명령 뒤에 텍스트 버전의 경우 "lines", 바이너
리 버전의 경우 "binary"를 붙여서 이름을 지정합니다.

"FTP" 인스턴스에는 다음과 같은 메서드가 있습니다:

FTP.set_debuglevel(level)

   인스턴스의 디버깅 수준을 설정합니다. 인쇄되는 디버깅 출력의 양을 제
   어합니다. 기본값 "0"은 디버깅 출력을 생성하지 않습니다. "1" 값은 적
   당한 양의 디버깅 출력, 일반적으로 요청당 한 줄을 생성합니다. "2" 이
   상의 값은 제어 연결에서 보내고 받는 각 줄을 로깅하여 최대 디버깅 출
   력량을 생성합니다.

FTP.connect(host='', port=0, timeout=None, source_address=None)

   주어진 host와 port에 연결합니다. FTP 프로토콜 명세에 지정된 대로,
   기본 포트 번호는 "21"입니다. 다른 포트 번호를 지정할 필요는 거의 없
   습니다. 이 함수는 각 인스턴스에 대해 한 번만 호출해야 합니다; 인스
   턴스를 만들 때 host가 제공되었으면, 전혀 호출되지 않아야 합니다. 다
   른 모든 메서드는 연결이 완료된 후에만 사용할 수 있습니다. 선택적
   *timeout* 매개 변수는 연결 시도에 대한 시간제한을 초로 지정합니다.
   *timeout*이 전달되지 않으면, 전역 기본 시간제한 설정이 사용됩니다.
   *source_address*는 소켓이 연결하기 전에 소스 주소로 바인드 하는 2-
   튜플 "(host, port)"입니다.

   인자 "self", "host", "port"로 감사 이벤트 "ftplib.connect"를 발생시
   킵니다.

   버전 3.3에서 변경: *source_address* 매개 변수가 추가되었습니다.

FTP.getwelcome()

   초기 연결에 대한 응답으로 서버에서 보낸 환영 메시지를 반환합니다. (
   이 메시지에는 때때로 사용자와 관련될 수 있는 고지 사항이나 도움말
   정보가 포함되어 있습니다.)

FTP.login(user='anonymous', passwd='', acct='')

   주어진 *user*로 로그인합니다. *passwd*와 *acct* 매개 변수는 선택 사
   항이며 기본값은 빈 문자열입니다. *user*를 지정하지 않으면, 기본값은
   "'anonymous'"입니다. *user*가 "'anonymous'"이면, 기본 *passwd*는
   "'anonymous@'"입니다. 이 함수는 연결이 설정된 후 각 인스턴스에 마다
   한 번만 호출해야 합니다; 인스턴스가 만들어질 때 host와 user가 제공
   되었으면 전혀 호출되지 않아야 합니다. 대부분의 FTP 명령은 클라이언
   트가 로그인한 후에만 허용됩니다. *acct* 매개 변수는 "계정 정보
   (accounting information)"를 제공합니다; 이를 구현하는 시스템은 거의
   없습니다.

FTP.abort()

   진행 중인 파일 전송을 중단합니다. 이것을 사용하는 것이 항상 동작하
   지는 않지만, 시도해 볼 가치가 있습니다.

FTP.sendcmd(cmd)

   간단한 명령 문자열을 서버로 보내고 응답 문자열을 반환합니다.

   인자 "self", "cmd"로 감사 이벤트 "ftplib.sendcmd"를 발생시킵니다.

FTP.voidcmd(cmd)

   간단한 명령 문자열을 서버로 보내고 응답을 처리합니다. 성공에 해당하
   는 응답 코드(200--299 범위의 코드)가 수신되면 아무것도 반환하지 않
   습니다. 그렇지 않으면 "error_reply"를 발생시킵니다.

   인자 "self", "cmd"로 감사 이벤트 "ftplib.sendcmd"를 발생시킵니다.

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)

   바이너리 전송 모드로 파일을 가져옵니다. *cmd*는 적절한 "RETR" 명령
   이어야 합니다: "'RETR filename'". *callback* 함수는 수신된 각 데이
   터 블록에 대해 호출되며, 단일 바이트열 인자로 데이터 블록을 제공합
   니다. 선택적 *blocksize* 인자는 실제 전송을 수행하기 위해 만들어진
   저수준 소켓 객체에서 읽을 최대 청크 크기를 지정합니다 (*callback*에
   전달되는 데이터 블록의 최대 크기이기도 합니다). 합리적인 기본값이
   선택됩니다. *rest*는 "transfercmd()" 메서드에서와 같은 의미입니다.

FTP.retrlines(cmd, callback=None)

   Retrieve a file or directory listing in ASCII transfer mode.  *cmd*
   should be an appropriate "RETR" command (see "retrbinary()") or a
   command such as "LIST" or "NLST" (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 to "sys.stdout".

FTP.set_pasv(val)

   *val*이 참이면 "수동(passive)" 모드를 활성화하고, 그렇지 않으면 수
   동 모드를 비활성화합니다. 수동 모드는 기본적으로 켜져 있습니다.

FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

   바이너리 전송 모드로 파일을 저장합니다. *cmd*는 적절한 "STOR" 명령
   이어야 합니다: ""STOR filename"". *fp*는 (바이너리 모드로 열린) *파
   일 객체*이며 저장될 데이터를 제공하기 위해 *blocksize* 크기의 블록
   으로 "read()" 메서드를 사용하여 EOF까지 읽힙니다. *blocksize* 인자
   의 기본값은 8192입니다. *callback*은 각 데이터 블록마다 보내진 다음
   에 호출되는 선택적 단일 매개 변수 콜러블입니다. *rest*는
   "transfercmd()" 메서드에서와 같은 의미입니다.

   버전 3.2에서 변경: *rest* 매개 변수가 추가되었습니다.

FTP.storlines(cmd, fp, callback=None)

   Store a file in ASCII transfer mode.  *cmd* should be an
   appropriate "STOR" command (see "storbinary()").  Lines are read
   until EOF from the *file object* *fp* (opened in binary mode) using
   its "readline()" method to provide the data to be stored.
   *callback* is an optional single parameter callable that is called
   on each line after it is sent.

FTP.transfercmd(cmd, rest=None)

   데이터 연결을 통해 전송을 시작합니다. 전송이 활성화되면, "EPRT"나
   "PORT" 명령과 *cmd*로 지정한 전송 명령을 보내고 연결을 받아들입니다
   . 서버가 수동(passive)이면, "EPSV"나 "PASV" 명령을 전송하고, 서버에
   연결한 다음 전송 명령을 시작합니다. 어느 쪽이든, 연결 소켓을 반환합
   니다.

   If optional *rest* is given, a "REST" command is sent to the
   server, passing *rest* as an argument.  *rest* is usually a byte
   offset into the requested file, telling the server to restart
   sending the file's bytes at the requested offset, skipping over the
   initial bytes.  Note however that **RFC 959** requires only that
   *rest* be a string containing characters in the printable range
   from ASCII code 33 to ASCII code 126.  The "transfercmd()" method,
   therefore, converts *rest* to a string, but no check is performed
   on the string's contents.  If the server does not recognize the
   "REST" command, an "error_reply" exception will be raised.  If this
   happens, simply call "transfercmd()" without a *rest* argument.

FTP.ntransfercmd(cmd, rest=None)

   "transfercmd()"와 비슷하지만, 데이터 연결과 데이터의 예상 크기의 튜
   플을 반환합니다. 예상 크기를 계산할 수 없으면, "None"이 예상 크기로
   반환됩니다. *cmd*와 *rest*는 "transfercmd()"에서와 같은 의미입니다.

FTP.mlsd(path="", facts=[])

   "MLSD" 명령(**RFC 3659**)을 사용하여 표준화된 형식으로 디렉터리를
   나열합니다. *path*가 생략되면 현재 디렉터리를 가정합니다. *facts*는
   원하는 정보 유형을 나타내는 문자열의 리스트입니다 (예를 들어
   "["type", "size", "perm"]"). 경로에서 발견된 모든 파일에 대해 두 요
   소의 튜플을 산출하는 제너레이터 객체를 반환합니다. 첫 번째 요소는
   파일 이름이고, 두 번째 요소는 파일 이름에 대한 사실(facts)을 포함하
   는 딕셔너리입니다. 이 딕셔너리의 내용은 *facts* 인자에 의해 제한될
   수 있지만, 서버가 요청된 모든 사실을 반환한다고 보장하지는 않습니다
   .

   버전 3.3에 추가.

FTP.nlst(argument[, ...])

   "NLST" 명령이 반환한 파일 이름 리스트를 반환합니다. 선택적
   *argument*는 나열할 디렉터리입니다 (기본값은 현재 서버 디렉터리입니
   다). 비표준 옵션을 "NLST" 명령에 전달하기 위해 여러 인자를 사용할
   수 있습니다.

   참고:

     서버가 명령을 지원한다면, "mlsd()"가 더 나은 API를 제공합니다.

FTP.dir(argument[, ...])

   "LIST" 명령이 반환한 디렉터리 목록을 생성하여 표준 출력으로 인쇄합
   니다. 선택적 *argument*는 나열할 디렉터리입니다 (기본값은 현재 서버
   디렉터리입니다). 비표준 옵션을 "LIST" 명령에 전달하기 위해 여러 인
   자를 사용할 수 있습니다. 마지막 인자가 함수면, "retrlines()"와 같이
   *callback* 함수로 사용됩니다; 기본값은 "sys.stdout"으로 인쇄합니다.
   이 메서드는 "None"을 반환합니다.

   참고:

     서버가 명령을 지원한다면, "mlsd()"가 더 나은 API를 제공합니다.

FTP.rename(fromname, toname)

   서버의 파일 *fromname*을 *toname*으로 이름을 바꿉니다.

FTP.delete(filename)

   서버에서 *filename*이라는 파일을 제거합니다. 성공하면, 응답 텍스트
   를 반환하고, 그렇지 않으면 권한 에러면 "error_perm"을, 다른 에러면
   "error_reply"를 발생시킵니다.

FTP.cwd(pathname)

   서버에서 현재 디렉터리를 설정합니다.

FTP.mkd(pathname)

   서버에서 새 디렉터리를 만듭니다.

FTP.pwd()

   서버에서 현재 디렉터리의 경로명을 반환합니다.

FTP.rmd(dirname)

   서버에서 *dirname*이라는 디렉터리를 제거합니다.

FTP.size(filename)

   서버에서 *filename*이라는 파일의 크기를 요청합니다. 성공하면, 파일
   크기가 정수로 반환되고, 그렇지 않으면 "None"이 반환됩니다. "SIZE"
   명령은 표준화되어 있지 않지만, 많은 일반적인 서버 구현에서 지원됨에
   유의하십시오.

FTP.quit()

   "QUIT" 명령을 서버로 보내고 연결을 닫습니다. 이는 연결을 닫는 "정중
   한" 방법이지만, 서버가 "QUIT" 명령에 대해 에러로 응답하면 예외가 발
   생할 수 있습니다. 이것은 묵시적인 "close()" 메서드 호출을 수반하며,
   이는 후속 호출에 "FTP" 인스턴스를 쓸모없게 만듭니다 (아래를 참조하
   십시오).

FTP.close()

   일방적으로 연결을 닫습니다. 이것은 이미 닫힌 연결에는 적용되지 않아
   야 합니다, 가령 "quit()"를 성공적으로 호출한 후에. 이 호출 후 "FTP"
   인스턴스를 더는 사용하지 않아야 합니다 ("close()"나 "quit()" 호출
   후 다른 "login()" 메서드를 사용해서 연결을 다시 열 수 없습니다).


FTP_TLS 객체
============

"FTP_TLS" 클래스는 "FTP"를 상속하여, 다음과 같은 추가 객체를 정의합니
다:

FTP_TLS.ssl_version

   사용할 SSL 버전 (기본값은 "ssl.PROTOCOL_SSLv23"입니다).

FTP_TLS.auth()

   "ssl_version" 어트리뷰트에 지정된 내용에 따라, TLS나 SSL을 사용하여
   보안 제어 연결을 설정합니다.

   버전 3.4에서 변경: 이 메서드는 이제 "ssl.SSLContext.check_hostname"
   과 *서버 이름 표시(Server Name Indication)*로 호스트명 확인을 지원
   합니다 ("ssl.HAS_SNI"를 참조하십시오).

FTP_TLS.ccc()

   제어 채널을 일반 텍스트로 되돌립니다. 고정 포트를 열지 않고 비보안
   FTP로 NAT을 다루는 방법을 알고 있는 방화벽을 활용하는 데 유용할 수
   있습니다.

   버전 3.3에 추가.

FTP_TLS.prot_p()

   보안 데이터 연결을 설정합니다.

FTP_TLS.prot_c()

   일반 텍스트 데이터 연결을 설정합니다.
