# `ftplib` — FTP protocol client

Вихідний код: Lib/ftplib.py

Цей модуль визначає клас `FTP` і кілька пов’язаних елементів. Клас `FTP` реалізує клієнтську сторону протоколу FTP. Ви можете використовувати це для написання програм на Python, які виконують різноманітні автоматизовані завдання FTP, такі як віддзеркалення інших серверів FTP. Він також використовується модулем `urllib.request` для обробки URL-адрес, які використовують FTP. Додаткову інформацію про FTP (протокол передачі файлів) див. в Інтернеті RFC 959.

Стандартне кодування – UTF-8, наступне RFC 2640.

Ось зразок сеансу з використанням модуля `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.'

The module defines the following items:

class `ftplib.``FTP`(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

  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. The encoding parameter specifies the encoding for directories and filenames.

  Клас `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 дорівнює нулю, це викличе `ValueError`, щоб запобігти створенню неблокуючого сокета. Параметр encoding було додано, а значення за замовчуванням змінено з Latin-1 на UTF-8 на RFC 2640.

class `ftplib.``FTP_TLS`(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')

  A `FTP` subclass which adds TLS support to FTP as described in RFC 4217. Connect as usual to port 21 implicitly securing the FTP control connection before authenticating. Securing the data connection requires the user to explicitly ask for it by calling the `prot_p()` method. context is a `ssl.SSLContext` object which allows bundling SSL configuration options, certificates and private keys into a single (potentially long-lived) structure. Please read Міркування безпеки for best practices.

  keyfile and certfile are a legacy alternative to context – they can point to PEM-formatted private key and certificate chain files (respectively) for the SSL connection.

  Нове в версії 3.2.

  Змінено в версії 3.3: Додано параметр source_address.

  Змінено в версії 3.4: The class now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `ssl.HAS_SNI`).

  Застаріло починаючи з версії 3.6: keyfile and certfile are deprecated in favor of context. Please use `ssl.SSLContext.load_cert_chain()` instead, or let `ssl.create_default_context()` select the system’s trusted CA certificates for you.

  Змінено в версії 3.9: Якщо параметр timeout дорівнює нулю, це викличе `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']

exception `ftplib.``error_reply`

  Виняток виникає, коли від сервера надходить неочікувана відповідь.

exception `ftplib.``error_temp`

  Виняток виникає, коли отримано код помилки, що означає тимчасову помилку (коди відповіді в діапазоні 400–499).

exception `ftplib.``error_perm`

  Виняток виникає, коли отримано код помилки, який означає постійну помилку (коди відповіді в діапазоні 500–599).

exception `ftplib.``error_proto`

  Виняток виникає, коли відповідь, отримана від сервера, не відповідає специфікаціям відповіді протоколу передачі файлів, тобто починається з цифри в діапазоні 1–5.

`ftplib.``all_errors`

  Набір усіх винятків (у вигляді кортежу), які методи екземплярів `FTP` можуть викликати в результаті проблем із з’єднанням FTP (на відміну від програмних помилок, зроблених абонентом). Цей набір включає чотири винятки, перелічені вище, а також `OSError` і `EOFError`.

Дивись також

Модуль `netrc`

  Парсер для формату файлу `.netrc`. Файл `.netrc` зазвичай використовується FTP-клієнтами для завантаження інформації про автентифікацію користувача перед запитом користувача.

## FTP Objects

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

Екземпляри `FTP` мають такі методи:

`FTP.``set_debuglevel`(level)

  Set the instance’s debugging level. This controls the amount of debugging output printed. The default, `0`, produces no debugging output. A value of `1` produces a moderate amount of debugging output, generally a single line per request. A value of `2` or higher produces the maximum amount of debugging output, logging each line sent and received on the control connection.

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

  Connect to the given host and port. The default port number is `21`, as specified by the FTP protocol specification. It is rarely needed to specify a different port number. This function should be called only once for each instance; it should not be called at all if a host was given when the instance was created. All other methods can only be used after a connection has been made. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If no timeout is passed, 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.

  Викликає подію аудиту `ftplib.connect` з аргументами `self`, `host`, `port`.

  Змінено в версії 3.3: Додано параметр source_address.

`FTP.``getwelcome`()

  Повернути вітальне повідомлення, надіслане сервером у відповідь на початкове підключення. (Це повідомлення іноді містить застереження або довідкову інформацію, яка може бути актуальною для користувача.)

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

  Log in as the given user. The passwd and acct parameters are optional and default to the empty string. If no user is specified, it defaults to `'anonymous'`. If user is `'anonymous'`, the default passwd is `'anonymous@'`. This function should be called only once for each instance, after a connection has been established; it should not be called at all if a host and user were given when the instance was created. Most FTP commands are only allowed after the client has logged in. The acct parameter supplies «accounting information»; few systems implement this.

`FTP.``abort`()

  Перервати передачу файлу, що триває. Використання цього не завжди працює, але варто спробувати.

`FTP.``sendcmd`(cmd)

  Надішліть простий рядок команди на сервер і поверніть рядок відповіді.

  Викликає подію аудиту `ftplib.sendcmd` з аргументами `self`, `cmd`.

`FTP.``voidcmd`(cmd)

  Send a simple command string to the server and handle the response. Return nothing if a response code corresponding to success (codes in the range 200–299) is received. Raise `error_reply` otherwise.

  Викликає подію аудиту `ftplib.sendcmd` з аргументами `self`, `cmd`.

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

  Retrieve a file in binary transfer mode. cmd should be an appropriate `RETR` command: `'RETR filename'`. The callback function is called for each block of data received, with a single bytes argument giving the data block. The optional blocksize argument specifies the maximum chunk size to read on the low-level socket object created to do the actual transfer (which will also be the largest size of the data blocks passed to callback). A reasonable default is chosen. rest means the same thing as in the `transfercmd()` method.

`FTP.``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 (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 має значення true, інакше вимкніть пасивний режим. Пасивний режим увімкнено за замовчуванням.

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

  Store a file in binary transfer mode. cmd should be an appropriate `STOR` command: `"STOR filename"`. fp is 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. The blocksize argument defaults to 8192. callback is an optional single parameter callable that is called on each block of data after it is sent. rest means the same thing as in the `transfercmd()` method.

  Змінено в версії 3.2: rest parameter added.

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

  Зберігайте файл у рядковому режимі. cmd має бути відповідною командою `STOR` (див. `storbinary()`). Рядки зчитуються до EOF з file object fp (відкритого у двійковому режимі) за допомогою його методу `readline()` для надання даних для збереження. callback — необов’язковий єдиний параметр, який викликається в кожному рядку після надсилання.

`FTP.``transfercmd`(cmd, rest=None)

  Ініціювати передачу через з’єднання даних. Якщо передача активна, надішліть команду `EPRT` або `PORT` і команду передачі, визначену cmd, і прийміть з’єднання. Якщо сервер пасивний, надішліть команду `EPSV` або `PASV`, підключіться до нього та запустіть команду передачі. У будь-якому випадку поверніть розетку для підключення.

  Якщо вказано необов’язковий rest, команда `REST` надсилається на сервер, передаючи rest як аргумент. rest зазвичай є зміщенням байтів у запитуваному файлі, повідомляючи серверу перезапустити надсилання байтів файлу із запитаним зміщенням, пропускаючи початкові байти. Однак зауважте, що метод `transfercmd()` перетворює rest на рядок із параметром encoding, указаним під час ініціалізації, але перевірка вмісту рядка не виконується. Якщо сервер не розпізнає команду `REST`, буде викликано виняток `error_reply`. Якщо це станеться, просто викличте `transfercmd()` без аргументу rest.

`FTP.``ntransfercmd`(cmd, rest=None)

  Подібно до `transfercmd()`, але повертає кортеж з’єднання даних і очікуваний розмір даних. Якщо очікуваний розмір не вдалося обчислити, як очікуваний розмір буде повернено «Немає». cmd і rest означають те саме, що й у `transfercmd()`.

`FTP.``mlsd`(path='', facts=[])

  Перерахуйте каталог у стандартизованому форматі за допомогою команди `MLSD` (RFC 3659). Якщо шлях опущено, передбачається поточний каталог. факти — це список рядків, що представляють тип бажаної інформації (наприклад, `["тип", "розмір", "перм"]`). Повертає об’єкт-генератор, утворюючи кортеж із двох елементів для кожного файлу, знайденого на шляху. Перший елемент – ім’я файлу, другий – словник, що містить інформацію про ім’я файлу. Вміст цього словника може бути обмежений аргументом факти, але сервер не гарантує повернення всіх запитуваних фактів.

  Нове в версії 3.3.

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

  Повертає список імен файлів, які повертає команда `NLST`. Необов’язковий аргумент — це каталог для переліку (за замовчуванням — це поточний каталог сервера). Для передачі нестандартних параметрів команді `NLST` можна використовувати кілька аргументів.

  Примітка

  Якщо ваш сервер підтримує команду, `mlsd()` пропонує кращий API.

`FTP.``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 the `LIST` command. If the last argument is a function, it is used as a callback function as for `retrlines()`; the default prints to `sys.stdout`. This method returns `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 Objects

`FTP_TLS` class inherits from `FTP`, defining these additional objects:

`FTP_TLS.``ssl_version`

  The SSL version to use (defaults to `ssl.PROTOCOL_SSLv23`).

`FTP_TLS.``auth`()

  Налаштуйте безпечне контрольне з’єднання за допомогою TLS або SSL, залежно від того, що вказано в атрибуті `ssl_version`.

  Змінено в версії 3.4: The method now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `ssl.HAS_SNI`).

`FTP_TLS.``ccc`()

  Повернути канал керування назад до відкритого тексту. Це може бути корисним, щоб скористатися перевагами брандмауерів, які знають, як обробляти NAT із незахищеним FTP без відкриття фіксованих портів.

  Нове в версії 3.3.

`FTP_TLS.``prot_p`()

  Налаштуйте безпечне з’єднання даних.

`FTP_TLS.``prot_c`()

  Налаштуйте підключення для передачі даних у відкритому тексті.