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

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

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

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

**RFC 2640**에 따라, 기본 인코딩은 UTF-8입니다.

가용성: not WASI.

이 모듈은 웹어셈블리에서 작동하지 않거나 제공되지 않습니다. 자세한 내
용은 웹어셈블리 플랫폼을 참조하세요.

Here's a sample session using the "ftplib" module:

   >>> from ftplib import FTP
   >>> ftp = FTP('ftp.us.debian.org')  # 기본 포트로 호스트에 연결합니다
   >>> ftp.login()                     # user anonymous, passwd anonymous@
   '230 Login successful.'
   >>> ftp.cwd('debian')               # "debian" 디렉터리로 변경합니다
   '250 Directory successfully changed.'
   >>> ftp.retrlines('LIST')           # 디렉터리 내용의 목록을 얻습니다
   -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*) -- The username to log in with (default:
        "'anonymous'"). 주어지면, 생성자가 "login(host, passwd, acct)"
        를 묵시적으로 호출합니다.

      * **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*) -- "connect()"와 같은 블로킹
        연산에 대한 시간제한을 초로 지정 (기본값: 전역 기본 시간제한
        설정).

      * **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**을 따릅니다.

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

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

   set_debuglevel(level)

      인스턴스의 디버깅 수준을 "int"로 설정합니다. 인쇄되는 디버깅 출
      력의 양을 제어합니다. 디버깅 수준은 다음과 같습니다:

      * "0" (기본값): 디버깅 출력을 생성하지 않습니다.

      * "1": 적당한 양의 디버깅 출력, 일반적으로 요청당 한 줄을 생성합
        니다.

      * "2" 이상: 제어 연결에서 보내고 받는 각 줄을 로깅하여 최대량의
        디버깅 출력을 생성합니다.

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

      주어진 host와 port에 연결합니다. 이 함수는 각 인스턴스에 대해 한
      번만 호출해야 합니다; "FTP" 인스턴스를 만들 때 *host* 인자가 제
      공되었으면, 호출되지 않아야 합니다. 다른 모든 "FTP" 메서드는 연
      결이 성공적으로 이루어진 후에만 호출할 수 있습니다.

      매개변수:
         * **host** (*str*) -- 연결할 호스트.

         * **port** (*int*) -- 연결할 TCP 포트 (기본값: "21", FTP 프로
           토콜 명세에 지정된 대로). 다른 포트 번호를 지정할 필요는 거
           의 없습니다.

         * **timeout** (*float** | **None*) -- 연결 시도에 대한 시간제
           한 (기본값: 전역 기본 시간제한 설정).

         * **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='')

      연결된 FTP 서버로 로그인합니다. 이 함수는 연결이 설정된 후 각 인
      스턴스에 마다 한 번만 호출해야 합니다; "FTP" 인스턴스가 만들어질
      때 *host*와 *user* 인자가 제공되었으면 호출되지 않아야 합니다.
      대부분의 FTP 명령은 클라이언트가 로그인한 후에만 허용됩니다.

      매개변수:
         * **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()

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

   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*) -- 수신된 각 데이터 블록에 대해
           호출되는 단일 매개 변수 콜러블로, 단일 인자는 "bytes" 형의
           데이터입니다.

         * **blocksize** (*int*) -- 실제 전송을 수행하기 위해 만들어진
           저수준 "socket" 객체에서 읽을 최대 청크 크기. *callback*에
           전달되는 데이터의 최대 크기에 해당하기도 합니다. 기본값은
           "8192".

         * **rest** (*int*) -- 서버로 전송할 "REST" 명령.
           "transfercmd()" 메서드의 *rest* 매개 변수에 대한 설명서를
           참조하세요.

   retrlines(cmd, callback=None)

      초기화 때 *encoding* 매개 변수로 지정된 인코딩으로 파일이나 디렉
      터리 목록을 가져옵니다. *cmd*는 적절한 "RETR" 명령
      ("retrbinary()"를 참조하십시오)이거나 "LIST"나 "NLST"와 같은 명
      령(보통 단지 문자열 "'LIST'")이어야 합니다. "LIST"는 파일 목록과
      해당 파일에 대한 정보를 가져옵니다. "NLST"는 파일 이름 목록을 가
      져옵니다. *callback* 함수는 각 줄에 대해 호출되며, 후행 CRLF가
      제거된 줄을 포함하는 문자열을 인자로 제공합니다. 기본 *callback*
      은 줄을 "sys.stdout"으로 인쇄합니다.

   set_pasv(val)

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

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

      바이너리 전송 모드로 파일을 저장합니다.

      매개변수:
         * **cmd** (*str*) -- 적절한 "STOR" 명령: ""STOR *filename*"".

         * **fp** (*file object*) -- (바이너리 모드로 열린) 파일 객체
           이며 저장될 데이터를 제공하기 위해 *blocksize* 크기의 블록
           으로 "read()" 메서드를 사용하여 EOF까지 읽힙니다.

         * **blocksize** (*int*) -- 읽기 블록 크기. 기본값은 "8192".

         * **callback** (*callable*) -- 전송된 각 데이터 블록에 대해
           호출되는 단일 매개 변수 콜러블로, 단일 인자는 "bytes" 형의
           데이터입니다.

         * **rest** (*int*) -- 서버로 전송할 "REST" 명령.
           "transfercmd()" 메서드의 *rest* 매개 변수에 대한 설명서를
           참조하세요.

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

   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*
      인자에 의해 제한될 수 있지만, 서버가 요청된 모든 사실을 반환한다
      고 보장하지는 않습니다.

      Added in version 3.3.

   nlst(argument[, ...])

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

      참고:

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

   dir(argument[, ...])

      "LIST" 명령이 반환한 디렉터리 목록을 생성하여 표준 출력으로 인쇄
      합니다. 선택적 *argument*는 나열할 디렉터리입니다 (기본값은 현재
      서버 디렉터리입니다). 비표준 옵션을 "LIST" 명령에 전달하기 위해
      여러 인자를 사용할 수 있습니다. 마지막 인자가 함수면,
      "retrlines()"와 같이 *callback* 함수로 사용됩니다; 기본값은
      "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" 서브 클
   래스. 인증하기 전에 FTP 제어 연결을 묵시적으로 보안을 유지하면서 포
   트 21에 연결합니다.

   참고:

     사용자는 "prot_p()" 메서드를 호출하여 데이터 연결을 명시적으로 보
     호해야 합니다.

   매개변수:
      * **host** (*str*) -- 연결할 호스트명. 주어지면, 생성자가
        "connect(host)"를 묵시적으로 호출합니다.

      * **user** (*str*) -- The username to log in with (default:
        "'anonymous'"). 주어지면, 생성자가 "login(host, passwd, acct)"
        를 묵시적으로 호출합니다.

      * **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") -- SSL 구성 옵션, 인증서 및 개
        인 키를 잠재적으로 오래 유지되는 단일 구조로 묶을 수 있는 SSL
        컨텍스트 객체. 모범 사례를 보려면 보안 고려 사항을 읽으십시오.

      * **timeout** (*float** | **None*) -- "connect()"와 같은 블로킹
        연산에 대한 시간제한을 초로 지정 (기본값: 전역 기본 시간제한
        설정)

      * **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'").

   Added in version 3.2.

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

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

   버전 3.9에서 변경: *timeout* 매개 변수가 0으로 설정되면, 비 블로킹
   소켓이 만들어지지 않도록 "ValueError"를 발생시킵니다. *encoding* 매
   개 변수가 추가되었으며, 기본값은 Latin-1 에서 UTF-8로 변경되어
   **RFC 2640**을 따릅니다.

   버전 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을 다루는 방법을 알고 있는 방화벽을 활용하는 데 유용
      할 수 있습니다.

      Added in version 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(File Transfer Protocol)의 응답 규격(즉, 1--5 범위의
   숫자로 시작)에 맞지 않는 응답을 수신할 때 발생하는 예외.

ftplib.all_errors

   "FTP" 인스턴스의 메서드가 (호출자로 인한 프로그래밍 에러가 아니라)
   FTP 연결 문제로 인해 발생시킬 수 있는 모든 예외의 집합 (튜플). 이
   집합에는 위에 나열된 네 가지 예외뿐만 아니라 "OSError"와 "EOFError"
   가 포함됩니다.

더 보기:

  모듈 "netrc"
     ".netrc" 파일 형식의 구문 분석기. ".netrc" 파일은 일반적으로 FTP
     클라이언트가 사용자에게 프롬프트 하기 전에 사용자 인증 정보를 로
     드하는 데 사용됩니다.
